1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
Document Structure
------------------
o Introduction
o Quick Start
o Example
o Tool Usage
o References
Introduction
------------
We have settled on KDOC as the documentation system for source code.
KDOC is written for and used by the KDE project. It's syntax is
derived from Javadoc.
Quick Start
-----------
kdoc comments are C comments that start with /** and end with */.
When a kdoc comment appears in an interface it is assumed to refer to
the code or declaration immediately following it. Thus a comment
appearing before a class describes the class, a comment appearing
before a method describes the method, and so forth.
Within a kdoc comment, tags can be used to provide hints to the
documentation system. Each tag, with the exception of @ref, should
appear on a line of it's own.
o Class Tags
@short <descr>
Provide a short description of a class. <descr> is limited to 1 line.
@author <descr>
Provide author details. <descr> is limited to 1 line.
@version <descr>
Provide version detail. <descr> is limited to 1 line.
@see [one or more references to classes or methods ]
Provide references to related documentation. When referring to a
class just use the class name, when referring to a method use
ClassName#MethodName, eg string#empty for string::empty().
o Method Tags
@param <param_name> <descr>
Provide a description of a method parameter. The description may span
multiple lines.
@return <descr>
Provide a description of the return value.
@exception <exception1> [<exception2> [ <exception3> ...]]
Provide a list of exceptions that may be thrown by method.
@see <ref1> [<ref2> [<ref3> ...]]
See description in Class Tags.
o Constants, Enums
@see <ref1> [<ref2> [<ref3> ...]]
See description in Class Tags.
o Bonus Magic
@ref <ref1> [<ref2> [<ref3> ...]]
Like @see, but can appear anywhere in the documentation.
<pre>...code fragment... </pre>
Provide a piece of pre-formatted text, such as a code fragment,
that kdoc should not examine.
o KDOC style
In general, we try to follow the Javadoc style (see the URL in
section "Web Links"). Some of the exceptions from those guidelines are:
- If the @param description is longer than a line, you may add an
empty "* " line before the next @param or @return if it helps to
improve readability.
- Always add a period (i.e., ".") after a @param or @return statement
to indicate end-of-statement, even if the description is not
a complete sentence.
- The short version of a descriptor of a method or a class should
always start with a capital letter. Note that this doesn't apply
for the first letter in a @param or @return statement.
- If the short version of a descriptor of a method or a class is a
title-like, such as "Default constructor", don't add a period after it.
If the short descriptor is like a statement then add a period after it:
"Copy the raw address to an in6_addr structure."
Example
-------
/**
* @short A class to format text messages.
*
* This class pulls text from an input stream and pushes it out on an
* output stream. Each line pushed out may have optional decoration
* characters prepended and appended.
*
* Example usage might be along the lines of:
*
* <pre>
* Formatter f(cin, cout);
* f.set_line_introduction("oh dear: ");
* ...
* </pre>
*/
class Formatter
{
public:
/**
* Constructor
*
* @param istr input stream.
* @param ostr output stream.
*/
Formatter(istream& istr, ostream& ostr);
~Formatter();
/**
* Set the introductory text for each output by the formatter.
*
* @param msg the text to be prepended to each line.
*/
void set_line_introduction(const char* msg);
/**
* @return the text being prepended to each line.
* @see Formatter#set_line_introduction
*/
const char* line_introduction() const;
};
Tool Usage
----------
kdoc <filename>
kdoc supports a range of command line arguments for customizing output
directories, presentation, etc. The kdoc(1) manual page describes
these in detail.
Web Links
---------
The links below should be helpful if you are just starting. If you
find, or know of any other, links that would be appropriate please add
them here.
kdoc web page:
http://www.ph.unimelb.edu.au/~ssk/kde/kdoc/
Javadoc HOWTO:
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
Javadoc comment specification:
http://java.sun.com/docs/books/jls/first_edition/html/18.doc.html
|
