Package org.multijava.mjdoc.mjdoc_142

The mjdoc tool documents java programs that contain MultiJava (MJ) extensions to the Java progamming language; it produces html pages very similar to those produced by the javadoc tool.

See:
Description

Interface Summary

MjClassDoc.MemberFilter
MjdocWrapper.PrivacyChecker

Class Summary

Main	This class implements the entry point of the mjdoc tool.
MjClassDoc	This class is an interface between the MJC syntax tree classes and the javadoc program; it wraps a CClass object.
MjClassDoc.MjMemberFilter
MjConstructorDoc	This class represents a constructor of a class; it is the bridge between the MJC syntax tree object and the ConstructorDoc interface of javadoc doclets.
MjDoc	This abstract class provides an implementation of the Doclet Doc class.
MjdocAllClassesFrameWriter	Generate the file with list of all the classes in this run.
MjdocClassWriter	A derivative of a class in the javadoc doclet API, so as to be able to instantiate a MjdocClassWriter instead of a ClassWriter and a MjdocMethodSubWriter instead of a MethodSubWriter.
MjdocConstructorSubWriter	This is an extension of the doclet api in order to provide for adjusting the spacing in the javadoc and specs.
MjdocEMWriter	This class takes care of writing an html page for the contents of a compilation unit that contains external methods rather than classes.
MjdocFieldSubWriter
MjdocGFWriter	This class takes care of writing html pages that document individual generic functions (a family of related external and internal methods).
MjdocGUI	This class is automatically generated from MjdocGUI.gui and contains member fields corresponding to tool-specific GUI specifications.
MjdocMethodSubWriter	This is an extension of the doclet api in order to provide functionality for writing external methods.
MjdocMethodWriter	This is just used as a common super class for MjdocEFWriter and MjdocGFWriter, both of which produce html pages containing a list of methods, but not as part of a class.
MjdocPackageFrameWriter	Class to generate file for each package contents in the left-hand bottom frame.
MjdocPackageWriter	A derivative of a class in the javadoc doclet API, so as to be able to instantiate a MjdocClassWriter instead of a ClassWriter and a MjdocMethodSubWriter instead of a MethodSubWriter.
MjdocStandard	This class is an extension and modification of the Standard doclet, that is the usual javadoc implementation.
MjdocWrapper	This class is a bridge between the Mjc parsing mechanisms in Main and the html generation mechanisms in MjRootDoc and related classes.
MjdocWrapper.CClassMap
MjdocWrapper.MjPrivacyChecker
MjExecutableMemberDoc	This class is a superclass representing common functionality between both methods and constructors; it wraps appropriate objects from the MJ classes and parse tree.
MjExecutableMemberDoc.Comp	This class is used for sorting the gfs as listed on the package summary page and in the overview index lists.
MjExtMethodsDoc	This object holds a list of external methods that are in a single compilation unit.
MjFieldDoc	This class implements the Doclet FieldDoc interface by wrapping the MJC objects corresponding to a field of a class or interface.
MjGenericTag	This is an implementation of the Doclet Tag interface for a generic Tag, one that simply consists of a tag name and a description (which may have inline tags in it).
MjMemberDoc	This class implements the javadoc MemberDoc interface, but it clearly does not do very much.
MjMethodDoc	This class represents a method (but not constructor) of a class; it is the bridge between the MJC syntax tree object and the MethodDoc interface of javadoc doclets.
MjPackageDoc	This class represents a java package and provides methods for finding a package object and the classes within a package.
MjParameter	The class implements the javadoc Parameter interface, and wraps the name and type of a MJC formal parameter to supply the information about the parameter to javadoc.
MjParamTag	This class represents a javadoc comment @param tag; it is special in that it has a parameter name as well as a decription.
MjProgramElementDoc	This is an abstract class that is a super class for derived classes representing program elements such as classes, interfaces, constructors, methods, fields; it implements the javadoc ProgramElementDoc interface; derived classes wrap appropriate objects representing the program elements in the MJC class structure.
MjRootDoc	This class implements the Doclet interface for a RootDoc by containing lists of bridge classes for packages and classes.
MjSeeTag	This class represents the content of an @see or @link tag.
MjSourcePosition
MjTag	This class is the abstract parent task for the various special kinds of tag objects that represent tags in javadoc comments.
MjTagParser	This class is a helper class to parse javadoc comments into the appropriate set of tags.
MjTextTag	This class represents a portion of a Javadoc tag that is simply text (i.e. no inline tags such as links).
MjThrowsTag	This class represents a 'throws' tag in a javadoc comment, which has an exception name and a description; the description itself is composed of a sequence of text and inline tags.
MjType	This class implements the javadoc Doclet Type interface, by wrapping appropriate type objects from the MJ compiler.
Utils	This class simply contains some utility methods

Package org.multijava.mjdoc.mjdoc_142 Description

The mjdoc tool documents java programs that contain MultiJava (MJ) extensions to the Java progamming language; it produces html pages very similar to those produced by the javadoc tool.

The tool is provided as part of and in association with the MultiJava compiler (and on the same licensing terms). It is provided for the purpose of research and education in the area of programming language design, documentation and progamming productivity, particularly with respect to Java and the MultiJava extensions to the Java programming language. Note that MultiJava implements extensions to the Java programming language syntax, but the bytecode produced by the MultiJava compiler is fully compatible with the Java specification.

Questions and bug reports can be sent to the MultiJava interest mailing list.

Rationale

The javadoc tool is useful in providing web-based html documentation for java programs and libraries. It allows documentation to be maintained in the same source files as the program code, which helps the software developers keep the source code consistent with the documentation and specifications. But the tool enables the documentation to be formatted in a useful html format that is easily browsed, with relevant links for cross-references.

The multijava project proposes some extensions to the java language to allow multi-methods and open classes. All of the existing java language, as well as javadoc comments, remain legal in multijava. However, the syntax extensions for multijava are errors to the javadoc tool. Hence the need for mjdoc - a javadoc-like tool that performs the same function for multijava as javadoc does for java.

Architecture

The mjdoc tool uses the language parser of the multijava compiler project. The doclet extension mechanism of the javadoc API is used to render the html documentation pages. Ordinarily, java doclets use the javadoc services to parse java source files, producing a parse tree of relevant material. This tree is passed to either the standard doclet to be rendered to standard javadoc html pages or to a user-supplied doclet to achieve some user-defined purpose. In the case of mjdoc, appropriate adaptor classes take the parse trees from the multijava parser, wrap them in objects implementing the interfaces of the doclet API, and pass the resulting parse tree to a slight modification of the standard doclet. The slight modifications preserve all the usual html generated for javadoc pages, but add functionality appropriate to the multijava extensions.

The current version of this tool uses javadoc 1.4. It will not compile or run with doclet libraries earlier than java 1.4.

The JML project defines a syntax for special javadoc comments that enables specifications to be written in a machine processable manner. There is also a need to render those specifications in the html pages along with the usual javadoc output. The JML project has a companion tool, jmldoc, that leverages the multijava compiler, the mjdoc implementation, and the JML checker/parser in order to produce a tool that produces html output including multi-java extensions and JML specifications.

Previous work and references

This work to provide a javadoc-like tool for multijava stems from work on such a tool for the Java Modeling Language (JML). The code base is completely new, but the initial design of the javadoc tool for JML (jmldoc) was created by Arun D. Raghavan, as described in "Design of a JML documentation generator" (Iowa State University, Dept. of Computer Science, TR00-12, March 2000). [abstract] [postscript]

Running the mjdoc tool

In order to run the mjdoc tool, you must have on your CLASSPATH:

• org.multijava.mjdoc - the mjdoc Main class and adaptor classes
• org.multijava.mjc, org.multijava.util and its subpackages - the multijava compiler
• the antlr (2.7.2) runtime library
• the gnuopt command-line option parsing library
• the libraries for the javadoc tool and the doclet API. These are either part of your java installation or in an archive named tools.jar. If the command javap com.sun.tools.doclets.standard.Standard successfully lists the API for the Standard class, then your CLASSPATH contains the appropriate reference.

