metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Justin Leet <justinjl...@gmail.com>
Subject [DISCUSS] Stellar Documentation Autogeneration
Date Thu, 14 Dec 2017 19:32:52 GMT
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