What was the interface for that functor again?

Nils Franzén and Andreas Sundström

The aim of this software is to create interface descriptions for functors and show dependencies between functors. Produced interface descriptions can later be accessed in an easy way using a web-browser.

Download Software

Current version: 1.1 (06-Nov-2000), see change log for more information.

Check out generated web-documents for Tk and TkTools and Remote

• 1 Documenting tool for Mozart source code
• 2 Contributors
• 3 Documenting Interfaces
  • 3.1 Comments
    • 3.1.1 Problems with indentation in Emacs
  • 3.2 Commenting arguments for methods and procedures
    • 3.2.1 More detailed commenting of arguments
• 4 How to use the tool
  • 4.1 Arguments
  • 4.2 CVS option
• 5 Quick Introduction to the Web-Interface
• 6 Change Log

1 Documenting tool for Mozart source code

The idea is to give Mozart-developers a good tool to produce interface descriptions for functors. This tool takes a functor file as argument, follows all imported functors, and generates a number of navigable html pages. These html pages display the interfaces, (i.e. imports and exports) for the functors. One can easily jump between html pages describing the different functors with a single mouse-click.

2 Contributors

Erik Klintskog

Provided the layout algortihm for functor map.

Andreas Franke

Provided fontify and general suggestions for improvments

Simon Lindblom

Provided the cvs information extraction.

3 Documenting Interfaces

The tool is able to read comments in mozart source files, which will be displayed in the generated html pages. One can comment the following entities in the program

• The functor

• Classes and procedures

• Methods (in classes)

• Arguments taken by methods or procedures

3.1 Comments

Text comments has the form of

/** Comment */

The comments should be placed just before the entity that it should be associated with. White spaces and comments using "%" can be placed between the entity and the desired comment without any problem.

3.1.1 Problems with indentation in Emacs

When writing a comment that reaches over several lines, the indentation may be corrupt if you use keywords like if, or, etc. This is not a problem of ozh, rather the elisp that handles indentation. But changing the elisp to not to indent on keywords found in /** ... */-comments takes a lot of work and the result may be that the indentation process will become to slow (and in practice is useless). To solve this problem, ozh provides a small fix. All %s that start a line in a comment will not be displayed. Eventual spaces and tabs before the first % is also removed. For example you can write:

/**  
% if class or...
*/

and the output will look like

if class or...

and your mozart source can still be indented correctly in emacs.

3.2 Commenting arguments for methods and procedures

Brief commenting of arguments is done by using

@X=Value

where X is the position of the argument and Value is a string, which don't contains any whitespaces. For procedures X is a value between 1 and the arity of the procedure. For methods X is one of the features in the method-head.

Examples of commenting arguments in method-heads

meth new(One Two object:Foo)
   Foo={New One Two}
end

We describe the arguments in the following way

%% This comment will not appear in the generated html-pages
/** Creates a new instance of Class */ 
%% @1=Class @2=Init @object=?Object
meth new(One Two object:Foo)
   Foo={New One Two}
end

Will generate the following output

• new(Class Init object:?Object)
Creates a new instance of Class

3.2.1 More detailed commenting of arguments

Detailed commenting of arguments is done by

@arg X Name Description

X is used in the same way as in brief commenting, the Name is the variable name and the Description is a text string that explains the argument. The description must be inside /** ... */ and will be removed from the displayed comment. Each description must end with new-line.

4 How to use the tool

The tool is named ozh¹ takes one input file and an output directory

ozh RootFunctor.oz -o Directory

The program parses the source file RootFunctor and follows (when possible) all imported functors.

4.1 Arguments

ozh takes the following command-line arguments

4.2 CVS option

The --cvs option extracts CVS related information (author, date and version) from the file. This information will be displayed on top of the generated html-page for that functor.

5 Quick Introduction to the Web-Interface