Name: eaC66865 Date: 12/06/2002

Currently, the method comments read like this:
   PackageDoc
   -------------
   allClasses()
                Get all included classes and interfaces in the package.
   allClasses(boolean filter)
                Get all classes and interfaces in the package, filtered
                to the specified access modifier option.

    ClassDoc
    ----------
    constructors()
                Return included constructors in this class.
    constructors(boolean filter)
               Return constructors in this class, filtered to the specified
               access modifier option.

There are three issues with these APIs.

The first issue is psychological: When I see that the second method
has a filter, I read the first as being "unfiltered".

The dissonance is partly set up by the use of the word "filter". In
APIs that use strategy objects (like the APIs for directory-objects)
you use a strategy class that has a method like
boolean filter(File) {...}.
The filter returns true if the file is to be included, or false
otherwise.

That dissonance could be eliminated by renaming the parameter to
"filtered". The API then reads constructors(boolean filtered), which
more accurately reflects the boolean value as one that indicates a
state, rather than one which is labeled as though it performs an
operation.

[Note: The naming also reflects a difference in perspective. When
implementing the function, it is natural to think of the boolean as an
instruction to do the filtering. But when *using* the API, it is more
natural to think of the boolean as describing the kind of values that
are returned.]

The second issue is the use of the term "specified". In general, "the
specified X" is a conventional phrase that refers to a value passed
as a parameter. Since there is no parameter, a reader is left wondering
where and how the value is specified.

The third issue is that the comments sound very different on the
surface. One says it returns included constructors. The other says
it returns constructors filtered to a specified option. The difference
in terminology makes it unclear that the first is actually a shortcut
for constructors(true).

My stab at resolving these issues would be to make such methods
read like this:
    constructors()
               Return only the _included_ constructors in this class (the
               filtered set). Equivalent to invoking constructors(true).
    constructors(boolean filtered)
               If true, returns the _included_ constructors in this class,
               as determined by the _access modifier command-line option_.
               Otherwise, returns all constructors in this class, private,
               package-private, protected, and public, regardless
               of the access modifier.

Doug also came up with this elegant phrasing for PackageDoc.allClasses()

> > "to process only
> > the included classes and interfaces, use allClasses(true) or
> > simply allClasses(). The allClasses(false) option is used
> > to access private and package-private members that
> > must be documented, for example, on the serialized form page."

======================================================================