[Laszlo-dev] Documenting Protected Methods

[P T Withington]

On 2008-06-24, at 17:35 EDT, Matt Wilde wrote:

> Currently, the doc tools don't generate anything for protected  
> members. This presents a difficulty in Base Classes, where it would  
> be useful for those members to be documented, since the programmer  
> might want to override one of them in a subclass.
>
> Is there a good reason to not document the protected members?

Javascript 2 will not have `protected` as an adjective, and I think we  
should follow their lead.  In Javascript 2, there is only `public` or  
not.  [There are also namespaces, and in fact, properties without a  
namespace or `public` adjective just end up in an anonymous namespace  
that is only open in the package and not nameable outside the  
package.  I know a lot of people were sold on `protected` by C++ and  
Java, but I believe the general consensus in CS these days is that the  
C++/Java concept of fine-grained access control based on classes is  
too complex to be useful.  And, `protected` doesn't really protect  
anything, so it is really no more useful than a comment or coding  
convention.]

I suggest that we create a task to go through the components and  
decide whether properties documented as protected should be public or  
not.  We also ought to create a task to change the bias of our  
documentation system to assume that properties without an explicit  
access specification are private, not public, since that is also in  
line with Javascript 2.

That's my 2p.