The Pizza Compiler

The Pizza language is an extension to Java with three new features:
- Generics (aka Parametric polymorphism)
- Function pointers (aka First-class functions)
- Class cases and pattern matching (aka Algebraic types)

Pizzadoc documentation

 

 

 

NAME

pizzadoc - Generates HTML pages of API documentation from pizza or java source files.

SYNOPSIS

pizzadoc [ options ] [ source.java | source.pizza ]*
should be aliased to
pizzac -pizzadoc [ options ] [ source.java | source.pizza ]*

DESCRIPTION

I know about it... show me an example comment!

Tell me about the new distributed documentation feature!

pizzadoc parses the declarations and documentation comments in a set of pizza or Java source files and produces a set of HTML pages describing, by default, the public and protected classes, interfaces, constructors, methods, and fields. As an argument to pizzadoc you pass in a series of pizza or java source files.

pizzadoc generates two .html files for each class or interface file it encounters - one with the complete class or interface description and one with only the variables, methods and classes listed without any comments (known as pure interface page). For each encountered package an index page of all classes and interfaces in the packages is generated. In addition, it produces a class hierarchy (tree-pd.html) and an index of all class names, method names and variable names (names-pd.html).

When pizzadoc parses the class and member delarations, it picks up their signatures for inclusion. In addition, you can add further documentation by including doc comments in the source code.

pizzadoc does the complete typechecking the pizza compiler does. Therefore you can use pizzadoc as interface checker without implementing any methods.

Commenting the Source Code

You can include documentation comments in the source code. A doc comment consists of the characters between the /** that begins the comment and the */ that ends it. The text is divided into one or more lines. When pizzadoc parses a doc comment, leading * characters on each line are discarded; for lines other than the first, blanks and tabs preceding the initial * characters are also discarded. These comments may include HTML tags. Here is a doc comment:

/**
 * This is a <b>doc</b> comment.
 */
	  

The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag (as defined below). pizzadoc copies this first sentence to the member summary at the top of the .html file.

Documentation comments are only recognized when placed immediately before class, interface, constructor, method, or field declarations.

When you embed HTML tags within a doc comment, you should not use heading tags such as <h1> and <H3>, because pizzadoc creates an entire structured document and these structural tags interfere with the formatting of the generated document.

For the specification on documentation comments, see Chapter 18, Documentation Comments, in the Java Language Specification, by James Gosling, Bill Joy, and Guy Steele.

Tagged Paragraphs

pizzadoc parses special tags that are recognized when they are embedded within a pizza doc comment. These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an "at" sign (@).

Tags must start at the beginning of a line.

Documentation Tags

@author name-text
Creates an "Author" entry. The text has no special internal structure. A doc comment may contain multiple @author tags.

@version version-text
Adds a "Version" entry. The text has no special internal structure. pizzadoc uses only the last @version tag specified. Version normally refers to the version of the software (such as the Pizza API) that contains this feature.

@since since-text
Adds a "Since" entry. The text has no special internal structure. This tag means that this change or feature exists since the release number of the software specified by the since-text (such as the Pizza Release). pizzadoc uses only the last @since tag specified.

@see classname
Adds a hyperlinked "See Also" entry to the class. Some examples are:
    @see java.lang.String
    @see String
    @see String#equals
    @see java.lang.Object#wait(int)
    @see Character#MAX_RADIX
    @see <a href="spec.html">Java Spec</a>
    @see #aMethodInThisClass(int, String)
The character # separates the name of a class from the name of one of its fields, methods, or constructors. A @see tag beginning with a # generates a hyperlink local to this class page. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method or constructor name. Whitespace in @see's classname is significant. If there is more than one argument, there must be a single blank character between the arguments. If you use higher order functions the -> has to have a single blank character before and after it. For example:
    @see java.io.File#File(java.io.File, java.lang.String)
    @see #equals((A, A) -> int compare)

A doc comment may contain more than one @see tag.

@param parameter-name description
Adds a parameter to the "Parameters" section. The description may be continued on the next line.

@return description
Adds a "Returns" section, which contains the description of the return value.

@exception fully-qualified-class-name description
Adds a "Throws" section, which contains the name of the exception that may be thrown by the method. The exception is linked to its class documentation.

Where is which tag recognized?

Not all tags are sensefull for all declarations. This table tells you where you may use wich tag.
Tag Class comment Field comment Method comment
@authorYes
@versionYes
@sinceYes
@seeYesYesYes
@paramYesYes
@returnYes
@exceptionYes

An example of a class doccomment:

/** 
 * A class for immutable lists.
 * Sample list construction for a list of strings:
 * <pre>
 *  import pizza.lang.List;
 *  import pizza.lang.List.*; // imports case constructors of the list class
 *  ...
 *  List&lt;String&gt; list = Cons("element 1", Nil);
 *  list = Cons("element 2", Cons("element 3", list));
 *
 *  for (List&lt;Strin&gt; now=list; now != Nil; now = now.tail()) {
 *    System.out.println(now.head());
 *  }
 *  </pre>
 *  Results:
 *  <pre>
 *  element 2
 *  element 3
 *  element 1
 *  </pre>
 * @param A type of the elements in the list
 * @see		ListBuffer
 * @author      Martin Odersky
 * @version     1.0
 * @since       pizza 1.0
 */
