Next: Documentation language
While most of this chapter is relevant to all languages supported by d4c&b, examples assume ``C++''.
Writing a top level entry
A top level entry discusses topics relevant to the whole directory. It makes no difference in which file a top comment resides. In ``C++'' there are two ways to write a top level comment.
/*@top topic name topic text ... */
//@top topic name // topic text // ...A ``C++'' comment ends at first non comment line, which can be an empty line as well.
Every directory might have one default topic, which contains text to be displayed when you visit that directory. A default topic is nameless,
/*@top Main directory text ... */
/*@chapter Chapter name chapter text ... */A file may have a one default chapter as well, which is shown when file is visited.
/*@chapter File main text ... */When a file contains several classes or functions, a default chapter is usually very helpful. It typically explains the relation between the different elements, and why they are in the same file.
Documenting elements
d4c&b documents language elements. In ``C++'' those include classes, methods, functions, and so on. An element is documented by placing a special auto comment before it. In ``C++'', an auto comment starts with 3 slashes,
/// summary line1 /// summary line 2 /// ... // elaborate line1 // ...An auto comment has 2 parts. The first part is the summary, where a short description of the element is given. The second part is an elaborate description. A viewer may choose to hide elaborate parts by selecting
concise in the configuration frame below the contents frame. Summary is made from all consecutive triple-/ lines and elaborate from all consecutive double-/ lines after that (but remember, an empty line terminates an auto comment).
/// this is class X
// more on class X
class X {
public:
/// first member
void f(int k);
...
};
Either summary or elaboration may be empty, or both.
/// typedef unsigned int uint;Is like saying ``add this typedef to documentation''.
//@ foo and goo: // ... /// foo /// goo