About @private in comments

[Carlos Rovira <ca...@apache.org>]

Hi,

this is tiny, but I'm asking me for years...in old FlexSDK and now in
FlexJS code is full of @private comments in places where even the property
decorated is not private.
I always wonder what's the reason behind this, since I think not only makes
the code bloated with lines, but moreover this lines are not rightly
assigned.

Maybe I'm missing something and this respond to something with sense.

Thanks

-- 
Carlos Rovira
http://about.me/carlosrovira

Re: About @private in comments

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

On 10/17/16, 1:03 AM, "carlos.rovira@gmail.com on behalf of Carlos Rovira"
<carlos.rovira@gmail.com on behalf of carlosrovira@apache.org> wrote:

>Hi,
>
>this is tiny, but I'm asking me for years...in old FlexSDK and now in
>FlexJS code is full of @private comments in places where even the property
>decorated is not private.
>I always wonder what's the reason behind this, since I think not only
>makes
>the code bloated with lines, but moreover this lines are not rightly
>assigned.

@private means that ASDoc should not document it.  I've wondered if there
is some way we wouldn't have to add it to the setter if you've documented
the getter.  I've been looking as ASDoc for FalconJX and it looks like
that might be possible.  It is also used so a subclass's override doesn't
have to replicate the asdoc from the base class.

@private came about because there were public properties and methods used
for internal communications between components that we didn't want
application developers to worry about.  For example in Flex, there are
lots of calls to mx_internal things that application developers don't need
to know about.

In FlexJS, because we want to use more interfaces, and there really isn't
such a thing as namespaces in JS, lots of APIs that would have been
mx_internal are now public.  Things like the element and positioner
properties probably shouldn't be fiddled with by application developers
and calls to addedToParent() should only be made by the infrastructure.
The internals of how XML and XMLList do their work should also be hidden
from application developers.  So we might use @private more, but I would
like to upgrade ASDoc to use new directives that anyone could make up, and
allow the reader to filter on those directives. So we might start adding
@framework for framework-internal public things like element and
positioner that framework developers might need to know, and XML/XMLList
could invent an @xmlinternal tag for anyone trying to maintain the XML
library, etc.

HTH,
-Alex