All of these, except the doclet jar, are available together in the multijava release.

With the CLASSPATH appropriately set, execute

java org.multijava.mjdoc.Main options files packages
with command-line options and arguments as described below (the options, files, and packages may be intermixed and may appear in any order).

Alternatively, one can be specific about classpaths and write

java -classpath cp1 org.multijava.mjdoc.Main -classpath cp2 -sourcepath cp3 ...
where cp1 is a classpath containing paths to the packages listed above (and defaults to the environment setting of CLASSPATH), and cp2 is a classpath containing paths to find .class files for classes referenced by parsed files (defaults to cp1), and cp3 is a classpath used for finding packages listed on the command-line (defaults to cp2). The files and directories on the command-line are looked for in the current working directory. Packages on the command-line are looked for in the directories that make up the sourcepath. Note that, just as with javadoc, the source files must be available in order to generate documentation files with javadoc comments reflected in them.

Enhancements provided by mjdoc

The output of mjdoc contains the following enhancements over javadoc. More information about the details of the programming language extensions can be found in the MultiJava documentation.

• MultiJava allows multimethods, which allow dynamic dispatch on more than one argument of a method. This is indicated in a formal parameter list by the syntax type1@type2 or type@@literal. Methods with such parameters are rendered in html using the same syntax.
• Multijava allows external methods, that is, methods declared outside the compilation unit defining the class to which they belong. If the documentation of the receiver class is being generated along with the documentation for the external method, then the method and its documentation are inserted into the receiver class's documentation, just as if the method were a usual java method. The method is identified as an external method and the name of the package and file containing the declaration of the external method is given; a link (labeled "GENERIC FUNCTION VIEW") is provided giving an html reference to the generic function documentation.
  

  func [external method declared in open.func]

  public void func()

  Deprecated.

  Comment for B.func.

  Overrides:

  func in class A

  GENERIC FUNCTION VIEW
• For each generic function, that is each family of methods that form an inheritance hierarchy (with more specific methods overriding the more general), a documentation page is generated showing all the methods in that family of methods. Such pages are generated by default for external generic functions (but note the --fcns option described below). For each method listed on the generic function page, there is a link (labeled "CLASS VIEW") that references the class file for the receiver class of the method. Methods that are actually internal and declared in a class are labelled as such.

  open.A.fun

  void fun()

  Top method.

  CLASS VIEW

Documentation

The mjdoc tool is intended as a drop-in replacement for javadoc. That is, it accepts source files with all the tags accepted by javadoc, and it accepts all the command-line options that are accepted by javadoc. If presented with conventional java files and only javadoc command-line options, it produces the same output as javadoc. (Any differences in implementation are noted below). There are additional command-line options defined by mjdoc, described below.

• The syntax of javadoc tags and the available javadoc command-line options are described at the javadoc web page.
• The syntax of multijava enhancements is described in the multijava reference material.

Command-line options

The following are the command-line options available for javadoc 1.4 using the default (standard) doclet; they are also accepted by mjdoc. These options begin with a single hyphen and may not be abbreviated. The effect of these options is described more completely in the Javadoc 1.4 documentation. The following descriptions are summaries from the javadoc documentation. Javadoc option names (but not the arguments of the options, nor the mjdoc-specific options) are case-insensitive.

