Chapter 15. Creating Documentation

by David Sweet

In This Chapter

Much effort is put into making the process of creating documentation simpler for other developers and end users. Standards exist for writing such documentation, as do software tools to help you turn your documentation into attractive, accessible formats. In this chapter you learn about two such standards: the KDE source-code documentation style and DocBook and their related software tools.

15.1. Documenting Source Code

As mentioned in earlier chapters, it is important to document source code so that you and others can read and understand it later on. When you are attempting to manage a large collection of classes and functions, you will undoubtedly forget precisely how some of them work. Comments in the class declarations (in the header files), for example, can serve as a handy reference when this happens. Of course, if others want to use or change one of your classes, they will appreciate all the help they can get. If you are writing open source code, you will probably appreciate it when other developers send you patches, and again, it is easier for others to create patches if your code is documented.

In a large project, such as the KDE project, in which hundreds of developers are writing and hacking at hundreds of thousands of lines of source code, documentation becomes invaluable. The utility of such documentation was realized early on and a documentation standard was created.

KDE developers put special comments in their header files before each class and method name. These comments can be processed by a set of Perl scripts called KDOC. (This documentation style is similar to that used by JavaDoc, a Java language documentation preparation program.) KDOC can create output in HTML, DocBook, LaTeX, TeXInfo, and UNIX man page formats. The default format, HTML, is the one most commonly used in the KDE project. You can see samples of KDOC output on the KDE developers' Web site at http://developer.kde.org/documentation/library/2.0-api/classref/index.html. This page contains links to documentation of the KDE 2.0 API documentation.

15.1.1. Obtaining and Installing KDOC

The KDOC source code is available from http://www.ph.unimelb.edu.au/~ssk/kde/kdoc or from the KDE CVS source code repository in the module kdoc (see Chapter 17, "Managing Source Code with CVS" for information on retrieving modules from the source code repository).

KDE 2.0 uses KDOC 2, so if you visit the Web site (where both KDOC 1 and KDOC 2 are available), be sure to get KDOC 2.

