by December 5, 2002 0 comments



Documentation of programming code may be stated as a high priority at the beginning of a software project. But as the project proceeds and deadlines become stiff, the priority given to the documentation comes down and it may be totally neglected. The expected practice is to document the code as and when it is written. But it becomes mundane for the developers to update the code and its documentation at different places (files). Moreover, when the developer modifies the existing code, it’s likely that he may forget to update the documentation residing in a separate file. Though most programming languages provide facility to embed comments within the code, such comments are meant to lie within the source code files.

What if we want to maintain separate files for documentation? 

A solution is to embed the documentation within the code. Latest programming languages like Java and C# come with such documentation tools–Javadoc and XML documentation respectively. Numerous free and commercial documentation tools are available for other languages. But most of these tools are specific to a programming language. 

However, ROBODoc can be used to embed documentation within the source code written in any programming languages. As per ROBODoc’s manual it can be used to document C, C++, HTML, Perl, Basic, Fortran, Pascal, LISP, Tcl/Tk, Modula-2, Assembly language etc. Documentation using ROBODoc depends on the comment characters supported by the programming language (as we will see later). Since the comment characters supported by C/C++ (/*…*/ and //) are the also supported by Java, C#, JavaScript and PHP, ROBODoc can be used to document these languages too. Support for additional programming languages can be added by specifying their comment characters and recompiling ROBODoc. ROBODoc can produce documentation in a number of formats–HTML, plain text, RTF, LaTeX, and
AmigaGuide. 

Set up
You can download ROBODoc from www.xs4all. nl/~rfsber/Robo/robodoc.html#down (a few KB). Linux users can download the file robodoc-3.2.3.tar.gz. Extract the archive as:

tar —zxvf robodoc-3.2.3.tar.gz

This will produce a directory named robodoc-3.2.3. Change to this directory and issue:

./configure
make 
make install

This will produce the executable (robodoc) in the directory /usr/local/bin. In PCQLinux, this directory is in the PATH, by default. Windows users can download robodoc.exe and place it in the PATH. Since this article refers to the ROBODoc manual at places, you should also download the manual found at:
www.xs4all.nl/~rfsber/Robo/manual.html

Using ROBODoc
Let’s start off by trying to document some JavaScript code using ROBODoc. Throughout this article we produce documentation in HTML format. If you need it in other formats, refer to the ROBODoc manual. 

Consider the following JavaScript code residing in a JavaScript file named search.js (say). 

function simple_search(keyword)
{

keyword_found=false
…….
…….
…….
if (keyword_found==true) 
return true;

return false;
}

Given a keyword as parameter, the above function searches for it in an array (say) and returns true if the keyword is found, else returns a false. Now to document this code add the following lines, below the line – <script language=”JavaScript”>:

/****f* SearchProj/simple_search
* NAME
* simple_search: searches for a key- word in a array
* USAGE
* simple_search(keyword)
* FUNCTION
* Accepts a keyword as a parameter
* Iterates through the elemen-ts of the array
* And returns true if the keyword is found else returns false
* PARAMETERS
* keyword – the keyword to sear-ch for 
* RETURN VALUE
* true or false
/***
*/

The syntax of the above documentation code is:

<begin-marker><type><projectname>/<function-name>
<remark> <item-name>
<remark> <description>
<remark> <item-name>
<remark> <description>
…..
….
…..
<end-marker>
<closing —comment-character>

Here the <begin-marker> marks the beginning of a ROBODoc documentation para. The <begin-marker> is different for different programming languages and depends on the comment characters supported by the language. As per the ROBODoc’s manual, the <begin-marker> for C/C++ is “/****”. Since JavaScript supports C and C++ like commenting style, we use the same <begin-marker> for it. To find out the <begin-marker> for other languages, refer to the ROBODoc’s manual. 

The <type> in our example is “f” which specifies that we are documenting a function. Using ROBODoc you can also document a module (h), structure (s), class (c), method (m), variable (v) and constant (d). For example, a short documentation on the variable named keyword_found used in the simple_search( ) will be as follows:

/****v* SearchProj/simple_search/keyword_found
* NAME
*keyword_found: Set to tr-
ue if the keyword is found 
/***
*/

The <remark> character is also language dependent and for JavaScript we use “*” which is the remark character for C/C++. 
NAME, USAGE, FUNCTION, PARAMETER and OUTPUT are all reserved <item-names> for ROBODoc. ROBODoc supports a couple of other <item-names> which are listed in it’s manual. The <desc> can be any text describing the <item-name>. 

The <end-marker> – /*** – marks the end of the documentation para. The <end-marker> is also language specific like the <begin-marker> and the <remark> character.

The <closing-comment-character> must be present, if a multiline comment character pair like – /* and */ – is used. In our example, we have inserted */ after the <end-marker>. Failure to do this will through up errors, when the JavaScript file is executed. 

In case of single line comment character like //, the <closing-comment-character> is not required.

Now, to generate a HTML documentation for the function simple_search( ), issue the following command.

robodoc search.js search.htm TOC HTML

This will generate an html file named search.htm with a table of contents (TOC) at the top. Open search.htm in a web browser and voila, you can see a well-documented function with it’s purpose, parameters and returns. 

ROBODoc can be used to produce comprehensive and nicely formatted HTML documentation of programming code

Auto linking 
Suppose there are multiple functions in the same source file. If the documentation of one function contains the name of the other, then ROBODoc automatically creates a hyperlink to the latter function. For example, suppose, search.js has another function called advanced_search( ) and it is documented as shown below:

/****f* SearchProj/advanced_search
* NAME
* advanced_search: improv-
es over the simple_search
* USAGE
* advanced_search(keywords)
* FUNCTION
* Accepts multiple key-
words as a String array 
* Iterates through the elemen-
ts of the array
* And returns true if all the key-words are found else retur-
ns false
* PARAMETERS
* keywords – a String array of key-words
* RETURN VALUE
* true or false
/***
*/

Create the html file again by issuing the above command and open search.htm. Note the text “simple_search,” under the item name NAME, has turned into a hyperlink which upon clicking shows the documentation of the simple_search( ) function.

Linking across documents
ROBODoc can also link functions when they reside in different source files. But this is not automatic and requires some efforts from our side. Suppose simple_search( ) function resides in search.js and advanced_search( ) function resides in another file called adv_search.js. First you need to create something called xref files corresponding to both the source files — search.js and adv_search.js. This is done as follows:

robodoc search.js search.htm GENXREF search.js.xref 

robodoc adv_search.js adv_search.htm GENXREF adv_search.js.xref

This will produce two files called search.js.xref and ad_search.js.xref . Next create a text file which contains the name of the two .xref files on separate lines as shown below.

search.js.xref
adv_search.js.xref

NOTE: After typing in the above lines, append one or more blank lines below. Unless you do this, there seems to be some problem in the correct creation of the master TOC file (see the next section). Save the file as xref_files.txt. Now generate the documentation for the two source files as:

robodoc search.js search.htm XREF xref_files.txt TOC HTML

robodoc adv_search.js adv_search.htm XREF xref_files.txt TOC HTML

The resulting files search.htm and adv_search.htm contain the documentation for the files search.js and adv_search.js, respectively. Launch adv_search.htm, which contains the documentation for the function advanced_search( ). You will find that the hyperlink “simple_search” is now linked to the documentation of the simple_search( ) function in
search.htm. 

ROBODoc can produce a master table of content which contains links to the documentation of all the variables, functions, structures, classes etc 

Master TOC
Using ROBODoc we can also generate a Master table of contents which contains links to all the variables, function, classes etc. in all the source files. With the xref_files.txt already generated, creating the Master TOC is a just a matter of issuing the following command.

robodoc xref_files.txt index.htm INDEX HTML TITLE “Master Table of Contents”

Here “Master Table of Contents” is the title given to the Master TOC. Launch index.htm in the Webbrowser to have a look at the Master TOC. 

For more on ROBODoc browse the URL www.xs4 all.nl/~rfsber/Robo/. Another free documentation tool similar to ROBODoc is SDoc, which can be found at www.cit.uws.edu.au/~ blilburn/sdoc/. 

Shekhar Govindarajan   

No Comments so far

Jump into a conversation

No Comments Yet!

You can be the one to start a conversation.

<