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
-
index.html - the initial page. This contains both
framed and no-frame content. Which format will be
displayed depends on whether your browser can display
frames:
- Frames-capable browser
- The initial page is the only frame set.
Its left frame contains the list of all documented
functions.
The right frame displays all other pages as they are
selected.
- No-frames browser
- The initial page contains links to the alphabetic
index of all items, the index of all functions,
the index of all header pages and this help page.
- all-items.html, an alphabetic list of every
publicly named item.
- all-functions.html, an index of all public
functions.
If frames are displayed, this forms the left-side
function index.
- all-headers.html, an index of all C header
files.
- help-page.html, which you're currently reading.
- A detailed page for each C header file.
Each has the same name as the header file but with a
.html extension.
Each page may include one or more sections
if appropriate content is found.
The sections are:
- an overview
- a list of any include files in the header
- functions declared in the header.
Each function is in a separate section identified by
its name.
This is followed by all includes in force,
its declaration, a description taken from the source
file, and the name of the source file containing the
function definition.
- constants and macros declared in the header
- typedefs declared in the header
- global variables declared in the header
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