Hi Alex,
great to hear that ... being someone who still thinks the static API
documentation is important, I would like to work on a maven site mojo to
generate that static stuff. I am very experienced with XSLT, so that shouldn’t
be a problem. You mentioned, that the Falcon compiler outputs XML ... where is
that output to and what do I need to do to make him generate that?
Chris
Am 14.12.16, 18:38 schrieb "Alex Harui" <aha...@adobe.com>:
Hi,
Today I finally got enough of a FlexJS ASDoc app running to mention it on
the list, in hope that other folks can pitch in to help us finish it and
help prove that FlexJS can help folks do something useful, as well as make
it easier for folks to write code with FlexJS.
Normally, our ASDoc is published as a pile of HTML files. The regular
Flex MXMLC compiler has code that generates a pile of XML files and then
MXMLC calls into the Saxon library to apply XSLT to generate the HTML.
The Falcon codebase didn't have any of this code, but instead of copying
in the code and the Saxon dependency from flex-sdk, I chose to take a
completely different approach because I think that ASDoc for FlexJS may
need to be more interactive. There are so many more classes that have
different categorizations and different usage contexts that I want to
provide more sophisticated filtering, so users can filter down to, for
instance, "top-level components", or "view beads", etc. This is certainly
possible to do with a pile of HTML, but that would require that I and
anyone else who wants to help to learn or know XSLT. It makes more sense
to me to use ActionScript and MXML instead since everyone in this
community knows that. And turning this into a production-quality app
would force us to develop some new code that other folks will probably
want.
The source code is checked into the flex-asjs repo under
examples\flexjs\ASDoc. The apacheflexbuild CI server will re-build the
ASDoc app on any change to the flex-asjs repo, so you can see your results
here [1][2]. If you run it now, you'll see its pretty ugly. All I wanted
to get working was the ability to parse the underlying JSON files, which I
think is mostly working. It would be great to see folks pitch in to:
-make it look better
-use links for the base classes
-provide an "All classes" and "index"
-provide filters
-localization?
-maven build
-deep linking
-search engine support
And tons of other improvements. Just compare it to the current ASDoc to
see what is missing. My vision for filtering would be to allow folks to
check off a list of attributes that correlate to asdoc tags. We could
annotate all top-level components with @toplevel, and beads with @bead
and/or @viewbead and the app would offer the list of known tags and you
could check which ones you want to see or hide. I'll probably implement
the beginnings of that after I catch up on some other issues, but you
don't have to wait for me.
Hope you can find time to help,
-Alex
[1] SWF version:
http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%20ASDoc%20Example/lastS
uccessfulBuild/artifact/examples/flexjs/ASDoc/bin-debug/ASDoc.html
[2] JS Debug:
http://apacheflexbuild.cloudapp.net:8080/job/FlexJS%20ASDoc%20Example/lastS
uccessfulBuild/artifact/examples/flexjs/ASDoc/bin/js-debug/index.html
Note, the js-release version may not run since the code is currently using
lots of plain objects.
