On 10/17/16, 1:03 AM, "carlos.rov...@gmail.com on behalf of Carlos Rovira" <carlos.rov...@gmail.com on behalf of carlosrov...@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
