JML

Package org.multijava.mjdoc

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
JavadocOptionsInterface  
 

Class Summary
BootClassPath  
JavadocOptions This class is automatically generated from JavadocOptions.opt and contains member fields corresponding to command-line options.
Main This class just has a main routine that invokes the main routine in the subpackage appropriate to the version of the Java tools library that is on the classpath.
MjdocGUI This class just has a main routine that invokes the main routine in the subpackage appropriate to the version of the Java tools library that is on the classpath.
MjdocMessages  
MjdocOptions This class is automatically generated from MjdocOptions.opt and contains member fields corresponding to command-line options.
ToolsVersion  
 

Package org.multijava.mjdoc 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: 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.

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.

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.

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.

These mjdoc options are used mostly for debugging:

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.

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.

Bugs and features not yet 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:

Acknowledgements

The implementation of mjdoc has relied upon

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


JML

JML is Copyright (C) 1998-2002 by Iowa State University and is distributed under the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This release depends on code from the MultiJava project and is based in part on the Kopi project Copyright (C) 1990-99 DMS Decision Management Systems Ges.m.b.H.