I think this is a great idea, and I looked at the POC and it isn’t as bad as you make it out to be;)
What I would like to see is documentation for Stellar functions, by namespace generated. I would also like the capability to document at the namespace level. Often we have namespace level concepts that don’t fit into any given function’s documentation. Setting aside the how of the namespace documentation for a moment, based on the POC I would suggest that we * find all namespaces * create a page per namespace * document each function in it’s namespace’s page * include the namespace doc in that page Each module that exports stellar function’s should have it’s own documentation. As part of breaking stellar out to it’s own module we should remove stellar documentation from stellar common that applies to functions outside that module. On December 14, 2017 at 14:32:56, Justin Leet (justinjl...@gmail.com) wrote: I think it would be valuable to have the documentation around Stellar being autogenerated. We have most of the info we'd want in the @Stellar annotation, and ideally, we could just pull this info out and produce some docs similar to what we already manually maintain. This came up a bit in the context of https://issues.apache.org/jira/browse/METRON-1361 I put together a super, super (super!) rough POC of using the approach of Javadoc-style doclet processing that reads the annotations and kicks out something pretty close to the current docs (without any fancy stuff like the table of contents and so on). Right now, there'd be a good deal more to do that to make it usable. Off the top of my head, the main things I wanted to look at before really even taking an actual stab at it are 1) abstracting out the markdown formatting from the annotation parsing 2) Making sure we can integrate this approach without breaking current Javadocs 3) Managing things across projects (since we put in Stellar functions all over). 4) Slightly more though about how we'd manage it. Otto's alluded to having a couple thoughts, and I'm more than happy to get a better idea of what we want the end state to look like (either this or something else, e.g. an annotation processor during compile phase or if someone knows a tool that takes care of this sort of thing.) Any thoughts?
