metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Otto Fowler <ottobackwa...@gmail.com>
Subject Re: [DISCUSS] Stellar Documentation Autogeneration
Date Thu, 14 Dec 2017 20:00:18 GMT
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 (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