metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Miklavcic <>
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 <>

> 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 (
> 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
> 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?

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