Examples of sources that
DocBuilder can process
1. Simple comments
2. Comments (text units) with keywords and sub-entries
3. Javadoc/Doc++ comments
4. Named text units
5. Text units in separate files
6. Text units with commands
7. Flow text
Quick-start: Six steps up to your first automatic documentation
1. Simple comments
unsigned size() const; // Optionally a comment can be considered to be the description of // the function or code element. For this purpose it must be // located directly before or behind the code element.
2. Comments (text units) with keywords and sub-entries
(******************************************************************* * class: * * This is the description of a class. If the keyword "class" * * is specified in the DocBuilder dialog, DocBuilder will detect * * this comment as "official" description (text unit). * * * * "Frame characters" of the comment (here the characters '*' * * and '-') can be specified and removed then by DocBuilder * * ------------------------------------------------------------- * * @comment * * By keywords the text can be divided also in sub-entries. * * Keywords can be defined freely and contain blanks, * * such as following "See also". * * * * See also: * * ´´TClassB´´, ´´TClassC´´ * * (The double accent marks define cross references.) * * * * Note: * * Not each sub-entry must be transferred to the documentation! * *******************************************************************) type TClassA : class (TBaseClass) ... (* Class: If another programmer has selected this form of the documentation, the keyword "Class" should be specified additionally to the above "class", so that that this description is processed in the same way as the preceeding. Nevertheless, it is also possible to distinguish both text units by means of keyword (by so called "source pattern"). For this purpose you can assign different attributes to the different source patterns, and then both types of text units can be processed in a different way. *) type TClassB : class (TBaseClass) ...
3. Javadoc/Doc++ comments
/** * Comment patterns of Javadoc or DOC++ * Comments that begin with patterns "/**" and "///" (C/C++) or * "(**" (Pascal/Delphi), can be detected without an * introductory keyword as text units. This feature is optionally. * * @doc * The tags, defined in Javadoc or Doc++, like "@author" or "@doc" can * be defined automatically as sub-entries (cf. the corresponding dialog). * * @author Meier */
4. Named text units
//-------------------------------------------------------------------
// Variable: symtab The symbol table (global)
//-------------------------------------------------------------------
//
// If the text unit contains the name of the documented code element,
// it needs not to be located close to the code element. Then it can
// be located somewhere in the file.
//
// This text unit contains in its headline the key word "Variable", the
// (unqualified) name "symtab" and also a single-line brief description,
// the so called subject line.
//-------------------------------------------------------------------
// Forward declarations:
template<class T> class cHash;
class cSuperString;
namespace Globals {
cHash<cSuperString> symtab;
...
} // namespace Globals
5. Text units in separate files
stringdoc.txt:
--------------
Method: cSuperString::rotate
Description:
If the text unit contains the completely qualified name of the
code element, it can be located in a separate file.
superstring.hpp:
----------------
class cSuperString : public std::string {
...
cSuperString& rotate(int n = 1);
6. Text units with commands
function THandler.do_it(do_what: TAction): TResult;
(* @method
@des
The text unit can be structured by many commands, e.g.:
- paragraph formats like this enumerating,
@marnote{This is marginal note},
@b_verbatim
preformatted text, typically code examples
@e_verbatim
- Character formats as ´this is code format´,
@b{this is bold written} etc.
- Special characters as line feed (@endl) and
tabulators (@ltab<25mm>)
- Link targets @bookmark<target1>; and cross
references to automatically produced or user-defined
targets (see ´´cSuperString::rotate´´ or
@cref<target1>{cross references})
- @xe<{Index} Place entries> index entries
Note:
The most link targets and index entries are
automatically produced.
*)
7. Flow text
@text
@hdline{Example for the notation of arranged flow text}
Flow text is used normally for freely formulated paragraphs of a
documentation and has no sub-entries that are initiated by
keywords. Instead of that the flow text can be structured
by sub-headlines.
@sub1{Sub-headline - Level 1}
Headline levels are not absolute, but always relative to the
position of this text unit in the hierarchy of the produced
documentation. The absolute headline level of this text unit
is defined in the script file. Consequently a text unit can
be placed at different headline levels in different doc's.
You can configure the content of each new documentation as
desired and define also the concrete headline level depending
upon requirement.
@sub2{Sub-headline - Level 2}
Of course, all DocBuilder commands are available in
flow text. The inclusion of code examples that shall be
emphasize as source text occours e.g. with the
verbatim command:
@b_verbatim
class cExample; // used in the following prototypes
bool read_example ( cExample & e, const gString& fn);
bool write_example(const cExample & e, const gString& fn);
@e_verbatim
@sub3{Sub-headline - Level 3}
A @cref<target_name>{visible text over the link} to another place
of the documentation is set as here shown. If the reference
text, i.e. the text in {...}, is identical to the reference
target in <...>, the reference can be noted more briefly like this:
See the method ´´TClassA.method1´´.
@bookmark<target_name>
This is the explicite definition of a link target. However
the programm can generate link targets and index entries
also automatically for the text units.
DocBuilder Home | Overview | Advantages | Concepts | Download | FAQ
