Help page


Headers Index Help


Cdoc generates a set of interlinked HTML pages that form the documentation set for the public objects defined in one or more C header pages. The set of pages is always recreated in its entirety when cdoc is run; incremental documentation is not supported.

NOTE: cdoc's parser is minimalist in nature. In consequence there is no guarantee that cdoc will correctly interpret the contents of files that do not compile correctly or that contain wierd layouts or obfuscated code.

How Cdoc generates documentation

Cdoc generates a web page for every header file it processes. This contains all the available information about every publically accessable item declared in the header file and is extracted from the source files that define these items. In addition cdoc outputs a set of index pages and a copy of this page, which is intended to help you to understand why the generated documentation may not contain everything you expected, and what to do about it.

Public vs. private

The design aim of cdoc is to document every publically declared item in a C program. That is, anything that the programmer declared in a header file. Other items that are declared globally within a source file or within functions are treated as private and hence do not appear in cdoc's output.

Header file content

Header file declarations, e.g. function prototypes, constants, typedefs, macros and globals, are documented. During this process conditional preprocessor expressions are evaluated and the results of this determine what is included in cdoc output.

Comments in header files are always ignored.

Source file content

Source files are scanned to extract comments.

If the source file has the same name as the header being processed, the initial comment in the source file, which must come before everything else in it, is used as the overview for this header and the items declared in it. Initial comments in source files whose names do not match the header file name are ignored.

The comment that immediately preceeds a function definition is used as the function's description. All other comments in the source file are ignored.

During this process conditional preprocessor expressions are evaluated and the results of this determine what is included in cdoc output.

Controlling documentation layout

Cdoc output is affected by command line options. The command line looks like this:

java cdoc [<opts>] header files...

The options that affect output appearance are:

-D=sym=val
Define 'sym' with 'val' value. '=val' may be omitted. This is used to affect conditional text scanning in exactly the same way that a C compiler's -D options can be used to affect code generation.
-f
Retain line layout from the C source comments. If the C comments were formatted to underline function names or to form columns you can use this option to retain that layout. This will cause the overview and function descriptions to retain the same line layout that was used in the C comments. Otherwise each set of lines, separated by one or more blank lines is treated as a single paragraph and formatted accordingly by the web browser.

NOTE: text formatting may not work as expected if the source files you're scanning have a different newline convention to the one used by the operating system that is running cdoc, e.g if you're scanning DOS source files on a Linux or UNIX system you'll see that the comment lines retain their original line layout but are double spaced. To overcome this you can use a utility, such as dos2unix, to convert copies of the source files to the UNIX text standards or install Java on the system that the source files came from and run cdoc there. The first approach is known to work. The second should work too because it means you're running cdoc in a JVM that has been compiled to understand the text formatting conventions used in the source files.
-l
Force local includes to appear in function definitions. Normally these are excluded since they are private and should not affect programmers using library copies of the functions.
-L
Force includes to use diamond brackets around filenames. This may be needed if you're documenting a set of library routines in their development directory where the headers are local but the developers who use this documentation will be expecting to find the headers in, say, /usr/local/include.
-t=8
Set tabspacing to suit the C source file. During formatting cdoc will attempt to preserve the original line layout. As part of this process it expands tabs using a default width of 8 characters. If this gives an incorrect layout, the tab width can be changed with the -t option, e.g., -t=4 resets the tab width to four characters. This is probably most useful when used in conjunction with the -f option.

You can embed HTML tags in the comment if that will improve readability. Tags controlling bolding, italics, underline, linebreak, preformatting, paragraphs, emphasis, keyboard input, headings, bulletted lists, numbered lists, and definition lists are all preserved and will affect the documentation layout. All others are converted into literal words by escaping < and >

HTML escape sequences should not be used in comments because they will be converted into literal text. & characters will be escaped to preserve them.

Generated pages

Links from the header pages, the alphabetic index and help page to one or more of the indexes are part of each page's heading. All items in any of the indexes link to the item's description.


Return to the top