Advertisment

Documentation Made Easy

author-image
PCQ Bureau
New Update

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.

Advertisment

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. 

Advertisment

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:

Advertisment

./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. 

Advertisment

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 -

Advertisment