Skip to content

Create a Therapi-based Discoverer for Ops #77

Closed
scijava/incubator
#44

Description

@gselzer

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 op after the taglet)
  • The name under which the op will be discovered (gauss in the example)
  • The functional interface under which the op will be discovered (org.scijava.function.Computers.Arity1 in this example). Shorthands (such as Computers.Arity1 should 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 a module-info must open/export any 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

  1. added a commit that references this issue on May 2, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions