How to use MashDoc
1. Introduction
MashDoc is a tool that automatically parses comments in
OTcl/C++ code and generates structured API documentation.
Currently, only HTML documents are generated. Others
formats such as docbook and latex can be added when needed.
You can avoid reading the details in this document by
looking at the examples in Section 3.4 and 4.3, and cut
and paste from there.
2. Documentation Block (or, DB)
A documentation block, or DB, is a chunk of comments in your
code that MashDoc recognizes and parses into structured
documents.
2.1 DB Separator
DB must start with a special commented line called DB
separator and end with either another DB separator or a
non-commented line.
For OTcl, a DB separator is a line that either:
- begins with "#", followed by one or more "-", or
- begins with "#", followed by one or more "#".
For C++ and C, a DB separator is a line that either:
- begins with "//", followed by one or more "-", or
- begins with "/*", followed by one or more "*".
- begins with "/*", followed by one or more "-".
For C++ and C, a DB can also be terminated with a line that
- begins with "-" followed by one or more "-", followed by "*/"
- begins with "*" followed by one or more "*", followed by "*/"
Example:
#------------------------------------------------
#
#------------------------------------------------
#################################################
#
#################################################
/*-----------------------------------------------
------------------------------------------------*/
//-----------------------------------------------
//
//-----------------------------------------------
/*************************************************
*************************************************/
2.2 DB Keywords
A DB is divided into sections. Each section is identified by
a keyword. The list of keywords, and the semantics of the text
that follows, are given below:-
KEYWORD MUST BE FOLLOWED BY
------------------------------------------------------------------------
Application: Name of the application
Arguments: Arguments to a method or application.
C++ Class: Name of a C++ class
Class: Name of a class (C++/OTcl)
Description: Description of a application,class,method,procedure..
Function: Name of a C function.
Members: List of members in a struct/class and their description.
Method: Name of a C++/OTcl method.
OTcl Class: Name of an OTcl class.
Postcond: Post-condition of a method.
Precond: Pre-condition of a method.
Procedure: Name of a Tcl procedure.
Results: Results of a method,procedure,function..
See Also: Related classes.
Shadow Class: Name of the C++ class that implements this OTcl class.
Side Effects: Side effect.
Static Members: List of static members in a class.
Static Method: Name of a static methods.
Superclass: List of superclasses.
Keyword must be the first word in a line and must be followed
by a ":".
Text not following any keyword will be ignored by MashDoc.
Each DB should be typed. There are three types of DB:
classes, methods and applications. Untyped DB will be
ignored.
The type of a DB is determined by a keyword appearing inside
the DB.
Each DB should contain exactly one of the following "type" keyword
TYPE KEYWORD
--------------------------------------------------------------------
Class "OTcl Class:", "C++ Class:", "Class:", "Struct:"
Method "Static Method:" "Method:", "Procedure:", "Function:";
Application "Application:".
"Struct:" "Procedure:" "Function:" "Application:" are not
currently supported. Feel free to hack the code to add in
these keywords.
It is recommended that type keyword appears in the first
line in a DB.
3. Documenting Classes
The "Class:" keyword must be followed by the name of the
class. It is recommended that the name of the class appears
on the next line after the keyword.
By default, MashDoc determines the type of the class (whether
it is a OTcl class or a C++ class) by the extension of the
file the DB appears in. (whether it is .tcl or .cc/.c).
You can use "C++ Class:" or "OTcl Class:" to override the
above rule.
The following sections are recommended when documenting a
class:- "Description:", "Members", "See Also:"
3.1 Shadow Classes
For split objects, you can specify the relationship between
a C++ class and an OTcl class with a "Shadow Class:" section.
3.2 Superclasses
For OTcl classes, the inheritance information are generated
directly from the source. However, for C++ classes, you
have to explicitly put in a "Superclass:" section to parent
classes.
3.3 Members
Members of a class should be listed in the "Members:"
section. The name of the each member must be followed by
"--", and should be followed by a textual description for
that member.
3.4 Example
#------------------------------------------------
# Class:
# VideoStream
# Description:
# Encapsulation of a video stream.
# Members:
# fps -- frame rate of this video stream.
# bps -- bit rate of this stream.
# format -- format of this video stream.
# See Also:
# AudioStream
#------------------------------------------------
4. Documenting Methods
The "Method:" or "Static Method:" must be followed by the
name of the class, and then the name of the method. The
class name and the method name must appear on the same
line.
The following sections are recommended when documenting
methods:- "Description:", "Arguments", "See Also:".
4.1 Arguments
Arguments to a method are commented in the same manner
as members. Name of an argument must be the first word in
a line, followed by "--" on the same line, followed by the
description of the arguments, either on the same line or
on the next line.
4.2 Multiple methods
You can comment multiple methods in the same DB, by using
multiple class names and method names after the "Method:"
keyword. Each line must contain one class name and one
method name. Every methods in the same DB must belong to
the same class.
4.3 Example
#------------------------------------------------
# Method:
# VideoStream set_fps
# VideoStream get_fps
# Description:
# Set and get the frame rate of the video stream
# respectively.
# Arguments:
# fps --
# Frame rate of the video stream.
#------------------------------------------------
#------------------------------------------------
# Method:
# VideoStream clip
# Description:
# Return a new VideoStream, which is a shorter
# version of this VideoStream object.
# Arguments:
# start -- Start time of the clip.
# stop -- Stop time of the clip.
#------------------------------------------------
5. How to run MashDoc
5.1 mashdoc.tcl
mashdoc.tcl is a smash program that parses the code and
generate an intermediate file containing structured
information about the code.
It takes in two optional parameters:-
rootdir -- the directory where you put your source code.
All files (up to 4 levels recursively) under the rootdir
with extension .tcl, .cc, .c and .h will be read and
parsed. By default, rootdir is set to the current
directory. Typically you want this to be $HOME/mash-code/mash
or something like that.
outdir -- this is where you want to put your intermediate
file. By default, it is set to the current directory.
mashdoc.tcl generates two intermediate files, which contain
the same information, but in different format - one in XML
format (mashdoc.xml) and the other in Tcl list format (mashdoc.list)
5.2 tcllist2html.tcl
tcllist2html.tcl reads mashdoc.list and generates HTML
documentation. It takes in a single option "-o", which
specify where to put the generated HTML files. The last
argument passed to the tcllist2html is assumed to be the
input file (which typically is mashdoc.list).
5.3 Example
smash mashdoc.tcl $HOME/mash-code/mash
smash tcllist2html.tcl -o html mashdoc.list
5.4 Support Files
The generate HTMLs depend heavily on CSS (mashdoc.css). It
also refers to logo.gif, which is a smaller version of
Open Mash logo. These two files should be located in the
same directory as the HTMLs.