• -author : causes information in @author tags to be put into the html pages; the default is to omit the information
• -bootclasspath classpath : specifies the set of directories and jar files in which the Java system classes are found; the default is system specific.
• -bottom string : a string of HTML content to be placed at the end of the file, below the lower navigation bar
• -breakiterator : in javadoc controls the algorithm that determines the summary sentence of a comment; this option is ignored in mjdoc since mjdoc always behaves like javadoc with -breakiterator enabled.
• -charset string : specifies the HTML character set for the document as given in the usual META tag; the default is to omit the META html tag.
• -classpath pathlist : the set of root locations (directories and jar files) in which mjdoc will look for class files for all referenced classes (those not on the command-line but referenced by files and packages on the command-line). The default is the value of the environment variable CLASSPATH, or the current directory if CLASSPATH is not defined. This option is equivalent to --classpath and -C.
• -d directorypath : specifies the root location for the generated html files (relative to the current directory). The default is the current directory.
• -docencoding name : specifies the html encoding for generated files. The default is set by the java runtime environment in your local environment.
• -docfilessubdirs : recursively copy doc-file subdirectories
• -doclet class : uses the given (fully-qualified) class as the doclet class to use instead of the MjdocStandard class. See the doclet API for more information about writing new doclets.
• -docletpath classpathlist : specifies a path to or jar file containing the doclet specified in the -doclet option. The default is the value of -classpath (NOT IMPLEMENTED - add the doclet location to the classpath instead).
• -doctitle string : uses the given string as the displayed title in the generated overview html page; the default is no title.
• -encoding name : specifies the encoding name of the source files, otherwise uses a platform-specific default
• -exclude pkglist : specifies a list of packages to exclude from being documented
• -excludedocfilessubdir name1:name2:... : exclude any listed doc-files subdirectories
• -extdirs directorylist : specifies the directories where extension classes are found (NOT IMPLEMENTED - use bootclasspath instead)
• -footer string : a string of HTML content to be placed to the right of the lower navigation bar; the default is the string used for the header (cf. -header)
• -group groupheading packagepatternlist : allows the organization of the packages listed on the overview page into specified groups, as described in the javadoc documentation; by default all the packages are in one group.
• -header string : a string of HTML content to be placed to the right of the upper navigation bar
• -help : prints out a usage message and terminates (equivalent to --help)
• -helpfile filepath : specifies the file that contains the description of how to use the generated html pages. A copy of this file is made and stored in the top-level directory of the documentation set (using the given filename), and linked to by the HELP link in the documentation pages. Without this option, mjdoc (like javadoc) generates its own file at a hard-coded filename. The specified path to the filename is either an absolute path or a path relative to the current directory.
• -Jflag : specifies runtime system options
• -link url : specifies a url (either http: or file:) at which to find the html documentation of classes that are referenced in the classes being documented but whose documentation is not itself being generated in this run of mjdoc. It is allowed to have multiple -link options. It is required that there be a file named package-list at the specified url; this file contains the list of packages that are documented at that location.
• -linkoffline url url-or-directory : as for the -link option, this specifies the location of html files for classes not being documented in the current mjdoc run. In this case the url-or-directory gives the location of the package-list file that contains a list of packages that are documented at the location url. The url need not be available at the time the documentation is generated, through of course, it will have to be available when the link is activated in the produced documentation.
• -linksource : generate links to html files containing source code
• -locale locale-name : specifies the locale to be used for rendering text (place this option first) (NOT IMPLEMENTED in mjdoc)
• -nocomment : suppress description and tags, generating only declarations
• -nodeprecated : prevents the generation of any documentation of deprecated elements (as well as doing what -nodeprecatedlist does)
• -nodeprecatedlist : prevents the generation of the deprecated-list.html file, which contains a list of deprecated elements
• -nohelp : omits the generation of a help file (how to use the generated html pages)
• -noindex : prevents the generation of an index as part of the documentation
• -nonavbar : omits the header, footer and navigation bars
• -nooverview : prevents an overview file from being created when more than one package is being documented
• -noqualifier name1:name2:... : exclude the list of qualifiers from the output
• -nosince : prevents the listing of any information from @since tags
• -notree : omits the class/interface tree from the generated documentation
• -overview path/filename : causes mjdoc to create an overview page using the information in the given overview file; the given path/filename is found relative to the stated -sourcepath. In mjdoc, an overview file is created by default if more than one package is being documented. Typically -sourcepath refers to the root directory of the packages being implemented, path/ is omitted, and filename is overview.html. (Despite the javadoc documentation, javadoc 1.3 looks for the specified overview file relative to the current directory.)
• -public, -protected, -package, -private : These control which classes and class members are documented on the html pages, according to their declared access level.
• -quiet: Turns off any informational messages from the javadoc doclet api (Now equivalent to --Quiet)
• -serialwarn : causes warnings to be generated for missing @serial tags (NOT IMPLEMENTED)
• -source release : provide source compatibility with specified release
• -sourcepath pathlist : the set of root locations to search for the packages specified on the command-line. The default is the value of -classpath.
• -splitindex : if an index is generated, generates it as a number of smaller files instead of one large file
• -subpackages subpkglist : specifies subpackages to recursively load
• -stylesheetfile file : specifies a file to use as the HTML stylesheet file; it is copied to the root directory of the documentation set (retaining the same filename); the default behavior is simply to write a standard default css file using the filename stylesheet.css. The specified path to the filename is either an absolute path or a path relative to the current directory.
• -tag name:location:header : specifies a single argument custom tag
• -taglet name : specifies a fully-qualified name of a taglet class
• -tagletpath pathlist : the pathlist in which to find taglet classes
• -use : adds the use information pages (one per class and package) to the generated documentation
• -verbose : not applicable to mjdoc (causes printing of timing details of parsing in javadoc)
• -version : cause information in @version tags to be put into the html pages
• -windowtitle string : uses the given string in the TITLE tag of the generated html pages (so that it appears in the title bar and bookmarks or favorites lists of the browser). The javadoc documentation says that the default is the value of -doctitle; however javadoc (and mjdoc) actually produces a title of "Generated Documentation (Untitled)" on the frame-style overview page and an empty prefix on other pages.
• -x : prints out a list of special (javadoc) options
• -xnodate : a special option that causes html pages to have the string 'TODAY' instead of a current date and time

