chiming in with a +1 on my end too. This would be fantastic. On Thu, Dec 14, 2017 at 2:51 PM, Nick Allen <n...@nickallen.org> wrote:
> +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? > > >