public class List<A> {
   ...
}

An example of a method doccomment:

    /**
     * Returns the character at the specified index. An index 
     * ranges from <code>0</code> to <code>length() - 1</code>.
     *
     * @param     index  the index of the desired character.
     * @return    the desired character.
     * @exception StringIndexOutOfRangeException 
     *              if the index is not in the range <code>0</code> 
     *              to <code>length()-1</code>.
     * @see       java.lang.Character#charValue()
     */
    public char charAt(int index) {
       ...
    }

Distributed documentation pages

pizzadoc helps you to maintain a distributed documentation of projects. The link transformation functionality allows you to store the documentation of different packages on different locations on the internet. pizzadoc checks if it has to link to specified packages and uses a given URL prefix.

For example:
When your class is using the class java.lang.String you will not have to have the documentation local on your system, but you give pizzadoc the information all packages with the prefix java. are found at http://java.sun.com:80/products/jdk/1.1/docs/api/. pizzadoc will now use that URL as new prefix for the link.

In the file .pizzadoc you can set up your own link transformation pairs. The structure is like this:

java.=http://java.sun.com:80/products/jdk/1.1/docs/api/
sun.=http://java.sun.com:80/products/jdk/1.1/docs/api/
sunw.=http://java.sun.com:80/products/jdk/1.1/docs/api/
pizza.=http://www.cis.unisa.edu.au/~pizza/doc/api/
      
Actually this example is the standard transformation used when no .pizzadoc file is found in the home directory. In that case pizzadoc will generate the standard transformation file. You can use comments in the file by using # as first character in the comment line.

OPTIONS

-public
Shows only public classes and members.

-protected
Shows only protected and public classes and members. This is the default.

-package
Shows only package, protected, and public classes and members.

-private
Shows all classes and members.

-excludedeprecated
Exclude classes or members which are marked as deprecated. (See nodeprecated)

-nointerface
Don't generate pages with the pure class interfaces.

-nosourcename
Don't write the source filenames in the pages.

-sourceversion
Include @version tags, which are omitted by default. (Was -version in javadoc!)

-since
Include @since tags, which are omitted by default.

-author
Include @author tags, which are omitted by default.

-index
Generate an index page with all class, method and variable names, what is NOT done by default.

-noindex
Don't generate the index page.

-tree
Generate a class/interface hierarchy, which is NOT produced by default.

-notree
Omit the class/interface hierarchy.

-linktrans
Transform links to get a distributed documentation. You can specify the transformation you want to use in the file ".pizzadoc". If this file does not exist pizzadoc will generate the standard transformation table.

-nolinktrans
Don't transform links.

-nodeprecated
Exclude paragraphs with the @deprecated tag. (See excludedeprecated)

-newindex
Generates all packages and package index files new instead of scanning the old ones and adding new information to them.

-d  directory
Specifies the destination directory where pizzadoc stores the generated HTML files. (The "d" means "destination.") The directory can be absolute or relative to the current working directory. The directory will NOT be generated if it doesn't exist! For example, the following generates the documentation for all pizza files in the pizza/lang directory and stores the results in the directory specified by the -d option:
	    
pizzadoc -d /pizza/src/doc pizza/lang/*.pizza
-classpath  path
Specifies the path pizzadoc uses to look up the .java files. Also specifies the directories from which pizzadoc is to load its own .class files. Each path element should be a directory that contains the topmost packages. Overrides the default or the CLASSPATH environment variable, if it is set. The path can contain multiple paths by separating them with a colon (in DOS seperated by a semicolon). For example, the following sets two paths, the first of which is the current directory (.):

pizzadoc -classpath .:/home/cisqut/pizza/classes

The value of classpath defaults to the current directory plus the classes location.

-Jflag
Pass flag directly to the runtime system. For example, if you need to ensure that the system sets aside 32 megabytes of memory to hold the generated documentation, then you would use this flag as follows:
pizzadoc -J-mx32m -J-ms32m <classes> ...

-verbose
Without the verbose option, messages appear for generating the documentation pages. The verbose option causes the printing of additional messages specifying the number of milliseconds to parse each java source file and which classes are loaded.

We recommend...

To keep all source documentation at one place you should add the destination directory to your alias or batch command:
  alias pizzadoc "pizzac -pizzadoc -d ~/pizza/src/doc"

EXAMPLES

Documenting One or More Packages and Redirect the Output

First, change to the parent directory of the top-most package. Then run pizzadoc, supplying one or more source filenames with or without wildcards.
  % cd /pizza/src/
  % pizzadoc -d /www pizza/lang/*.pizza pizza/util/*.pizza
Generates HTML-formatted documentation for the public classes in packages pizza.lang and pizza.util and puts it in the specified destination directory (/www). Old index files are updated.

Documenting One or More Classes

Change to the directory holding the class (or supply the sourcepath option with that directory). Then run pizzadoc, supplying one or more class names.
  % cd /pizza/src/pizza/lang
  % pizzadoc -d /www List.pizza ListBuffer.pizza
Generates HTML-formatted documentation for the two classes in the directory /www.

ENVIRONMENT

CLASSPATH
Provides the system a path to the user-defined classes. Separate directories with a colon, for example,
.:/home/avh/classes:/usr/local/java/classes