aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorRobert P. J. Day <rpjday@mindspring.com>2007-02-10 04:45:58 -0500
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-02-11 13:51:32 -0500
commit262086cf5b5343c2b81c97b1c606058e921859df (patch)
treec45f2b849ddfedef19a742714d9349838184eeb4 /Documentation
parent78137e3b34e122949e6de36a894fb5843664b8f9 (diff)
[PATCH] Discuss a couple common errors in kernel-doc usage.
Explain a couple of the most common errors in kernel-doc usage. Signed-off-by: Robert P. J. Day <rpjday@mindspring.com> Acked-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/kernel-doc-nano-HOWTO.txt37
1 files changed, 33 insertions, 4 deletions
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
index 6ca507f40749..2075c0658bf5 100644
--- a/Documentation/kernel-doc-nano-HOWTO.txt
+++ b/Documentation/kernel-doc-nano-HOWTO.txt
@@ -107,10 +107,14 @@ The format of the block comment is like this:
107 * (section header: (section description)? )* 107 * (section header: (section description)? )*
108(*)?*/ 108(*)?*/
109 109
110The short function description cannot be multiline, but the other 110The short function description ***cannot be multiline***, but the other
111descriptions can be (and they can contain blank lines). Avoid putting a 111descriptions can be (and they can contain blank lines). If you continue
112spurious blank line after the function name, or else the description will 112that initial short description onto a second line, that second line will
113be repeated! 113appear further down at the beginning of the description section, which is
114almost certainly not what you had in mind.
115
116Avoid putting a spurious blank line after the function name, or else the
117description will be repeated!
114 118
115All descriptive text is further processed, scanning for the following special 119All descriptive text is further processed, scanning for the following special
116patterns, which are highlighted appropriately. 120patterns, which are highlighted appropriately.
@@ -121,6 +125,31 @@ patterns, which are highlighted appropriately.
121'@parameter' - name of a parameter 125'@parameter' - name of a parameter
122'%CONST' - name of a constant. 126'%CONST' - name of a constant.
123 127
128NOTE 1: The multi-line descriptive text you provide does *not* recognize
129line breaks, so if you try to format some text nicely, as in:
130
131 Return codes
132 0 - cool
133 1 - invalid arg
134 2 - out of memory
135
136this will all run together and produce:
137
138 Return codes 0 - cool 1 - invalid arg 2 - out of memory
139
140NOTE 2: If the descriptive text you provide has lines that begin with
141some phrase followed by a colon, each of those phrases will be taken as
142a new section heading, which means you should similarly try to avoid text
143like:
144
145 Return codes:
146 0: cool
147 1: invalid arg
148 2: out of memory
149
150every line of which would start a new section. Again, probably not
151what you were after.
152
124Take a look around the source tree for examples. 153Take a look around the source tree for examples.
125 154
126 155