Coda2 is implemented in Tcl and designed into three distinct modules:
dump command of the text widget. When a doc-item has been parsed, it is passed on to the Docifier.The idea of Coda2 is to implement several compatible comment readers that can read comments from various types of programming languages (and other formats). Similarly, it should be possible to implement several compatible docifiers, that will produce outputs in various formats. This document specifies the interface of these modules.
A comment reader shall be implemented as a namespace having a predefined set of procs. Readers for different programming languages or commenting syntaxes should have different namespaces, which makes it really easy to extend Coda2 to accept new programming languages with any kind of commenting style (simply by implementing a new reader). In the sequel, the name of the namespace will be refferd to as CR (for comment reader).
There are two procs required to be implemented by a comment reader: GetNextItem and Init. The Init proc may take any number of arguments, the parameters to this proc must be specified internally for each comment style implemented by Coda. The purpose of the Init proc is to set up the reader to extract comments from a specific file format, and it will be called before reading each file (since one may run coda on several types of source files in one go).
GetNextItem should be called with the following syntax:
CR::GetNextItem channelID
The proc should start reading from the channel untill it encounters a Coda2 doc-item or the end of file. If a valid doc-item is found, the proc should return a list of input lines where the comment markup particular for the input language are stripped away, as for example inital pounds in tcl-comments. In theory, the proc should return pure text according to the Coda2 text format, although it is not the job of the reader to validate the text.
If the proc encounters the end of the file, it must return an empty string.
Coda2 will contain only one comment parser, which will interpret the doc-item according to the Coda2 text format specification. It will be assigned the name space CodaText, and will implement one proc which should be called with the following syntax:
CodaText::Parse headerVar textLines
It should return a list that has a similar structure that is returned by the dump command of the text widget:
key1 value1 key2 value2 ...
The possible values of key are:
begin link will immediately be followed by an url key.begin key, and the param will allways be empty.link item or a fig. It will be always occur as the first item subsequent to a begin link item.A docifier reader shall be implemented as a namespace having a predefined set of procs. Docifiers for different output formats should have different namespaces, which makes it really easy to extend Coda to produce new formats (simply by implementing a new docifier) with any kind of obscure commenting format. In the sequel, the name of the namespace will be refferd to as CD (for coda docifier).
The docifier namespace need to implement several procs, which should have the following call syntax:
CD::StartProject ?options?
Typically, a project will comprise several files which is to be documented. A set of files will be referred to as a project. The projectName identifies the name of the project. The following options should be supported:
The following proc will be called when all items of a project are docified:
CD::EndProject
Specifies that all files in the project has been parsed and docified. This is a good time to write out indexes contents and main files.
CD::Docify headerVar docText
design.txt"