+1 I think it is a great idea, Justin and the only way that we'll keep the docs in-sync with the code.
On Thu, Dec 14, 2017 at 2:32 PM 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? >