Be sure you have Perl 5.005 (or later, see http://www.cpan.org) installed before you attempt to install KDOC 2.

If you downloaded the file (a compressed tar archive) kdoc-snapshot.tar.gz from the Web site mentioned earlier, you should unpack it with


   1 
   2 gzip -d kdoc-shapshot.tar.gztar -xvf kdoc-snapshot.tar

The archive unpacks to a directory called kdoc. Change to this directory with


   1 
   2 cd kdoc

If you downloaded the CVS modules, you won't need to do any unpacking, but you will need to type


   1 
   2 cd kdocmake -f Makefile.cvs

to prepare the directory for use.

In either case—whether you downloaded the archive from the Web site or the module from CVS—you are ready to compile and install kdoc. Log in as root and type


   1 
   2 ./configuremake install

KDOC is installed and ready to use. (Before continuing, you should log out and log in as a nonroot user.)

15.1.2. Using KDOC

Using KDOC is simple. You add a comment before each class declaration and inside class declarations before each method or enum declarations. These comments are C-style, like this:


   1 
   2 /**
   3  * This is a KDOC comment.
   4  */

Notice that the first line begins with /**. The double asterisk is the signal to KDOC that it should process this comment. Comments without the double asterisk are ignored. Each subsequent line should begin with an asterisk. Note that these comments appear in header files. KDOC is not designed to process comments in source-code files.

The comments should describe the element—class, method, or enum—that they precede. Look at Listing 15.1 as an example. One large comment describes the class by telling what it does, who wrote it, what version it is, and so on. The comments preceding the methods tell what function the methods perform, what their arguments mean, and so on.


Example 15.1. kdocsample.h: A Class Declaration Commented for Processing by KDOC

   1 
   2  1: #ifndef __KDOCSAMPLE_H__
   3  2: #define __KDOCSAMPLE_H__
   4  3:
   5  4: /**
   6  5:  * @libdoc A single-class library.
   7  6:  *
   8  7:  * This comment is the overall documentation for entire library.
   9  8:  * It could appear in any one header file.
  10  9:  * The single class in this library is called @ref KDocSample.
  11 10:  **/
  12 11:
  13 12:
  14 13: /**
  15 14:  * This header file is documented in kdoc format.
  16 15:  *
  17 16:  * This is a new paragraph of documentation because it is preceeded
  18 17:  * by a blank line.  The string "/**" above marks this comment as
  19 18:  * documentation.
  20 19:  *
  21 20:  * If this class created a widget, we might put a small screenshot
  22 21:  *  here:
  23 22:  * @image /home/dsweet/KDE/HEAD/kde/share/icons/large/hicolor/apps/go.png
  24 23:  * @short Sample documented header file
  25 24:  * @author Joe Developer <jdevel@kde.org>
  26 25:  * @version 1.0
  27 26:  */
  28 27: class KDocSample
  29 28: {
  30 29:  public:
  31 30:   /**
  32 31:    * @sect Important stuff
  33 32:    *
  34 33:    * Instantiate this class.
  35 34:    *
  36 35:    * Notes
  37 36:    * @li Don't forget to …
  38 37:    * @li Be sure to …
  39 38:    * @param goodstuff Some good stuff to document.
  40 39:    * @see getStuff
  41 40:    **/
  42 41:   KDocSample (QString goodstuff);
  43 42:
  44 43:   /**
  45 44:    * Retrieve the good stuff.
  46 45:    *
  47 46:    * @since one two three
  48 47:    * @returns The good stuff.
  49 48:    * @exception some_exception some_other_exception
  50 49:    **/
  51 50:   virtual QString getStuff () const;
  52 51: };
  53 52:
  54 53:
  55 54: #endif

You can create HTML output with the following command:


   1 
   2 kdoc -d KDocSampleOutput -n KDocSample kdocsample.h

This command instructs KDOC to create its HTML output—a collection of .html files—in the directory MyLibraryOutput (via the option -d) and to name the collection of files (within the documentation files) KDocSample (via the option -n). kdoc can take multiple filenames as input. For example,


   1 
   2 kdoc -d MyLibraryOutput -n MyLibrary *.h

processes all header files with the extension .h in this directory into a collection of HTML files in the directory MyLibraryOutput and titles it MyLibrary. Figure 15.1 shows some of the HTML output as viewed by Konqueror.


Figure 15.1. Screen shot of Konqueror viewing the HTML output of kdoc given kdocsample.h as input.


Each KDOC-formatted comment can include the following elements:

  • Unformatted text—Each paragraph is separated by an empty line (that is, an asterisk followed only by whitespace).

  • <pre>…</pre> tags—These tags mark preformatted text, such as code segments (the same as in HTML).

  • Tags beginning with the @ character—One such tag, @author name, tells who the author of the code is. Other possible KDOC tags are described in the next section.

The next sections detail tags that can be used when formatting comments for KDOC.

15.1.3. Library Documentation

15.1.4. Class Documentation

  • @short Short description—Offers a short description of the class.

  • @author authorName—Specifies the name of the author of the class.

  • @version version—Specifies the version of the class.

  • @internal—Indicates that a class is used only internally by a library.

  • @deprecated—Indicates that a class is deprecated.

15.1.5. Method Documentation

  • @param parameterName description—Describes one of the parameters (arguments) that is passed to this function.

  • @returns description—Describes the value returned by this method.

  • @since version—Says that this method was added in version version of the class.

  • @exception ref1 ref2 —Tells what exceptions might be thrown from this function.

  • @throws ref1 ref2 —Tells what exceptions might be thrown from this function. (Same as @exception.)

  • @raises ref1 ref2 —Tells what exceptions might be thrown from this function. (Same as @exception.)

15.1.6. Class and Method Documentation

  • @see ref1 re2 —Provides cross-reference to one or multiple other classes or methods. The arguments ref1, ref2, and so on have the format Classname or Classname::method. KDOC will turn these references into hyperlinks (when producing HTML output) if it can. Note: Don't include the parentheses or arguments when naming methods. That is, use method, not method().

  • @ref ref—This is an inline cross-reference. For example, the following text:


       1 
       2 * Take a look at @ref KClass, it's a good one!

    includes a hyperlinked (if possible) reference to KClass.

  • @image pathOrUrl—Includes an image that can be found at the path or URL pathOrURL.

  • @sect sectionName—Starts a new section of the documentation and cells it sectionName

  • @li listItem—Includes a list item (<LI> in HTML) called listItem at this point in the document.

The tags @see and @image need to be followed by a blank KDOC comment line. For example:


   1 
   2 * @see KOtherClass
   3   *
   4   * @version 1.0

is allowed, whereas


   1 
   2   * @see KOtherClass
   3   * @version 1.0

is not. The blank line tells KDOC to stop processing the @see or @image tag.