It is crucial that we have a robust, simple, and integrated mechanism for documenting ops.

Documenting specific implementations

Our current plan/idea is to use javadoc on the method/field/class implementing it. (It makes most sense for classes and methods; we'll need to think carefully about the best way to document parameters of lambdas assigned to fields.) The main challenge for this is that javadoc is not retained in bytecode. Possible solutions:

• An annotation processor that executes as compilation time to scrape the javadoc and record it into some metadata inside the main JAR file—e.g. therapi-runtime-javadoc
• Scraping the -javadoc classifier JAR on demand for the content. But then we'd need to download these from the remote on demand and cache them somewhere and parse it. But this could create a substantial delay the first time help is called, or upon the first op lookup failure.

Algorithms as a whole

We also need to document algorithms as a whole—e.g. what does filter.sobel do mathematically? (Thanks @marktsuchida for suggesting this.) Each filter.sobel op implementation can then lead with a link to the general algorithm documentation for overview, and then focus on any implementation-specific notes as needed.

I don't currently have a great idea where this general documentation would be placed, technically. If we do go with javadoc for documenting implementations, we would need another class somewhere per op name, which seems suboptimal. Maybe package-info.java in packages?

Possible syntax

Syntax for getting help on a specific algorithm could be:

ops.op("math.add").inputs(in1, in2).outputs(out).help()

Syntax for accessing the general documentation could be:

ops.help("math.add")

or:

ops.op("math.add").help()

as well as algorithms as a whole (thanks @marktsuchida for suggesting.