Skip to content

Use javadoc Op declaration for Ops Tutorials #224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hinerm merged 1 commit into from
May 20, 2024
Merged

Use javadoc Op declaration for Ops Tutorials #224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 0 additions & 10 deletions scijava-ops-tutorial/src/main/java/module-info.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,14 +59,4 @@
requires jama;
requires mines.jtk;

provides org.scijava.ops.spi.OpCollection with
org.scijava.ops.tutorial.OpAdaptation,
org.scijava.ops.tutorial.OpConversion,
org.scijava.ops.tutorial.OpDependencies,
org.scijava.ops.tutorial.OpParallelization,
org.scijava.ops.tutorial.OpPriorities,
org.scijava.ops.tutorial.OpReduction,
org.scijava.ops.tutorial.ReportingProgress,
org.scijava.ops.tutorial.UsingNils,
org.scijava.ops.tutorial.WritingOpCollections;
}
8 changes: 6 additions & 2 deletions scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpAdaptation.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,17 @@
* Below, we can see how this works by calling the above Field Op, supposed to
* work on Doubles, on an array of Doubles[]
*/
public class OpAdaptation implements OpCollection {
public class OpAdaptation {

/**
* A simple Op, written as a {@link Field}, that performs a simple
* calculation.
*
* @input a the first {@code Double}
* @input b the second {@code Double}
* @output a linear combination of {@code a} and {@code b}
* @implNote op names="tutorial.adapt"
*/
@OpField(names = "tutorial.adapt")
public final BiFunction<Double, Double, Double> fieldOp = (a, b) -> {
return a * 2 + b;
};
Expand Down
8 changes: 6 additions & 2 deletions scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpConversion.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,13 +72,17 @@
* Below, we can see how this works by calling the below Field Op, implemented
* for {@link Double}s, with {@link Integer} arguments
*/
public class OpConversion implements OpCollection {
public class OpConversion {

/**
* A simple Op, written as a {@link Field}, that performs a simple
* calculation.
*
* @input a the first {@link Double}
* @input b the second {@link Double}
* @output a linear combination of {@code a} and {@code b}
* @implNote op names="tutorial.conversion"
*/
@OpField(names = "tutorial.conversion")
public final BiFunction<Double, Double, Double> fieldOp = (a, b) -> {
return a * 2 + b;
};
Expand Down
19 changes: 15 additions & 4 deletions scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpDependencies.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,28 +44,39 @@
*
* @author Gabriel Selzer
*/
public class OpDependencies implements OpCollection {
public class OpDependencies {

/**
* An Op that computes the size of a {@link double[]}
*
* @param inArray the input
* @return the size of {@code inArray}
* @implNote op names="stats.size"
*/
@OpMethod(names = "stats.size", type = Function.class)
public static double size(final double[] inArray) {
return inArray.length;
}

/**
* An Op that computes the sum of a {@link double[]}
*
* @param inArray the input
* @return the sum of {@code inArray}
* @implNote op names="stats.sum"
*/
@OpMethod(names = "stats.sum", type = Function.class)
public static double sum(final double[] inArray) {
return Arrays.stream(inArray).sum();
}

/**
* An Op that computes the mean of a {@link double[]}
*
* @param sumOp an Op that computes the sum of the a {@link double[]}
* @param sizeOp an Op that computes the size of the a {@link double[]}
* @param inArray the input
* @return the mean of {@code inArray}
* @implNote op names="stats.mean"
*/
@OpMethod(names = "stats.mean", type = Function.class)
public static double mean( //
@OpDependency(name = "stats.sum") Function<double[], Double> sumOp, //
@OpDependency(name = "stats.size") Function<double[], Double> sizeOp, //
Expand Down
9 changes: 4 additions & 5 deletions scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpParallelization.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,9 @@ public class OpParallelization implements OpCollection {
* framework assume the burden of parallelization
*
* @param input the input pixel
* @param output the preallocated output pixel
* @param output the preallocated output pixel (container)
* @implNote op names="tutorial.invertPerPixel"
*/
@OpMethod(names = "tutorial.invertPerPixel", type = Computers.Arity1.class)
public static void invertOp(UnsignedByteType input, UnsignedByteType output) {
output.set(255 - input.get());
}
Expand All @@ -69,10 +69,9 @@ public static void invertOp(UnsignedByteType input, UnsignedByteType output) {
* framework assume the burden of parallelization
*
* @param input the input pixel
* @param output the preallocated output pixel
* @param output the preallocated output pixel (container)
* @implNote op names="tutorial.neighborhoodAverage"
*/
@OpMethod(names = "tutorial.neighborhoodAverage",
type = Computers.Arity1.class)
public static void averageNeighborhood(Neighborhood<UnsignedByteType> input,
UnsignedByteType output)
{
Expand Down
18 changes: 15 additions & 3 deletions scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpPriorities.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,15 @@
*
* @author Gabriel Selzer
*/
public class OpPriorities implements OpCollection {
public class OpPriorities {

@OpField(names = "tutorial.priority")
/**
* An Op with default priority.
*
* @input n
* @output
* @implNote op names="tutorial.priority"
*/
public final Function<Iterable<Integer>, String> iterableFunc = //
n -> {
int max = Integer.MIN_VALUE;
Expand All @@ -59,7 +65,13 @@ public class OpPriorities implements OpCollection {
return "This maximum (Iterable Op): " + max;
};

@OpField(names = "tutorial.priority", priority = Priority.HIGH)
/**
* An Op with high priority.
*
* @input n
* @output
* @implNote op names="tutorial.priority", priority="100.0"
*/
public final Function<SortedSet<Integer>, String> listFunc = //
n -> "This maximum (SortedSet Op): " + n.last();

Expand Down
4 changes: 2 additions & 2 deletions scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpReduction.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@
* Below, we can see how this works by calling the above Method Op, normally
* requiring three parameters, with only two parameters.
*/
public class OpReduction implements OpCollection {
public class OpReduction {

/**
* An {@link Method} annotated to be an Op.
Expand All @@ -66,8 +66,8 @@ public class OpReduction implements OpCollection {
* @param in2 the second input. OPTIONAL.
* @param in3 the third input. OPTIONAL.
* @return the sum of the passed numbers.
* @implNote op names="tutorial.reduce"
*/
@OpMethod(names = "tutorial.reduce", type = Functions.Arity3.class)
public static Double nullableMethod(Double in1, @Nullable Double in2,
@Nullable Double in3)
{
Expand Down
12 changes: 9 additions & 3 deletions scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/ReportingProgress.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,9 +73,15 @@
*
* @author Gabriel Selzer
*/
public class ReportingProgress implements OpCollection {

@OpField(names = "tutorial.long.op")
public class ReportingProgress {

/**
* An Op that reports its progress while finding prime numbers.
*
* @input numPrimes the quantity of unique prime numbers to find
* @output a {@link List} of prime numbers
* @implNote op names="tutorial.long.op"
*/
public final Function<Integer, List<Long>> primes = numPrimes -> {
var primes = new ArrayList<Long>();
long val = 1, sqrt;
Expand Down
10 changes: 7 additions & 3 deletions scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/UsingNils.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,19 +51,23 @@
*
* @author Gabriel Selzer
*/
public class UsingNils implements OpCollection {
public class UsingNils {

/**
* This Op returns a 10x10 image of unsigned bytes
*
* @output
* @implNote op names="tutorial.nils"
*/
@OpField(names = "tutorial.nils")
public final Producer<Img<UnsignedByteType>> imgOfBytes = //
() -> ArrayImgs.unsignedBytes(10, 10);

/**
* This Op returns a 10x10 image of doubles
*
* @output
* @implNote op names="tutorial.nils"
*/
@OpField(names = "tutorial.nils")
public final Producer<Img<DoubleType>> imgOfDoubles = //
() -> ArrayImgs.doubles(10, 10);

Expand Down
80 changes: 47 additions & 33 deletions ...va/ops/tutorial/WritingOpCollections.java → ...ijava/ops/tutorial/WritingConciseOps.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,57 +29,71 @@

package org.scijava.ops.tutorial;

import org.scijava.ops.api.OpEnvironment;

import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.util.function.BiFunction;

import org.scijava.ops.api.OpEnvironment;
import org.scijava.ops.spi.OpCollection;
import org.scijava.ops.spi.OpField;
import org.scijava.ops.spi.OpMethod;

/**
* {@link OpCollection}s, as the name suggests, define many Ops within one
* class.
* <p>
* There are two different types of Ops that can be written inside
* {@link OpCollection}s:
* <ol>
* <li>{@link OpField}s are Ops written as {@code public final}
* {@link Field}s.</li>
* <li>{@link OpMethod}s are Ops written as {@code public static}
* {@link Method}s.</li>
* </ol>
* Each {@link OpCollection} can contain an arbitrary number of either type of
* Op.
* While {@link OpTypes} shows how to write an Op as a {@link Class}, it is much
* more convenient to write Ops with less code. This tutorial shows how you can
* write Ops contained within {@link Field}s and {@link Method}s, leading to
* less boilerplate code!
*
* @author Gabriel Selzer
* @author Mark Hiner
* @see OpTypes for information about writing Ops as {@link Class}es.
*/
public class WritingOpCollections implements OpCollection {
public class WritingConciseOps {

/**
* {@link OpField}s are Ops written as {@link Field}s. They <b>must</b> be:
* One major benefit of Ops written as {@link Field}s is that they can use
* Java's lambda syntax, maximizing expressiveness. Field Ops <b>must</b> be
* {@code public} <b>and</b> {@code final}, and should define Op parameters
* using the following tags:
* <ul>
* <li>public</li>
* <li>final</li>
* <li>{@code @input <name> <description>}</li> to describe a parameter named
* {@code <name>} with purpose {@code <description>}
* <li>{@code @container <name> <description>}</li> to describe a preallocated
* output <b>container</b> parameter named {@code <name>} with purpose
* {@code <description>}
* <li>{@code @mutable <name> <description>}</li> to describe a <b>mutable</b>
* input parameter named {@code <name>} with purpose {@code <description>}
* <li>{@code @output <description}</li> to describe a lambda return with
* purpose {@code <description>}
* </ul>
* One major benefit of {@link OpField}s is that they can use Java's lambda
* syntax, maximizing expressiveness.
*
* @input b the base
* @input e the exponent
* @output the result
* @implNote op names="test.opField.power"
*/
@OpField(names = "test.opField.power")
public final BiFunction<Double, Double, Double> opFieldPower = (b, e) -> Math
.pow(b, e);

/**
* {@link OpMethod}s are Ops written as {@link Method}s. They <b>must</b> be:
* Ops can additionally be written as {@link Method}s. Method Ops must be
* {@code public} <b>and</b> {@code static}, and should declare their
* parameters using the following tags:
* <ul>
* <li>public</li>
* <li>static</li>
* <li>{@code @param <name> <description>}</li> to describe a parameter named
* {@code <name>} with purpose {@code <description>}
* <li>{@code @param <name> <description> (container)}</li> to describe a
* preallocated output <b>container</b> parameter named {@code <name>} with
* purpose {@code <description>}
* <li>{@code @param <name> <description> (mutable)}</li> to describe a
* <b>mutable</b> input parameter named {@code <name>} with purpose
* {@code <description>}
* <li>{@code @return <description}</li> to describe a method return with
* purpose {@code <description>}
* </ul>
* <p>
* <b>In addition, Ops written as methods must specify their Op type.</b> This
* tells SciJava Ops whether this function should become a Computer, an
* Inplace, or something else entirely.
*
* @param b the base
* @param e the exponent
* @return the result
* @implNote op names="test.opMethod.power"
*/
@OpMethod(names = "test.opMethod.power", type = BiFunction.class)
public static Double opMethodPower(Double b, Double e) {
return Math.pow(b, e);
}
Expand Down
11 changes: 0 additions & 11 deletions scijava-ops-tutorial/src/main/resources/META-INF/services/org.scijava.ops.spi.OpCollection
View file
Open in desktop

This file was deleted.