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. 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 The archive unpacks to a directory called kdoc. Change to this directory with If you downloaded the CVS modules, you won't need to do any unpacking, but you will need to type 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 KDOC is installed and ready to use. (Before continuing, you should log out and log in as a nonroot user.) | |
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: 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: 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, 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. 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. | |
@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.
| |
@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.)
| |
@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: 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: is allowed, whereas is not. The blank line tells KDOC to stop processing the @see or @image tag. | |
| |
