This is an umbrella RFE for the set of feature changes (CCC) for the
standard doclet for Merlin. This begins with a first set of
changes and is followed by a second and third set.

A related set of changes to the Javadoc tool can be found at
4452937: a package of related javadoc/doclet API changes
The first three items below (1.1 to 1.3) go hand-in-hand with
the Doclet API changes enabled by 4452937.

See the individual referenced bug reports for more details.
(Developers should submit their comments there.)

============= FIRST SET OF CHANGES FOR MERLIN ============================

STANDARD DOCLET:

(1.1) 4208989: Provide more information with warnings
        4396665: All warnings & errors should show responsible file

        These make javadoc errors much, much easier to track. Without this,
        you don't know which of thousands of source files an error is caused.
        Requires adding class name to the error and warning messages.
        
(1.2) 4320557: Automatically add values of static fields to generated docs

        This builds on Neal's fix to 422788: javadoc API: provide access to
        the value of constant fields. This is a very important missing part
        of the Java 2 Platform API Specification.
        We would use com.sun.javadoc.FieldDoc.constantValue()
        and com.sun.javadoc.FieldDoc.constantValueText() to write
        these values to the HTML output.
                
(1.3) 4180839: Allow serialized form to be generated in normal run of Javadoc
        4341304: Make sure writeReplace() is included in serialized form page

        These will enhance the standard doclet to make it feasible for
        developers outside the J2SE team to generate the correct
        serialized form page, allowing it to be properly generated in the
        normal run of Javadoc.
        
(1.4) 4256505: doc-files directory at doc root should be copied to
        destination.

        This enables the inclusion of overview-level documentation
        to be included in javadoc. Coping the doc-files directory
        works at the package level, just not at the top level.
 
(1.5) 4429628: Add plain text version of {@link}, such as {@linkplain}.

        This is a long-needed minor modification to the {@link}
        tag, where the label is displayed in plain text rather than code font.

(1.6) 4469119: Document @files to work with command line options as well
        as filenames - @argfile.

        This is a request to change documentation only.
        The feature @files was originally documented in javadoc and javac to
        allow only filenames, not command line options. This expands
        the documentation to say ^S^S @files also allows command line
        options. This will enable us to say that it works for -header,
        -footer, and -bottom.


============= SECOND SET OF CHANGES FOR MERLIN ============================

STANDARD DOCLET:

(2.1) 4058216: Capability to exclude classes/members (e.g. RMI stubs and
                skeletons) @docset

       The -include and -exclude options and @docset tag have been
       added to the standard doclet If "-exclude foo1:foo2" is
       used, all members, classes and packages with @docset foo1
       and/or @docset foo2 will be excluded from the standard
       doclet output. If "-include foo1:foo2" is used, ONLY
       members, classes and packages with @docset foo1 and/or
       @docset foo2 will be included in the output.

(2.2) 4217345: -quiet option to shut off non-error processing/generating
                messages (fixed)

       Only the warnings and errors will appear, making them
       much easier to find.

(2.3) 4214766: New tags for portable comments: {@class} {@parent} {@package}
               {@date} {@member]

       This enables copy/paste of comments to other classes.
       Example: /**
                 * The {@class} class is used for ...
                 * ...other classes derived from {@parent}.
                 * ...any class in the {@package} package.
                 * This was last updated on {@date MMM DD, YYYY}.
                 */

(2.4) 4359889: Option to omit qualifying package name from ahead of class
                names in output

       The current default is (on the page for class p.C) to add
       the package name only to classes not belonging to package p.
       Suggest adding -noqualifier <arg> where the argument is
       either "all" (all packages are not prepended) or a list
       of packages with wildcards to be removed as qualifiers
       (java.lang:java.awt:javax.*)

(2.5) 1242492: Add links to source code, using -src option

       We would not use this feature in the J2SE doc bundle, but
       would make it available for others to use.

(2.6) 4114089: javadoc needs to report its version

       Suggest always printing the version number in its output
       stream

(2.7) 4282805: Add tag interface for custom tags

       A developer would only have to write a class that
       tells the doclet how to handle the new tag. Could be done
       by providing an API for clients to extend the standard
       doclet, or by reorganizing the standard doclet to make it
       much easier to extend.

(2.8) 4232597: Put current class (or package) name in window title, esp.
                with frames.

       With frames off, this involves putting the class (or package)
       name first so that it will appear in the Windows task bar
       when a window is minimized. Javascript might also allow the
       name to appear in the title bar when frames are turned on.


JAVADOC TOOL:
 
(2.9) 4113483: Implement a public way to invoke javadoc from within java
                (fixed)

       Added a programmatic interface, that can be called multiple
       times in one run -- the javadoc tool and the standard doclet
       are now re-entrant.
       Part of the interface:
               public static void main(java.lang.String[] args)
               public static int execute(java.lang.String[] args)

============= THIRD SET OF CHANGES FOR MERLIN ============================

STANDARD DOCLET:

(3.1) 4359386: Include package info when passing in source filenames
                (*.java). The docs that are generated should not
                be any different when passing in package names than
                when passing in the same class names.

(3.2) 4464477: Automatically create destination directory (-d)
                Since a primary function of javadoc is to create
                files and directories, it seems reasonable to create
                the root destination directory as well.
 
(3.3) 4213984: {@insert} or {@include} reference material (source
                code, overview). These external documents that are
                copied (in-lined) by javadoc into the final documentation
                The biggest advantage may be for inserting a source file
                or snippet, which could remain in a .java file for testing

(3.4) 4186639: Inherit documentation with {@inheritDoc} tag
                Add a tag that copies the doc comment from a superclass
                into the current doc comment. This allows developers to
                write around the copied text rather than have the
                inherited text be the only text. Currently, text is
                copied only if the comment is empty.

(3.5) 4243589: Want capability to sort members summary & detail sections
                Want to be able to order by group, source order or
                strictly alphabetic by name (without grouping by
                constructor/method/field).

(3.6) 4039014: Flag misspelled tags while printing custom tags
                This is a part of the custom tag mechanism.
               
(3.7) 4074202: Put exception class link in throws section in two cases:
                (1) there is a @throws tag but no text accompanies the tag
                (2) if an exception is in the declaration but there is no tag

(3.8) 4464558: Add -nocomment to suppress description & tags, generating
                only declarations. Was needed for reference API for
                MPH 1.0.1 spec based on pjava 3.1. They wanted to
                re-use the source files originally intended for a different
                platform.


============ FOURTH SET OF CHANGES FOR MERLIN ==============================
These were submitted separately, under their own bugtraq numbers.

(4.1) 4504730: Separate page for static constant values

(4.2) 4510979: Add -linksourcetab for converting n spaces to tab