Just to join in on the discussion ... I was consumed by the Website task for the last few days and couldn't find the time to participate here.
Are you talking about a cool bells&whistles version of ASDoc for which still the static version will be generated? Or are you thinking about dropping the static HTML version completely? I would strongly suggest not to drop this as I don't know a single Language that doesn't produce static HTML (?)Docs. I guess it would make it hard for Tool vendors to integrate anything fancy into their tools. At least simply displaying a HTML page is easy. And when thinking about Maven, usually the cool libraries "xyz.jar"(or in our case "xyz.swc") usually come with an "xyz-source.jar" that contains the sources and a "xyz-javadoc.jar" (I would reccomend to call it "javadoc" even if it's not Java as tools like IntelliJ know how to automatically handle them). Chris ________________________________ Von: Alex Harui <aha...@adobe.com> Gesendet: Mittwoch, 12. Oktober 2016 08:10:12 An: dev@flex.apache.org Betreff: Re: [FalconJX] Generating ASDoc Hi Jason, That's a pretty good assessment of the problem. Whether XML or JSON, the data set is pretty much the same: It will look like a subset of ObjectUtil.getClassInfo or describeTypeJSON. Each class and each of its members has not only the ASDoc that annotates it, but also a set of other data about whether it is read/write, private/public, static, override, dynamic, final. I'm still leaning toward JSON and writing an app instead of a tool chain. Well, the compiler's dumping of ASDoc as JSON does count as part of a tool chain, but I'm thinking the app will do all further "transformation". That way, there is hopefully straight forward Java to generate the JSON files, and MXML and AS to compute and present the data. Those 3 languages are probably better known in our community than XSLT so the gamble is that more volunteers will be able to help out. But other volunteers are certainly welcome to implement the XML/XSLT path. -Alex On 10/11/16, 3:40 PM, "Jason Guild" <jason.gu...@alaska.gov> wrote: >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. >
