Coda 2 User Manual

Agnar Renolen
version 1.1, August 29th, 2001




Coda2 comes in two versions: coda which is the command-line version and wcoda which provides a GUI on top of coda.

Coda reads specially formatted comments in the source code, and produces output in various formats. This version of Coda support output in HTML and LaTeX. Support for WinHelp and Unix man pages are on the wish list. Coda can also read comments from several programming languages. Coda is packaged with support for Tcl, Perl, C, C++, C#, Java, Pascal, Emacs Lisp and Visual Basic. Coda also support reading pure text files containing raw CodaText. However, Coda can be customized to support other formats as well.


The calling syntax of coda is as follows:

coda [-q] [-t format] [-d dir] [-r pattern] [-f file] pattern1 [pattern2 ...]

The parameters have the following meaning.

Specifies the output format. Legal values of format are:
Will generate an index.html file, along with a table of contents file (toc.html), and one file for each doc-item. Those doc-items which are of type "item" (whichever is the default), will be included in the table of contents, the others not.
Will generate a main.tex file, and one file for each doc-item. Those doc-items which are of type "document" will generate standalone latex articles, the others will be included in the main file.
If ommited, the target format defaults to html.
Specifies the target directory where coda is to put the output files. The default value is doc
Specifies that all files in the current directory and in all subdirectories matching a pattern is to be docified. This options can be repeated many times with different patterns.
Specifies that a file named file contains a list of files to docify. This option is also repeatable.
Tells coda to be quiet, that is, no output will be given during progress.

The remaining arguments, pattern1, pattern2 and so forth, specifies the files to docify in the current directory.


The text format recognized by coda is called CodaText. It is a text format designed for documenting source code by writing the documentation as comments within the source files. The main purpose of designing this format is to provide a text format that is:

You may read the CodaText format specification about the CodaText format.


Coda has implemented two readers that extract comments from various file formats. These readers handle two distinct types of commenting syntax:

embrace style comments
This types of comments are recognized by a sequence of characters that identifies the beginning of a comment, and another sequence identifying the end of a comment. Typical examples of this type of comments syntax is implemented in C/C++ where comments are started by the sequence "/*" and ended by the sequence "*/", and pascal, where comments are embraced between a pair of curly braces.
prefix style comments
This type of comments are recognized by a sequence of characters that start a comment, which is ended by the subsequent newline. Typical exapmles of this type of comment syntax is implemented in Tcl and Perl where comments are prefixed by a "#" character and C++ where comments can be prefixed by a pair of forwards slashes ("//").

Coda has implemented three readers:

Reads comments with embrace style comments.
Reads comments with prefix style comments.
Reads text files containing pure CodaText.

Each of these readers needs some parameters to interpret the source file correctly. These parameters are

coda prefix
This is the prefix that starts a coda comment. This prefix must begin with the string that opens a normal comment, must contain at least one extra character so coda distinguish the comments written for coda, and those that are not. It is recommended that no other characters than the prefix is included in the first line of a coda comment.
line prefix
For prefix style comments, this will be the sequence of characters that identifies comments in general. For embrace style comments, this is a character that you can add at the beginning of the line to make the comment stand out from the source code, and that coda will ignore during input. This character must be contained in the prefix, and it must be in the same column as the first occurence of the same character in the prefix.
comment suffix
This is the character sequence that identifies the end of a embrace-style comment.

Coda has implemented the following comment styles:

  comment      comment             coda        line     comment
  type         reader             prefix      prefix    suffix
  pascal       EmbraceReader        {**         *          } 
  c            EmbraceReader        /**         *          /* 
  script       PrefixReader         ##          # 
  lisp         PrefixReader         ;;          ; 
  basic        PrefixReader         ''          ' 
  coda         PlainReader

Coda has set up the following mapping between the comment type and the extensions of files.

.c .h .cp .cpp .hp .hpp .java .cs
.tcl .pl .cgi
.txt .coda


Suppose that you want to add suport for PostScript files. PostScript uses prefix style comments, and "%" as the comment prefix. In order to distinguish comments written for coda from other comments (including DSC comments), we want to prefix all coda-comments with a triple percent ("%%%").

In your home directory (for windows users, that'l be "C:\" or the directory specified by your "HOME" environment variable), add a file named .codarc. This is a tcl file that will be 'sourced' in by coda upon startup, if it exists. Note that coda will be sourced in within the coda namespace, so you can only manipualte the variables within the coda namespace, unless you use the global namespace qualifier.

First, we must define a new comment type. For this, coda maintains an array variable named formatMap. Each entry in this array contains a two-element list where the first element is the name of the name space that implements the reader, and the second element is the intialization parameters to the reader. Hence we include following line in the .codarc file:

set formatMap(postscript) {PrefixReader {"%%%" "%"}}

The next thing we do, is to provide a mapping between file extensions and our new postscript comment type. It is the array named extMap which holds this mapping. The following lines will map files with extensions ".ps" and ".eps" to the postscript comment type:

set extMap(.ps) postscript
set extMap{.eps) postscript

And that's all you have to do to make coda accept coda comments from postscript files.

For comprehensivenes, we also provide an example for reading html comments, just to show an example of embrace-style comments:

set formatMap(html) {EmbraceReader {"<!----" "-" "-->"}}
set extMap(.html) html
set extMap(.htm)  html


Now, suppose that you'd like coda to provide a new output format, or a so called docifier. In the Design Specification you may read about the interface between coda and it's docifiers. Suppose that you have implemented an xml docifier, put in in a namespace called XmlOut in the file XmlOut.tcl. First, you need to 'source' in the file, which you can do by adding the following line in the .codarc file in your root directory:

source "XmlOut.tcl"

You might want to provide the full path to the tcl file to make sure that it will be read in all situations.

Coda has an array variable named targetMap which maps target formats to their corresponding docifiers. In order to make coda recognize the new output format, say, with the -t xml option, you simply add the following line in the .codarc.

set targetMap(xml) XmlOut

However, once you've implemented your docifier, and it works well, please submit it to the authors of coda, and they'd be happy to include the format in the next release.

in file: "manual.txt"