Skip to content

Commit d88f779

Browse files
hinermhinerm
committed
Move builder usage documentation to OpEnvironment
Since this is the entry point for actually using the builder it makes more sense to document there than on the class.
1 parent 464151f commit d88f779

2 files changed

Lines changed: 56 additions & 34 deletions

File tree

‎scijava/scijava-ops-api/src/main/java/org/scijava/ops/api/OpEnvironment.java‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,10 +148,64 @@ InfoChain infoChain(final String opName, final Nil<?> specialType,
148148

149149
InfoChain chainFromInfo(final OpInfo info, final Nil<?> specialType, final Hints hints);
150150

151+
/**
152+
* Entry point for convenient Op calls, providing a builder-style interface
153+
* to walk through the process step-by-step.
154+
* <br/>
155+
* The general order of specification:
156+
* <ol>
157+
* <li>The op name (and {@link Hints}, if desired)</li>
158+
* <li>The number of input(s)</li>
159+
* <li>The type or value(s) of input(s)</li>
160+
* <li>One of:
161+
* <ul>
162+
* <li>The type or value of the output</li>
163+
* <li>Which input should be modified in-place</li>
164+
* </ul>
165+
* </li>
166+
* </ol>
167+
* The first two steps are required, at a minimum. The choices you make will
168+
* determine the <i>type</i> of Op that is matched:
169+
* <ul>
170+
* <li>No inputs &rarr; <code>Producer</code> or <code>Computer</code></li>
171+
* <li>Inputs with an output <i>value</i> &rarr; <code>Computer</code></li>
172+
* <li>Inputs with an output <i>type</i> &rarr; <code>Computer</code> or <code>Function</code></li>
173+
* <li>Inputs with no output &rarr; <code>Inplace</code> or <code>Function</code> with unknown (<code>Object</code>) return</li>
174+
* </ul>
175+
* <br/>
176+
* <p>
177+
* Examples:
178+
* {@code OpEnvironment env = new DefaultOpEnvironment();}
179+
* <ul>
180+
* <li>{@code env.op("create").arity0().outType(DoubleType.class).create();} &#8212; run an Op creating an instance of the ImgLib2 {@code DoubleType}</li>
181+
* <li>{@code env.op("create").arity0().outType(Img.class).create();} &#8212; run an Op creating a raw instance of an ImgLib2 {@code Img}.</li>
182+
* <li>{@code env.op("create").arity0().outType(new Nil<Img<DoubleType>>(){}).create();} &#8212; run an Op creating an instance of an ImgLib2 {@code Img<DoubleType>}.</li>
183+
* <li>{@code env.op("math.add").arity2().inType(Integer.class, Integer.class).function();} &#8212; get an instance of an Op to add two integers together. Return type will be {@code Object}.</li>
184+
* <li>{@code env.op("math.add").arity2().input(1, 1).outType(Double.class).apply();} &#8212; run an Op combining two integers. Return type will be {@code Double}.</li>
185+
* <li>{@code env.op("math.add").arity2().input(img1, img2).output(result).compute();} &#8212; run an Op combining two images and storing the result in a pre-allocated image.</li>
186+
* <li>{@code env.op("filter.addPoissonNoise").arity1().input(img1).mutate();} &#8212; run an Op adding poisson noise to an input image.</li>
187+
* </ul>
188+
* </p>
189+
*
190+
* @param opName The name of the Op to run
191+
* @return The {@link OpBuilder} instance for builder chaining.
192+
* @throws org.scijava.ops.api.features.OpMatchingException if the Op request cannot be satisfied
193+
* @see <a href="#op-java.lang.String-org.scijava.ops.api.Hints-" title="To specify a Hints instance to use">op(String, Hints)</a>
194+
* @see OpBuilder
195+
*/
151196
default OpBuilder op(final String opName) {
152197
return new OpBuilder(this, opName);
153198
}
154199

200+
/**
201+
* As {@link #op(String)} but using a provided {@link Hints}.
202+
*
203+
* @param opName The name of the Op to run
204+
* @param hints The {@code Hints} instance to use for Op matching
205+
* @return The {@link OpBuilder} instance for builder chaining.
206+
* @throws org.scijava.ops.api.features.OpMatchingException if the Op request cannot be satisfied
207+
* @see <a href="#op-java.lang.String-" title="To use the default Hints for this OpEnvironment">op(String)</a>
208+
*/
155209
default OpBuilder op(final String opName, final Hints hints) {
156210
return new OpBuilder(this, opName, hints);
157211
}

‎scijava/scijava-ops-api/templates/main/java/org/scijava/ops/api/OpBuilder.vm‎

Lines changed: 2 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -47,48 +47,16 @@ import org.scijava.types.Types;
4747

4848
/**
4949
* Convenience class for looking up and/or executing ops using a builder
50-
* pattern. The general order of specification:
51-
* <ol>
52-
* <li>The op name</li>
53-
* <li>The number of input(s)</li>
54-
* <li>The type or value(s) of input(s)</li>
55-
* <li>One of:
56-
* <ul>
57-
* <li>The type or value of the output</li>
58-
* <li>Which input should be modified in-place</li>
59-
* </ul>
60-
* </li>
61-
* </ol>
62-
* The first two steps are required, at a minimum. The choices you make will
63-
* determine the <i>type</i> of Op that is matched:
64-
* <ul>
65-
* <li>No inputs &rarr; <code>Producer</code> or <code>Computer</code></li>
66-
* <li>Inputs with an output <i>value</i> &rarr; <code>Computer</code></li>
67-
* <li>Inputs with an output <i>type</i> &rarr; <code>Computer</code> or <code>Function</code></li>
68-
* <li>Inputs with no output &rarr; <code>Inplace</code> or <code>Function</code> with unknown (<code>Object</code>) return</li>
69-
* </ul>
50+
* pattern. Typical entry point is through {@link OpEnvironment#op(String)}
51+
* - which contains full usage information.
7052
* <br/>
71-
* <p>
7253
* Note that the intermediate builder steps use the following acronyms:
7354
* <ul>
7455
* <li><b>IV/OV:</b> Input/Output Value. Indicates instances will be used for matching; ideal if you want to directly run the matched Op, e.g. via <code>apply</code>, <code>compute</code>, <code>mutate</code> or <code>create</code> methods.</li>
7556
* <li><b>IT/OT:</b> Input/Output Types. Indicates {@code Classes} will be used for matching; matching will produce an Op instance that can then be (re)used. There are two "Type" options: raw types or {@code Nil}s. If you are matching using a parameterized type use the {@code Nil} option to preserve the type parameter.</li>
7657
* <li><b>OU:</b> Output Unknown. Indicates an output type/value has not been specified to the builder yet. The output, if any, will simply be an {@code Object}</li>
7758
* </ul>
7859
* </p>
79-
* <p>
80-
* Examples:
81-
* {@code OpEnvironment env = new DefaultOpEnvironment();}
82-
* <ul>
83-
* <li>{@code env.op("create").arity0().outType(DoubleType.class).create();} &#8212; run an Op creating an instance of the ImgLib2 {@code DoubleType}</li>
84-
* <li>{@code env.op("create").arity0().outType(Img.class).create();} &#8212; run an Op creating a raw instance of an ImgLib2 {@code Img}.</li>
85-
* <li>{@code env.op("create").arity0().outType(new Nil<Img<DoubleType>>(){}).create();} &#8212; run an Op creating an instance of an ImgLib2 {@code Img<DoubleType>}.</li>
86-
* <li>{@code env.op("math.add").arity2().inType(Integer.class, Integer.class).function();} &#8212; get an instance of an Op to add two integers together. Return type will be {@code Object}.</li>
87-
* <li>{@code env.op("math.add").arity2().input(1, 1).outType(Double.class).apply();} &#8212; run an Op combining two integers. Return type will be {@code Double}.</li>
88-
* <li>{@code env.op("math.add").arity2().input(img1, img2).output(result).compute();} &#8212; run an Op combining two images and storing the result in a pre-allocated image.</li>
89-
* <li>{@code env.op("filter.addPoissonNoise").arity1().input(img1).mutate();} &#8212; run an Op adding poisson noise to an input image.</li>
90-
* </ul>
91-
* </p>
9260
*
9361
* @author Curtis Rueden
9462
* @author Gabriel Selzer

0 commit comments

Comments
 (0)