Mailing-List: contact dev-help@flex.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@flex.apache.org
MIME-Version: 1.0
From: Josh Tynjala <joshtynjala@gmail.com>
Date: Thu, 15 Sep 2016 09:06:20 -0700
Message-ID: <CADZSWG7fZ3f6tDc5Q_o=wDSr3Nuzc-u5=JFs+nutrPUPAw4cBw@mail.gmail.com>
Subject: FlexJS asdoc Top Level classes
To: dev <dev@flex.apache.org>
Content-Type: multipart/alternative; boundary=94eb2c12354e308790053c8e0943
archived-at: Thu, 15 Sep 2016 16:07:16 -0000

--94eb2c12354e308790053c8e0943
Content-Type: text/plain; charset=UTF-8

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

--94eb2c12354e308790053c8e0943--