The following are additional options available in mjdoc. These options have a long form, which begin with a double hyphen, and a short form, which consist of a single hyphen and a single letter. If a short form option has a single argument, it may be concatenated with the hyphen and letter or it may be separated by white space.

• --classpath classpath, -C classpath : specifies the root directories where referenced classes and packages are found; equivalent to -classpath
• --deprecation : not applicable to mjdoc (in mjc it prevents deprecated methods from being called); use -nodeprecated above to avoid listing deprecated classes and meethods in the generated documentation
• --destination directory, -d directory : The location in which to put all output files. The default is the current directory.
• --fcns arg : specifies which generic function html pages should be produced. If arg is none, no generic function pages are produced; if arg is ext (the default), then pages are produced only for external methods; if arg is all, then pages are produced for both internal and external methods. [ -all is experimental and incomplete ]
• --help, -h : simply prints out usage information and terminates, without processing any files (equivalent to -help)
• --multijava, -M : enables multijava extensions (default is enabled)
• --nomultijava : disables multijava extensions
• --norecursive : disables the -recursive option (the default is non-recursive)
• --recursive, -R : causes mjdoc to document java files in any subdirectories (and sub-subdirectories, etc., recursively) of directories or packages listed on the command-line. See also the -subpackage option in javadoc 1.4 for a slightly different but similar functionality.
• --sourcepath directorylist, -S directorylist : equivalent to -sourcepath above
• --version, -V : displays the version number of the mjdoc program and terminates
• --warning int, -w int : controls the pickiness of the warnings produced by mjdoc, in an undocumented way

These mjdoc options are used mostly for debugging:

• --debug, -c : enables the production of copious debugging information
• --filter qualifiedName, -f qualifiedName : names a filter to filter error and warning messages
• --keepGoing, -k : instructs mjdoc to continue on after reporting errors, even at the risk of runtime exceptions
• --quiet, -q : enables the printing of timing information about each compilation phase
• --verbose, -v : enables the printing of tracing information about each compilation phase

Treatment of files, packages and directories listed on the command line

In addition to the command-line options and their arguments described above, the command-line for mjdoc may contain filenames, directories and package names. A command-line argument that is not an option or option argument is interpreted as follows.

