docguide.docs 7.96 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2 3
/*!

@page docguide Documentation Guidelines
4

Pekka Pessi's avatar
Pekka Pessi committed
5 6 7
@section doxygen Using Doxygen

Doxygen is a document generation program, used by many C/C++ projects. Its
8
home page is at <a href="http://www.doxygen.org">http://www.doxygen.org</a>.
Pekka Pessi's avatar
Pekka Pessi committed
9 10 11
The Sofia documentation is written using Doxygen.

Doxygen works by extracting the documentation data both from the actual
12 13 14
C/C++ source code and from the specially formatted comments.
The comments can contain some Javadoc-like
@ref doxycommands "special commands".
Pekka Pessi's avatar
Pekka Pessi committed
15 16 17 18 19 20

In general the the style of the comments and documentation should follow the
<a href="http://java.sun.com/j2se/javadoc/writingdoccomments/">
javadoc style guide</a>.

A Doxygen comment must either contain reference about the entity
21
it is describing, e.g., command
Pekka Pessi's avatar
Pekka Pessi committed
22 23 24
\@file when describing files:
@verbatim
/**
25 26
 * @file foo.c
 *
Pekka Pessi's avatar
Pekka Pessi committed
27
 * Implementation of foo. The foo takes care of grokking xyzzy.
28
 *
Pekka Pessi's avatar
Pekka Pessi committed
29
 * @author Jaska Jokunen <jaska.jokunen@company.com> \n
30
 *
Pekka Pessi's avatar
Pekka Pessi committed
31 32 33 34 35 36 37 38 39 40 41 42
 * @date Created: Wed Oct 20 15:06:51 EEST 2004 jasjoku
 */
@endverbatim

Usually the entity that is documented comes straight after the documentation
comment. For example, documenting a function happens like this:
@anchor orch
@verbatim

/**
 * Orches a candometer. If orching candometer is not possible, it
 * tries to schadule hearping.
43
 *
44 45 46
 * @param[in]  k        pointer to a candometer
 * @param[in]  level    orching level
 * @param[out] return_hearping return value for schaduled hearping
Pekka Pessi's avatar
Pekka Pessi committed
47 48 49 50
 *
 * @return
 * The function orch() returns the candometer value, or #ERROR upon an error.
 * If the returned value is 0, the newly schaduled hearping is returned in
51
 * @a return_hearping.
Pekka Pessi's avatar
Pekka Pessi committed
52
 */
53
int orch(cando_t *k, int level, hearping_t *return_hearping)
Pekka Pessi's avatar
Pekka Pessi committed
54 55 56 57 58 59 60 61
{
  ...
}
@endverbatim

@subsection doxyfile Doxyfile and Doxyfile.conf

The doxygen options are specified through a configuration file,
62 63
<i>Doxyfile</i>. As a convention, a module-specific Doxyfile includes
a common file libsofia-sip-ua/docs/Doxyfile.conf. This makes it possible
Pekka Pessi's avatar
Pekka Pessi committed
64 65 66 67 68 69
to keep the module-specific Doxyfiles as clean as possible:

@code
PROJECT_NAME         = "ipt"
OUTPUT_DIRECTORY     = ../docs/ipt

70
INPUT 		     = ipt.docs .
Pekka Pessi's avatar
Pekka Pessi committed
71 72 73 74 75 76 77 78 79 80 81 82

@INCLUDE = ../Doxyfile.conf

TAGFILES            += ../docs/docs/doxytags=../docs
TAGFILES            += ../docs/su/doxytags=../su
GENERATE_TAGFILE     = ../docs/ipt/doxytags
@endcode

From the file above, you can observe some conventions. The
Doxygen-generated HTML documentation is collected in @b docs
subdirectory at top level. A separate output directory is created for
each submodule under it. Doxytags for the module are generated in the @e
83
doxytags file in the output directory.
Pekka Pessi's avatar
Pekka Pessi committed
84

85
@subsection module_docs Module documentation in \<module\>.docs
Pekka Pessi's avatar
Pekka Pessi committed
86 87 88 89 90 91 92 93

Each module contains a documentation file containing at least the module
mainpage called @e \<module\>.docs. There should be the module
boilerplate information, for instance the following example is excerpt
contents of file @e ipt.docs:

@verbatim
/**
94
@MODULEPAGE "ipt" - Utility Module
Pekka Pessi's avatar
Pekka Pessi committed
95 96 97 98 99 100 101

@section ipt_meta Module Meta Information

Utility library for IP Telephony applications.

@CONTACT Pekka Pessi <Pekka.Pessi@nokia.com>

102
@STATUS @SofiaSIP Core library
Pekka Pessi's avatar
Pekka Pessi committed
103 104 105 106 107

@LICENSE LGPL

@section ipt_overview Overview

108
This module contain some routines useful for IPT applications, like
Pekka Pessi's avatar
Pekka Pessi committed
109 110 111 112 113 114 115 116 117
- ...
- ...
*/
@endverbatim

@section doxycommands Common Doxygen Commands

In this section we go through the most common Doxygen commands. All
the commands are explained in the manual.
118
The commands include
Pekka Pessi's avatar
Pekka Pessi committed
119 120
- @ref doxystyle "style commands (@@a, @@b, @@c, @@e, @@em, @@p)"
- @ref doxyfuncs "function parameters and return values (@@param, @@return, @@retval)"
121

