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.
