FlexJS asdoc Top Level classes

[Josh Tynjala <jo...@gmail.com>]

I was talking to someone who is using FlexJS to build an app. One thing
they mentioned is that they found it confusing that top level classes like
String, Array, etc. were not in the FlexJS asdoc, but others like QName and
Namespace were.

Now, I understand that we have custom implementations of Namespace and
QName because they don't exist in JavaScript, and the other classes are
native so we don't have classes to parse for the asdocs. However, it's
still a good point about possible confusion. Especially if you consider
that someone might be migrating an existing Flex app to FlexJS, and it's
not clear if a class isn't in the asdocs because it doesn't exist in the
new framework or for another reason.

At the very least, it might help if there were some kind of explanation
about why these classes are "missing". I think the asdoc tool supports
extended package descriptions somehow, and it might be a good idea to point
to Adobe's docs, or MDN, or somewhere that has full details about available
APIs for some of these classes. Or maybe we could create stub classes that
are only used for documentation that at least have basic descriptions.

- Josh

Re: FlexJS asdoc Top Level classes

[Josh Tynjala <jo...@gmail.com>]

Using flex-typedefs is a good idea!

I don't have time at the moment, but if I remember in a few weeks, I'll try
to take a look. If anyone else can jump in sooner, feel free.

- Josh

On Thu, Sep 15, 2016 at 3:53 PM, Alex Harui <ah...@adobe.com> wrote:

> Josh,
>
> Do you have time to work on it?  I think ASDoc just processes a set of
> source paths.  It might be possible to point a source path to the .as
> files from flex-typedefs.
>
> -Alex
>
> On 9/15/16, 9:06 AM, "Josh Tynjala" <jo...@gmail.com> wrote:
>
> >I was talking to someone who is using FlexJS to build an app. One thing
> >they mentioned is that they found it confusing that top level classes like
> >String, Array, etc. were not in the FlexJS asdoc, but others like QName
> >and
> >Namespace were.
> >
> >Now, I understand that we have custom implementations of Namespace and
> >QName because they don't exist in JavaScript, and the other classes are
> >native so we don't have classes to parse for the asdocs. However, it's
> >still a good point about possible confusion. Especially if you consider
> >that someone might be migrating an existing Flex app to FlexJS, and it's
> >not clear if a class isn't in the asdocs because it doesn't exist in the
> >new framework or for another reason.
> >
> >At the very least, it might help if there were some kind of explanation
> >about why these classes are "missing". I think the asdoc tool supports
> >extended package descriptions somehow, and it might be a good idea to
> >point
> >to Adobe's docs, or MDN, or somewhere that has full details about
> >available
> >APIs for some of these classes. Or maybe we could create stub classes that
> >are only used for documentation that at least have basic descriptions.
> >
> >- Josh
>
>

Re: FlexJS asdoc Top Level classes

[Alex Harui <ah...@adobe.com>]

Josh,

Do you have time to work on it?  I think ASDoc just processes a set of
source paths.  It might be possible to point a source path to the .as
files from flex-typedefs.

-Alex

On 9/15/16, 9:06 AM, "Josh Tynjala" <jo...@gmail.com> wrote:

>I was talking to someone who is using FlexJS to build an app. One thing
>they mentioned is that they found it confusing that top level classes like
>String, Array, etc. were not in the FlexJS asdoc, but others like QName
>and
>Namespace were.
>
>Now, I understand that we have custom implementations of Namespace and
>QName because they don't exist in JavaScript, and the other classes are
>native so we don't have classes to parse for the asdocs. However, it's
>still a good point about possible confusion. Especially if you consider
>that someone might be migrating an existing Flex app to FlexJS, and it's
>not clear if a class isn't in the asdocs because it doesn't exist in the
>new framework or for another reason.
>
>At the very least, it might help if there were some kind of explanation
>about why these classes are "missing". I think the asdoc tool supports
>extended package descriptions somehow, and it might be a good idea to
>point
>to Adobe's docs, or MDN, or somewhere that has full details about
>available
>APIs for some of these classes. Or maybe we could create stub classes that
>are only used for documentation that at least have basic descriptions.
>
>- Josh