Pekka Pessi's avatar
Pekka Pessi committed
122 123 124 125
@subsection doxystyle Style Commands - @a, @b, @c, @e

The text style can be changed with @@b @b (bold), @@c @c (code), or
@@e @e (italic) commands. Function argument names use style command
126
@@a.
Pekka Pessi's avatar
Pekka Pessi committed
127 128 129 130 131

For example, a sentence "The @b Content-Type header @a ct specifies the @e
media-type of the message body, e.g., @c audio/amr would be AMR-encoded
audio." is produced with commands like
@code
132
The @b Content-Type header @a ct specifies the @e media-type of
Pekka Pessi's avatar
Pekka Pessi committed
133
the message body, e.g., @c audio/amr would be AMR-encoded audio.
134
@endcode
Pekka Pessi's avatar
Pekka Pessi committed
135

136
The style commands have synonyms, e.g., @@em and @@e mean same, as
Pekka Pessi's avatar
Pekka Pessi committed
137 138 139 140 141 142
well as @@c and @@p.

@subsection doxyfuncs Function Parameters and Return Values - @param, @return, @retval

Parameters to a function are documented with @@param commands. (See
the @ref orch "orch()" function above.) As a convention, the data flow
143 144
direction [in], [out] or [in,out] is indicated in the brackets after the
@@param command keyword.
Pekka Pessi's avatar
Pekka Pessi committed
145 146 147 148 149 150 151 152

Return values can be documented in two alternative manners, either
using @@return command (see @ref orch "orch()") or @@retval command. The
latter is used if the function returns a small number of possible
values, e.g., enumeration or success/failure indication.

@verbatim
/**Schadule hearping.
153
 *
Pekka Pessi's avatar
Pekka Pessi committed
154
 * The function schadule() schadules a hearping.
155
 *
156
 * @param[in] h pointer to hearping
157
 *
Pekka Pessi's avatar
Pekka Pessi committed
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
 * @retval 0  hearping was successful
 * @retval -1 an error occurred
 */
int schadule(hearping_t *h)
{
  ...
}
@endverbatim

@subsection doxyexamples Example Blocks - @code, @endcode

An example code fragment can be included using @@code and @@endcode
commands.
@verbatim
/**Destroy a hearping.
173
 *
Pekka Pessi's avatar
Pekka Pessi committed
174
 * The function hearping_destroy() deinitializes a hearping and
175 176
 * reclaims the memory allocated for it.
 *
177
 * @param[in,out] h pointer to pointer to hearping
178
 *
Pekka Pessi's avatar
Pekka Pessi committed
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
 * The function clears the pointer to hearping, so it must be called
 * with a pointer to pointer:
 * @code
 *   hearping_destroy(&x->hearping);
 * @endcode
 */
void hearping_destroy(hearping_t **h)
{
@endverbatim

@subsection docpar Paragraphs

The command @@par can be used to divide text into paragraphs. The text on
the same line with @@par is used as a subtitle for the paragraph. The
commands @@date, @@note, @@bug, @@todo, @@sa (See Also) and
@@deprecated can be used to add common paragraphs to documentation entries.

@subsection docfiles Documenting Files

In most files there is documentation entry for the file itself. It is
199 200
usually at top after the LGPL reference, containing @@file command or alias
@@CFILE/@@IFILE. There are Emacs macros for creating the boilerplate entry.
Pekka Pessi's avatar
Pekka Pessi committed
201 202 203 204 205 206

@subsection docgrouping Grouping Entries

When the structure of the documentation does not follow directory or file
structure, it is possible to use grouping commands @@defgroup and @@ingroup.
The command @@defgroup creates a group, and @@ingroup adds an entry to an
207
group.
Pekka Pessi's avatar
Pekka Pessi committed
208 209 210 211 212 213 214 215 216 217

@subsection doclinking Creating Links

Normally, Doxygen creates links to classes (and C structs) when it
encounters the struct/class name.  It is also possible to add links to
functions, type names and variables. If the function name is followed by
pair of parenthesis (), Doxygen creates a link to it. If a type name or
variable is prefixed with hash @#, Doxygen creates a link to it.

It is also possible to create links with freely selected link to
218
documentation entries with @@link and @@endlink commands.
Pekka Pessi's avatar
Pekka Pessi committed
219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249

When the link target is a named page, section, or subsection, it is possible
to use the @@ref command.

@subsection doctext Writing Body Text

The main body of the documentation is specified with @@mainpage command. The
contents of the @@mainpage entry become the HTML home page of the
documentation set. In each documentation set generated with Doxygen there
can be only one @@mainpage command. Commands @@section, @@subsection, and
@@subsubsection can be used to structure the body text.

It is also possible to add individual HTML pages to the documentation. It
happens with @@page command. These individual pages are like the home page
added with @@mainpage, they can be accessed with the Related Pages link from
the navigation bar.

@subsection docimages Adding Images

Images are added with @@image command. As the different documentation
formats support different image formats, the @@image has list the image file
name for each supported documentation format. The following example uses
bitmap image for HTML documentation and Encapsulate PostScript for
print documents:
@code
@image html sip-parser.gif

@image latex sip-parser.eps
@endcode

*/