Repository navigation
Description
Use case: imglib2-algorithm
Suppose a library's Javadocs are saved using the therapi annotation processor. Can we use the javadoc at runtime together with an OpTaglet to determine which algorithms should be wrapped into Ops, without any additional Maven dependencies?
Imglib2-algorithm algorithms would then need to declare in their javadoc:
/**
* Apply Gaussian convolution to source and write the result to output.
* In-place operation (source==target) is supported.
*
* ...
*
* @implNote op gauss org.scijava.function.Computers.Arity1
*
* @param sigma
* standard deviation of isotropic Gaussian.
* @param source
* source image, must be sufficiently padded (e.g.
* {@link Views#extendMirrorSingle(RandomAccessibleInterval)}) to
* provide values for the target interval plus a border of half
* the kernel size.
* @param target
* target image
* @param <S>
* source type
* @param <T>
* target type
* @throws IncompatibleTypeException
* if source and target type are not compatible (they must be
* either both {@link RealType RealTypes} or the same type).
*/
public static < S extends NumericType< S >, T extends NumericType< T > > void gauss( final double sigma, final RandomAccessible< S > source, final RandomAccessibleInterval< T > target ) throws IncompatibleTypeException
{
...
}In the example, we use the @implNote taglet, introduced with Java 8. Other options include @apiNote, @implSpec. This taglet will need to declare:
- That it is an op (via the
opafter the taglet) - The name under which the op will be discovered (
gaussin the example) - The functional interface under which the op will be discovered (
org.scijava.function.Computers.Arity1in this example). Shorthands (such asComputers.Arity1should also be supported).
The advantage here is zero additional dependencies (although it will require an annotation processor dependency for Ops to discover these taglets and the corresponding algorithm).
Disadvantages compared to a compile-time dependency on the Ops framework:
- The annotation interfaces (
@OpField,@OpMethod, etc) provide more type safety and discoverability in IDEs. You will not be able to search for imglib2 algorithms as they will not be declared under any annotation. You also cannot search for these ops under, for example,Function. - These annotations can be malformed and the compiler will not recognize the problem.
- This mechanism used was not originally designed for the task. It is unlikely that anyone else will not use this tag, and could conceivably break things (if Java/someone else is tuned into these tags).
- This requires that, if JPMS modules are used, every package with ops must be
opened to both therapi and some SciJava Ops-based module that parses this syntax. BUT this is a common issue; any component with amodule-infomustopen/exportany packages with algorithms designed to be called by other modules.
The annotation processor can be activated by a opt-in property <therapi.packages> in the POM. This property can include a comma-delineated set of packages to process only those packages, or left blank to include all packages.
Activity
Merge pull request #77 from scijava/imagej/imagej-ops2/copy-op-revamp