You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flex.apache.org by Alex Harui <ah...@adobe.com> on 2016/10/11 18:23:08 UTC
[FalconJX] Generating ASDoc
Hi,
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
solution.
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.
Thoughts?
-Alex
Re: [FalconJX] Generating ASDoc
Posted by Josh Tynjala <jo...@gmail.com>.
According to MDN and caniuse, IE 10 supports the history API.
https://developer.mozilla.org/en-US/docs/Web/API/History_API
http://caniuse.com/#feat=history
On caniuse, sometimes supported versions are hidden because they aren't
widely used anymore. It may look like IE 11 is the minimum version when you
first load the page, but they're saying that since IE 10 has 0.3%
marketshare, it doesn't matter anymore. Click Show All to see everything..
- Josh
On Tue, Oct 11, 2016 at 1:36 PM, Alex Harui <ah...@adobe.com> wrote:
>
>
> On 10/11/16, 1:10 PM, "Josh Tynjala" <jo...@gmail.com> wrote:
>
> >Anchors could probably be acceptable as a starting point in a minimum
> >viable product. That wouldn't need the server-side integration. However,
> >you don't need to use anchors with the HTML history API. Calling
> >pushState() changes the address bar without reloading.
>
> Cool! Didn't know about pushState. Is it true it doesn't work in IE<11?
>
> Having different implementations like this is why we are pushing on the
> whole beads & multiple-component-set support. There is rarely only one
> way to do things.
>
> Thanks,
> -Alex
>
>
Re: [FalconJX] Generating ASDoc
Posted by Alex Harui <ah...@adobe.com>.
On 10/11/16, 1:10 PM, "Josh Tynjala" <jo...@gmail.com> wrote:
>Anchors could probably be acceptable as a starting point in a minimum
>viable product. That wouldn't need the server-side integration. However,
>you don't need to use anchors with the HTML history API. Calling
>pushState() changes the address bar without reloading.
Cool! Didn't know about pushState. Is it true it doesn't work in IE<11?
Having different implementations like this is why we are pushing on the
whole beads & multiple-component-set support. There is rarely only one
way to do things.
Thanks,
-Alex
Re: [FalconJX] Generating ASDoc
Posted by Josh Tynjala <jo...@gmail.com>.
Anchors could probably be acceptable as a starting point in a minimum
viable product. That wouldn't need the server-side integration. However,
you don't need to use anchors with the HTML history API. Calling
pushState() changes the address bar without reloading.
- Josh
On Tue, Oct 11, 2016 at 12:26 PM, Alex Harui <ah...@adobe.com> wrote:
>
>
> On 10/11/16, 12:14 PM, "Josh Tynjala" <jo...@gmail.com> wrote:
>
> >Search engine compatibility is one of the most basic requirements of
> >documentation, in my opinion. If you can't find a
> >component/property/method
> >from Google, it's not very useful. I guess Google's crawler will run
> >JavaScript, though. With that in mind, maybe a non-static app can be used
> >for the API reference and still be indexed.
>
> I completely agree that ASDoc must be searchable. I don't know how folks
> solve this problem, but IMO, it isn't limited to ASDoc. Any RIA, written
> in Flex or not, like a shopping catalog, wants to be indexed by search
> engines. Does anybody know what the popular solutions are? Whatever they
> are, we want to try to package that as a component, so others can use it.
>
> >
> >I think to do this right, the app needs to use the HTML history API. The
> >URL should update as you navigate to pages for different components, and
> >the back button needs to work too. Additionally, you need to be able to
> >copy-paste a URL and be able to return to the same content later. That
> >means that the server needs to know that each of these URLs should load
> >the
> >exact same HTML. The JavaScript can figure out which JSON content to load.
> >
> >example.com/docs/
> >example.com/docs/com.example.SomeComponent/
> >example.com/docs/com.example.AnotherComponent/
>
> Yep, and we will need to component-ize such functionality for our
> downstream developers.
>
> >
> >I know on Apache server, an .htaccess file gives you the ability to
> >rewrite
> >URLs and load different content. In the example above, you might add one
> >in
> >the docs folder that tells it to always load example.com/docs/index.html
> >as
> >long as the request isn't for CSS/JSON/images.
>
> Again, I don't know what the popular solutions are. Hopefully we have
> some knowledgable people in our community. IIRC, for regular Flex, we
> used anchors instead of sub-directories, so the browser address bar showed:
>
> example.com/docs/index.html
> example.com/docs/index.html#com.example.SomeComponent/
> example.com/docs/index.html#com.example.AnotherComponent/
>
> I think you have to use anchors so the page isn't re-loaded. But whatever
> solution(s) is popular, we want to encapsulate it for other app developers.
>
>
> -Alex
>
>
Re: [FalconJX] Generating ASDoc
Posted by Alex Harui <ah...@adobe.com>.
On 10/11/16, 12:14 PM, "Josh Tynjala" <jo...@gmail.com> wrote:
>Search engine compatibility is one of the most basic requirements of
>documentation, in my opinion. If you can't find a
>component/property/method
>from Google, it's not very useful. I guess Google's crawler will run
>JavaScript, though. With that in mind, maybe a non-static app can be used
>for the API reference and still be indexed.
I completely agree that ASDoc must be searchable. I don't know how folks
solve this problem, but IMO, it isn't limited to ASDoc. Any RIA, written
in Flex or not, like a shopping catalog, wants to be indexed by search
engines. Does anybody know what the popular solutions are? Whatever they
are, we want to try to package that as a component, so others can use it.
>
>I think to do this right, the app needs to use the HTML history API. The
>URL should update as you navigate to pages for different components, and
>the back button needs to work too. Additionally, you need to be able to
>copy-paste a URL and be able to return to the same content later. That
>means that the server needs to know that each of these URLs should load
>the
>exact same HTML. The JavaScript can figure out which JSON content to load.
>
>example.com/docs/
>example.com/docs/com.example.SomeComponent/
>example.com/docs/com.example.AnotherComponent/
Yep, and we will need to component-ize such functionality for our
downstream developers.
>
>I know on Apache server, an .htaccess file gives you the ability to
>rewrite
>URLs and load different content. In the example above, you might add one
>in
>the docs folder that tells it to always load example.com/docs/index.html
>as
>long as the request isn't for CSS/JSON/images.
Again, I don't know what the popular solutions are. Hopefully we have
some knowledgable people in our community. IIRC, for regular Flex, we
used anchors instead of sub-directories, so the browser address bar showed:
example.com/docs/index.html
example.com/docs/index.html#com.example.SomeComponent/
example.com/docs/index.html#com.example.AnotherComponent/
I think you have to use anchors so the page isn't re-loaded. But whatever
solution(s) is popular, we want to encapsulate it for other app developers.
-Alex
Re: [FalconJX] Generating ASDoc
Posted by Josh Tynjala <jo...@gmail.com>.
Search engine compatibility is one of the most basic requirements of
documentation, in my opinion. If you can't find a component/property/method
from Google, it's not very useful. I guess Google's crawler will run
JavaScript, though. With that in mind, maybe a non-static app can be used
for the API reference and still be indexed.
I think to do this right, the app needs to use the HTML history API. The
URL should update as you navigate to pages for different components, and
the back button needs to work too. Additionally, you need to be able to
copy-paste a URL and be able to return to the same content later. That
means that the server needs to know that each of these URLs should load the
exact same HTML. The JavaScript can figure out which JSON content to load.
example.com/docs/
example.com/docs/com.example.SomeComponent/
example.com/docs/com.example.AnotherComponent/
I know on Apache server, an .htaccess file gives you the ability to rewrite
URLs and load different content. In the example above, you might add one in
the docs folder that tells it to always load example.com/docs/index.html as
long as the request isn't for CSS/JSON/images.
- Josh
On Tue, Oct 11, 2016 at 11:23 AM, Alex Harui <ah...@adobe.com> wrote:
> Hi,
>
> 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
> solution.
>
> 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.
>
> Thoughts?
> -Alex
>
>
AW: [FalconJX] Generating ASDoc
Posted by Christofer Dutz <ch...@c-ware.de>.
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 <ah...@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" <ja...@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.
>
Re: [FalconJX] Generating ASDoc
Posted by Alex Harui <ah...@adobe.com>.
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" <ja...@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.
>
Re: [FalconJX] Generating ASDoc
Posted by Jason Guild <ja...@alaska.gov>.
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.