metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matt Foley <ma...@apache.org>
Subject Re: [DISCUSS] Stellar Documentation Autogeneration
Date Thu, 14 Dec 2017 23:21:20 GMT
+1 from me too, Justin.  Great idea.


On 12/14/17, 12:44 PM, "Zeolla@GMail.com" <zeolla@gmail.com> wrote:

    A huge +1 from me.  This would be great
    
    On Thu, Dec 14, 2017 at 3:39 PM Michael Miklavcic <
    michael.miklavcic@gmail.com> wrote:
    
    > +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?
    > >
    >
    -- 
    
    Jon
    



Mime
View raw message