Skip to content

Commit 739f0a6

Browse files
hinermhinerm
authored
Merge pull request #224 from scijava/scijava-ops-tutorial/use-javadoc-declaration
Use javadoc Op declaration for Ops Tutorials
2 parents 953a54a + 2ebf162 commit 739f0a6

11 files changed

Lines changed: 111 additions & 78 deletions

File tree

‎scijava-ops-tutorial/src/main/java/module-info.java‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -59,14 +59,4 @@
5959
requires jama;
6060
requires mines.jtk;
6161

62-
provides org.scijava.ops.spi.OpCollection with
63-
org.scijava.ops.tutorial.OpAdaptation,
64-
org.scijava.ops.tutorial.OpConversion,
65-
org.scijava.ops.tutorial.OpDependencies,
66-
org.scijava.ops.tutorial.OpParallelization,
67-
org.scijava.ops.tutorial.OpPriorities,
68-
org.scijava.ops.tutorial.OpReduction,
69-
org.scijava.ops.tutorial.ReportingProgress,
70-
org.scijava.ops.tutorial.UsingNils,
71-
org.scijava.ops.tutorial.WritingOpCollections;
7262
}

‎scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpAdaptation.java‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,13 +52,17 @@
5252
* Below, we can see how this works by calling the above Field Op, supposed to
5353
* work on Doubles, on an array of Doubles[]
5454
*/
55-
public class OpAdaptation implements OpCollection {
55+
public class OpAdaptation {
5656

5757
/**
5858
* A simple Op, written as a {@link Field}, that performs a simple
5959
* calculation.
60+
*
61+
* @input a the first {@code Double}
62+
* @input b the second {@code Double}
63+
* @output a linear combination of {@code a} and {@code b}
64+
* @implNote op names="tutorial.adapt"
6065
*/
61-
@OpField(names = "tutorial.adapt")
6266
public final BiFunction<Double, Double, Double> fieldOp = (a, b) -> {
6367
return a * 2 + b;
6468
};

‎scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpConversion.java‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,13 +72,17 @@
7272
* Below, we can see how this works by calling the below Field Op, implemented
7373
* for {@link Double}s, with {@link Integer} arguments
7474
*/
75-
public class OpConversion implements OpCollection {
75+
public class OpConversion {
7676

7777
/**
7878
* A simple Op, written as a {@link Field}, that performs a simple
7979
* calculation.
80+
*
81+
* @input a the first {@link Double}
82+
* @input b the second {@link Double}
83+
* @output a linear combination of {@code a} and {@code b}
84+
* @implNote op names="tutorial.conversion"
8085
*/
81-
@OpField(names = "tutorial.conversion")
8286
public final BiFunction<Double, Double, Double> fieldOp = (a, b) -> {
8387
return a * 2 + b;
8488
};

‎scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpDependencies.java‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,28 +44,39 @@
4444
*
4545
* @author Gabriel Selzer
4646
*/
47-
public class OpDependencies implements OpCollection {
47+
public class OpDependencies {
4848

4949
/**
5050
* An Op that computes the size of a {@link double[]}
51+
*
52+
* @param inArray the input
53+
* @return the size of {@code inArray}
54+
* @implNote op names="stats.size"
5155
*/
52-
@OpMethod(names = "stats.size", type = Function.class)
5356
public static double size(final double[] inArray) {
5457
return inArray.length;
5558
}
5659

5760
/**
5861
* An Op that computes the sum of a {@link double[]}
62+
*
63+
* @param inArray the input
64+
* @return the sum of {@code inArray}
65+
* @implNote op names="stats.sum"
5966
*/
60-
@OpMethod(names = "stats.sum", type = Function.class)
6167
public static double sum(final double[] inArray) {
6268
return Arrays.stream(inArray).sum();
6369
}
6470

6571
/**
6672
* An Op that computes the mean of a {@link double[]}
73+
*
74+
* @param sumOp an Op that computes the sum of the a {@link double[]}
75+
* @param sizeOp an Op that computes the size of the a {@link double[]}
76+
* @param inArray the input
77+
* @return the mean of {@code inArray}
78+
* @implNote op names="stats.mean"
6779
*/
68-
@OpMethod(names = "stats.mean", type = Function.class)
6980
public static double mean( //
7081
@OpDependency(name = "stats.sum") Function<double[], Double> sumOp, //
7182
@OpDependency(name = "stats.size") Function<double[], Double> sizeOp, //

‎scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpParallelization.java‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,9 @@ public class OpParallelization implements OpCollection {
5757
* framework assume the burden of parallelization
5858
*
5959
* @param input the input pixel
60-
* @param output the preallocated output pixel
60+
* @param output the preallocated output pixel (container)
61+
* @implNote op names="tutorial.invertPerPixel"
6162
*/
62-
@OpMethod(names = "tutorial.invertPerPixel", type = Computers.Arity1.class)
6363
public static void invertOp(UnsignedByteType input, UnsignedByteType output) {
6464
output.set(255 - input.get());
6565
}
@@ -69,10 +69,9 @@ public static void invertOp(UnsignedByteType input, UnsignedByteType output) {
6969
* framework assume the burden of parallelization
7070
*
7171
* @param input the input pixel
72-
* @param output the preallocated output pixel
72+
* @param output the preallocated output pixel (container)
73+
* @implNote op names="tutorial.neighborhoodAverage"
7374
*/
74-
@OpMethod(names = "tutorial.neighborhoodAverage",
75-
type = Computers.Arity1.class)
7675
public static void averageNeighborhood(Neighborhood<UnsignedByteType> input,
7776
UnsignedByteType output)
7877
{

‎scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpPriorities.java‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,15 @@
4747
*
4848
* @author Gabriel Selzer
4949
*/
50-
public class OpPriorities implements OpCollection {
50+
public class OpPriorities {
5151

52-
@OpField(names = "tutorial.priority")
52+
/**
53+
* An Op with default priority.
54+
*
55+
* @input n
56+
* @output
57+
* @implNote op names="tutorial.priority"
58+
*/
5359
public final Function<Iterable<Integer>, String> iterableFunc = //
5460
n -> {
5561
int max = Integer.MIN_VALUE;
@@ -59,7 +65,13 @@ public class OpPriorities implements OpCollection {
5965
return "This maximum (Iterable Op): " + max;
6066
};
6167

62-
@OpField(names = "tutorial.priority", priority = Priority.HIGH)
68+
/**
69+
* An Op with high priority.
70+
*
71+
* @input n
72+
* @output
73+
* @implNote op names="tutorial.priority", priority="100.0"
74+
*/
6375
public final Function<SortedSet<Integer>, String> listFunc = //
6476
n -> "This maximum (SortedSet Op): " + n.last();
6577

‎scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/OpReduction.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@
5757
* Below, we can see how this works by calling the above Method Op, normally
5858
* requiring three parameters, with only two parameters.
5959
*/
60-
public class OpReduction implements OpCollection {
60+
public class OpReduction {
6161

6262
/**
6363
* An {@link Method} annotated to be an Op.
@@ -66,8 +66,8 @@ public class OpReduction implements OpCollection {
6666
* @param in2 the second input. OPTIONAL.
6767
* @param in3 the third input. OPTIONAL.
6868
* @return the sum of the passed numbers.
69+
* @implNote op names="tutorial.reduce"
6970
*/
70-
@OpMethod(names = "tutorial.reduce", type = Functions.Arity3.class)
7171
public static Double nullableMethod(Double in1, @Nullable Double in2,
7272
@Nullable Double in3)
7373
{

‎scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/ReportingProgress.java‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -73,9 +73,15 @@
7373
*
7474
* @author Gabriel Selzer
7575
*/
76-
public class ReportingProgress implements OpCollection {
77-
78-
@OpField(names = "tutorial.long.op")
76+
public class ReportingProgress {
77+
78+
/**
79+
* An Op that reports its progress while finding prime numbers.
80+
*
81+
* @input numPrimes the quantity of unique prime numbers to find
82+
* @output a {@link List} of prime numbers
83+
* @implNote op names="tutorial.long.op"
84+
*/
7985
public final Function<Integer, List<Long>> primes = numPrimes -> {
8086
var primes = new ArrayList<Long>();
8187
long val = 1, sqrt;

‎scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/UsingNils.java‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,19 +51,23 @@
5151
*
5252
* @author Gabriel Selzer
5353
*/
54-
public class UsingNils implements OpCollection {
54+
public class UsingNils {
5555

5656
/**
5757
* This Op returns a 10x10 image of unsigned bytes
58+
*
59+
* @output
60+
* @implNote op names="tutorial.nils"
5861
*/
59-
@OpField(names = "tutorial.nils")
6062
public final Producer<Img<UnsignedByteType>> imgOfBytes = //
6163
() -> ArrayImgs.unsignedBytes(10, 10);
6264

6365
/**
6466
* This Op returns a 10x10 image of doubles
67+
*
68+
* @output
69+
* @implNote op names="tutorial.nils"
6570
*/
66-
@OpField(names = "tutorial.nils")
6771
public final Producer<Img<DoubleType>> imgOfDoubles = //
6872
() -> ArrayImgs.doubles(10, 10);
6973

scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/WritingOpCollections.java renamed to scijava-ops-tutorial/src/main/java/org/scijava/ops/tutorial/WritingConciseOps.java

Lines changed: 47 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -29,57 +29,71 @@
2929

3030
package org.scijava.ops.tutorial;
3131

32+
import org.scijava.ops.api.OpEnvironment;
33+
3234
import java.lang.reflect.Field;
3335
import java.lang.reflect.Method;
3436
import java.util.function.BiFunction;
3537

36-
import org.scijava.ops.api.OpEnvironment;
37-
import org.scijava.ops.spi.OpCollection;
38-
import org.scijava.ops.spi.OpField;
39-
import org.scijava.ops.spi.OpMethod;
40-
4138
/**
42-
* {@link OpCollection}s, as the name suggests, define many Ops within one
43-
* class.
44-
* <p>
45-
* There are two different types of Ops that can be written inside
46-
* {@link OpCollection}s:
47-
* <ol>
48-
* <li>{@link OpField}s are Ops written as {@code public final}
49-
* {@link Field}s.</li>
50-
* <li>{@link OpMethod}s are Ops written as {@code public static}
51-
* {@link Method}s.</li>
52-
* </ol>
53-
* Each {@link OpCollection} can contain an arbitrary number of either type of
54-
* Op.
39+
* While {@link OpTypes} shows how to write an Op as a {@link Class}, it is much
40+
* more convenient to write Ops with less code. This tutorial shows how you can
41+
* write Ops contained within {@link Field}s and {@link Method}s, leading to
42+
* less boilerplate code!
43+
*
44+
* @author Gabriel Selzer
45+
* @author Mark Hiner
46+
* @see OpTypes for information about writing Ops as {@link Class}es.
5547
*/
56-
public class WritingOpCollections implements OpCollection {
48+
public class WritingConciseOps {
5749

5850
/**
59-
* {@link OpField}s are Ops written as {@link Field}s. They <b>must</b> be:
51+
* One major benefit of Ops written as {@link Field}s is that they can use
52+
* Java's lambda syntax, maximizing expressiveness. Field Ops <b>must</b> be
53+
* {@code public} <b>and</b> {@code final}, and should define Op parameters
54+
* using the following tags:
6055
* <ul>
61-
* <li>public</li>
62-
* <li>final</li>
56+
* <li>{@code @input <name> <description>}</li> to describe a parameter named
57+
* {@code <name>} with purpose {@code <description>}
58+
* <li>{@code @container <name> <description>}</li> to describe a preallocated
59+
* output <b>container</b> parameter named {@code <name>} with purpose
60+
* {@code <description>}
61+
* <li>{@code @mutable <name> <description>}</li> to describe a <b>mutable</b>
62+
* input parameter named {@code <name>} with purpose {@code <description>}
63+
* <li>{@code @output <description}</li> to describe a lambda return with
64+
* purpose {@code <description>}
6365
* </ul>
64-
* One major benefit of {@link OpField}s is that they can use Java's lambda
65-
* syntax, maximizing expressiveness.
66+
*
67+
* @input b the base
68+
* @input e the exponent
69+
* @output the result
70+
* @implNote op names="test.opField.power"
6671
*/
67-
@OpField(names = "test.opField.power")
6872
public final BiFunction<Double, Double, Double> opFieldPower = (b, e) -> Math
6973
.pow(b, e);
7074

7175
/**
72-
* {@link OpMethod}s are Ops written as {@link Method}s. They <b>must</b> be:
76+
* Ops can additionally be written as {@link Method}s. Method Ops must be
77+
* {@code public} <b>and</b> {@code static}, and should declare their
78+
* parameters using the following tags:
7379
* <ul>
74-
* <li>public</li>
75-
* <li>static</li>
80+
* <li>{@code @param <name> <description>}</li> to describe a parameter named
81+
* {@code <name>} with purpose {@code <description>}
82+
* <li>{@code @param <name> <description> (container)}</li> to describe a
83+
* preallocated output <b>container</b> parameter named {@code <name>} with
84+
* purpose {@code <description>}
85+
* <li>{@code @param <name> <description> (mutable)}</li> to describe a
86+
* <b>mutable</b> input parameter named {@code <name>} with purpose
87+
* {@code <description>}
88+
* <li>{@code @return <description}</li> to describe a method return with
89+
* purpose {@code <description>}
7690
* </ul>
77-
* <p>
78-
* <b>In addition, Ops written as methods must specify their Op type.</b> This
79-
* tells SciJava Ops whether this function should become a Computer, an
80-
* Inplace, or something else entirely.
91+
*
92+
* @param b the base
93+
* @param e the exponent
94+
* @return the result
95+
* @implNote op names="test.opMethod.power"
8196
*/
82-
@OpMethod(names = "test.opMethod.power", type = BiFunction.class)
8397
public static Double opMethodPower(Double b, Double e) {
8498
return Math.pow(b, e);
8599
}

0 commit comments

Comments
 (0)