metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Miklavcic <michael.miklav...@gmail.com>
Subject Re: [DISCUSS] Stellar Documentation Autogeneration
Date Thu, 14 Dec 2017 20:39:46 GMT
+1 from me, great idea Justin. I did a bit of digging around also and the
Doclet approach you're already using seems the way to go. I didn't come
across any libraries that would make this easier or better. Not sure if
Swagger has anything along these lines?

On Thu, Dec 14, 2017 at 1:00 PM, Otto Fowler <ottobackwards@gmail.com>
wrote:

> 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