Mailing-List: contact flex-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: flex-dev@incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of aharui@adobe.com designates
 64.18.1.21 as permitted sender)
From: Alex Harui <aharui@adobe.com>
To: "flex-dev@incubator.apache.org" <flex-dev@incubator.apache.org>,
        "jeffry@dot-com-it.com" <jeffry@dot-com-it.com>
Date: Wed, 4 Jan 2012 22:27:39 -0800
Subject: Re: Proposition :: ASDoc and compiler adjustments
Thread-Topic: Proposition :: ASDoc and compiler adjustments
Thread-Index: AczLS+BNjC0W0wzvTTS6lljw6zfY5AAJz7HM
Message-ID: <CB2A82DB.3918D%aharui@adobe.com>
In-Reply-To: <4F0500E3.9070203@dot-com-it.com>
Accept-Language: en-US
Content-Language: en-US
user-agent: Microsoft-Entourage/13.11.0.110726
acceptlanguage: en-US
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0

I poked around the Apache projects and found this:
http://cxf.apache.org/javadoc/latest/

If you pick the class AegisDataBinding, you will see it inherits from
java.lang.object which is not in the package list but the links point to th=
e
main javadoc at oracle.  And there is a list of methods inherited from
java.lang.Object that point back to the javadoc at oracle.

I think we might have to end up with something like that.

-Alex


On 1/4/12 5:46 PM, "Jeffry Houser" <jeffry@dot-com-it.com> wrote:

>=20
>   At some point, most every Flex Component inherits from a Flash
> component.  In my own development, I Find it hugely beneficial to be
> able to look at all the inherited methods and properties.   I often find
> properties and methods up in the hierarchy that I didn't know existed
> just by reading the docs trying to figure stuff out.  I doubt I'm the
> only one.
>=20
>   So, if at all possible, I vote that we should include those relevant
> docs.  I have no idea how Adobe generates them; but I had assumed it was
> from the source.
>=20
> On 1/4/2012 6:18 PM, Alex Harui wrote:
>> Good question.  We will have to first figure out whether we can/should. =
 I
>> would imagine that there is JavaDoc for Java-based projects in Apache th=
at
>> inherit from Java classes and the JavaDoc does not include packages not =
in
>> Apache project.  Maybe the mentors can answer.
>>=20
>> We might have to make it such that when you click the link for Sprite yo=
u
>> end up in the Adobe doc for flash.display.Sprite.
>>=20
>> I believe the ASDoc tool doesn't handle that now so it might require an
>> update.
>>=20
>> If we decide we have to have the flash.*.* packages in our ASDoc, I will=
 see
>> what we can do to contribute those files, but keep in mind they are unde=
r
>> active development so it might be better if we learn to live without the=
m.
>>=20
>> -Alex
>>=20
>>=20
>> On 1/4/12 3:07 PM, "Jeffry Houser"<jeffry@dot-com-it.com>  wrote:
>>=20
>>>    I'm curious if we'll be able to generate the full ASDocs, like what
>>> are on the Adobe site without the source code for the Flash stuff.  We
>>> can only go so far up the inheritance tree.
>>>=20
>>> On 1/4/2012 5:40 PM, Michael Schmalle wrote:
>>>> I do not have a lot of experience with the actual compiler and asdoc
>>>> tool but that has not stopped me from having fun with parsers and AST.=
 :)
>>>>=20
>>>> I am wondering if there is any interest in creating some apis in the
>>>> compiler that jive with the asdoc tool(modifying the asdoc tool). I'm
>>>> going to be looking into the source code of this tomorrow so I will
>>>> have a clear understanding of what the work would be.
>>>>=20
>>>> My idea is this; If we could allow public api in both tools that
>>>> expose themselves through java it would allow 3rd party developers and
>>>> applications that could be made to enhance the documentation process
>>>> through formatters and asdoc editor applications.
>>>>=20
>>>> This a highlevel idea but I have already written such an application
>>>> using the jasblocks and asblocks AST framework, that are used to
>>>> create a user interface into creating asdoc comments and such through
>>>> visual editing of descriptions and tags.
>>>>=20
>>>> No more typing  /** ... */ is what I mean, the editor using the AST
>>>> reinserts the comment using tokens.
>>>>=20
>>>> I have found taking the actual documentation process out of the IDE's
>>>> code view allows for better documentation and actual revelation that
>>>> creating great docs can be fun.
>=20

--=20
Alex Harui
Flex SDK Team
Adobe Systems, Inc.
http://blogs.adobe.com/aharui