Alex:
The answer to this question might be "how much out-of-band metadata is
needed to properly qualify all the parts of the generated documentation?"
For instance, think about "this particular API X is not supported by
product version Y", "this API Z is internal for framework developers",
or other similar dimensional aspects.
This kind of info is would likely be used to filter, qualify, or
otherwise render differently certain parts of the documentation based on
this metadata.
It would be nice if the dynamic "documentation browser application"
being discussed right now could have some UI that allows the user to
toggle what or how documentation is seen based on selection of these
kinds of facets. That's something the old static ASDoc output could
never do: it was static and one-size-fits-all. I always wanted to know
about / read something about things marked 'mx:internal' but all of that
was excluded from the official Flex ASDoc.
If you stick with XML/XSLT, then there are all kinds of techniques to
embed this info in namespaces/tags/attributes/etc without interfering
with the actual documentation content. The toolchain is also
well-known/standard, though writing XSL can be tricky.
If you go with JSON for the output then you may need to invent ways to
encode these types of information which aren't really part of the actual
docs. And then you (or someone) gets to invent a whole new toolchain to
process the JSON into whatever the final result turns out to be.
Just my 2 cents, lurking from the shadows.
Jason
On 10/11/2016 10:23, Alex Harui wrote:
Right now I'm thinking I will change the raw output to be JSON. Or is
there a good reason to keep the old xml output? The flex-sdk ASDoc tool
takes the xml output and uses Saxon as an XSLT to generate html. Do we
want to do that? Or use Velocity or some other XSLT tool? Or is JSON the
new way to go?
If we go with JSON, we probably don't need to add these other XSLT
dependencies to Falcon/FalconJX. And the new ASDoc FlexJS app would be a
good test of our code. I remember concerns in past discussions about not
having HTML files for search engines to index, but isn't this sort of
thing a standard problem for RIAs? We probably need to have a default
solution.