• If the argument is an absolute or relative (relative to the current working directory) path to a readable file, it is considered a filename.
• Otherwise, if the argument is a syntactically valid package name (a java identifier or a sequence of java identifiers separated by '.' characters), it is considered a package name (whether or not it exists).
• Otherwise, if the argument is an absolute or relative (relative to the current working directory) path to an existing directory, it is considered a directory. (A simple name can be interpreted as a directory by prefixing it with ./
• Otherwise, the command-line argument is invalid.

A command-line argument that is considered a filename must be the name of a .java file and must contain valid multijava source code (i.e. compiled without error by mjc). Relative pathnames are relative to the current working directory (regardless of the values of the CLASSPATH environment variable or the classpath or sourcepath command-line options).

If the argument denotes a package, then it is expected to be a valid package name rooted at a directory listed in the sourcepath. Specifying a collection of files to the mjdoc application as a package rather than as individual files causes mjdoc to generate additional package-level and overview level documentation, as described in the javadoc documentation.

If the argument is a directory, then mjdoc processes all .java files in the given directory. If the -R (or --recursive) option has been specified, then all .java files in any subdirectory (and, recursively, sub-subdirectories, etc.) are also processed just like directories specified on the command-line are processed.

Differences from javadoc

The mjdoc tool extends javadoc, as described above. On strict java files with only javadoc command-line arguments, mjdoc output differs slightly from javadoc output in the following ways.

• The warnings generated by javadoc are not documented; the set of warnings generated by mjdoc is different, and the warning messages may have a different format.
• The resolution of class names specified in @see, @link, or @throws tags is somewhat different between the two tools. There may be some links or warnings about links that are generated with one tool that are not generated with the other.
• The output of javadoc contains an html comment in the generated files that says "Generated by javadoc"; mjdoc replaces that with "Generated by mjdoc"
• The algorithm for determining the summary (first) sentence of a javadoc comment may differ.
• The javadoc documentation says that the file specified by the -overview option is looked for relative to the directories on the given sourcepath, or relative to the current directory if no sourcepath is given. This behavior is implemented in mjdoc, but javadoc 1.3 actually only looks relative to the current directory.
• The spacing between javadoc commentary and subsequent tags is slightly altered.

Bugs and features not yet implemented

• The -docletpath option is not implemented.
• The -extdirs option is not implemented.
• The -locale option is not implemented.
• The -subpackages option is not implemented.
• The -exclude option is not implemented.
• The -docfilessubdirs and -excludedocfilessubdir options are not implemented.
• The resolution of class names in tags must be corrected.
• The type names of parameters of methods in see and link tags must be fully qualified
• Some of the non-javadoc text rendered by mjdoc is only in English and not affected by the -locale option
• Multijava extensions, such as the two parts of a specialized type, may not be represented in the use or index pages.
• The FRAMES/NO FRAMES options on a generic function html page do not work correctly.
• Some html files generated by mjdoc still have comments saying they are generated by javadoc.
• Anything to do with serial/serializable tags is not implemented

Differences from the doclet API

The mjdoc code contains an implementation of the Doclet API, as specified by Sun MicroSystems. There is also an implementation of that API implicit in the implementation of the javadoc application, and used by the Standard Doclet and other doclets. There are some known differences between the mjdoc and Standard doclet implementations, beyond the extensions needed for MultiJava:

• Description needed ???

Acknowledgements

The implementation of mjdoc has relied upon

• the implementation of the multijava compiler, provided by the MJC project, courtesy of and with thanks to those who have contributed to its development (see the MultiJava home page for a current list of contributors);
• the advice, assistance and encouragement of individuals currently active in the MJC and JML projects, particularly Gary Leavens, Curtis Clifton, and Todd Milstein.
• the documentation of javadoc and the documentation and implementation of the Standard Doclet as provided by Sun MicroSystems, about which Sun writes "One reason to look at the standard doclet is that it serves as a good example of the use of much of the doclet API. A second reason is that by seeing how the standard doclet produces the default HTML output, it will be easier for you to modify the standard doclet to make your own doclet for generating custom API documentation.". Also, "If you want HTML output with roughly the same format as the default output, you can use the standard doclet as a starting point for creating your doclet. You can subclass appropriate classes in the standard doclet and then add or override methods as necessary to produce the output you want. Or you can copy the whole standard doclet and modify it."
• David Cok, who has been (as of May 2002) the principal author of mjdoc.

Questions and bug reports can be sent to the MultiJava interest mailing list (subscribe here).