flex-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Harui <aha...@adobe.com>
Subject [FalconJX] Generating ASDoc
Date Tue, 11 Oct 2016 18:23:08 GMT

FlexJS currently has its ASDoc generated by calling the ASDoc tool in the
flex-sdk repo.  That's because the Falcon compiler code we got from Adobe
had no implementation of ASDoc support.  We could probably go on like this
forever, but it would be nicer to be able to have FlexJS/FalconJX not have
any dependencies on the regular Flex SDK and ASDoc represents what might
be the last dependency.  Also, I am still thinking that FlexJS may need a
"smarter" doc tool that could be written in FlexJS and run on AIR or web
that has more intelligent API filtering and searching.  And if I were to
write such a tool, it might be easier to work from JSON data than a pile
of xml or html files, which is what the current ASDoc tool does.

I spent some time looking at how to get Falcon and/or FalconJX to output
ASDoc comments into files.  Teaching Falcon to do it seemed really hard.
The Falcon code is really designed to create a SWF, not a pile of files.
It was a lot easier to get FalconJX to do it, since it already knows how
to output a pile of JS files.  So I now have code that dumps the raw ASDoc
comments in between some xml-like tags.

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

One more note:  Because of the way FalconJX is architected (thanks again
to Michael Schmalle), it is relatively simple to swap out a JSON emitter
for an XML emitter.  I will probably just do a JSON emitter for now.  If
someone really wants the XML/XSLT solution, they can work on it themselves.


View raw message