metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Casey Stella <ceste...@gmail.com>
Subject Re: [DISCUSS] Stellar Documentation Autogeneration
Date Thu, 14 Dec 2017 19:54:02 GMT
chiming in with a +1 on my end too.  This would be fantastic.

On Thu, Dec 14, 2017 at 2:51 PM, Nick Allen <nick@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 <justinjleet@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?
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message