|
The Pizza Compiler
The Pizza language is an extension to Java with three new features: |
Pizzadoc documentation
|
|
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.
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.
Tags must start at the beginning of a line.
A doc comment may contain more than one
For example:
In the file
The value of
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!
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.
*/
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 (@).
Documentation Tags
@author name-text
@author tags.
@version version-text
@version tag specified. Version
normally refers to the version of the software (such as the Pizza API)
that contains this feature.
@since since-text
@since tag specified.
@see classname
@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)
@see tag.
@param parameter-name description
@return description
@exception fully-qualified-class-name description
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
@seeYes Yes Yes
@paramYes Yes
@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<String> list = Cons("element 1", Nil);
* list = Cons("element 2", Cons("element 3", list));
*
* for (List<Strin> 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.
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..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
-d option:
.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 (.):
classpath defaults to the current directory plus the
classes location.
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