René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Improve mechanism for documenting ops","articleBody":"It is crucial that we have a robust, simple, and integrated mechanism for documenting ops.\r\n\r\n### Documenting specific implementations\r\n\r\nOur 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:\r\n* 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](https://github.com/dnault/therapi-runtime-javadoc)\r\n* 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.\r\n\r\n### Algorithms as a whole\r\n\r\nWe 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.\r\n\r\nI 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?\r\n\r\n### Possible syntax\r\n\r\nSyntax for getting help on a specific algorithm could be:\r\n```\r\nops.op(\"math.add\").inputs(in1, in2).outputs(out).help()\r\n```\r\n\r\nSyntax for accessing the general documentation could be:\r\n```\r\nops.help(\"math.add\")\r\n```\r\nor:\r\n```\r\nops.op(\"math.add\").help()\r\n```\r\n\r\n\r\nas well as algorithms as a whole (thanks @marktsuchida for suggesting.\r\n","author":{"url":"https://github.com/ctrueden","@type":"Person","name":"ctrueden"},"datePublished":"2020-08-26T19:14:49.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":11},"url":"https://github.com/50/scijava/issues/50"}