docs: get rid of kernel-doc-nano-HOWTO.txt

-2

Documentation/00-INDEX

··· 228 228 - directory with info on the Linux ISDN support, and supported cards. 229 229 kbuild/ 230 230 - directory with info about the kernel build process. 231 - kernel-doc-nano-HOWTO.txt 232 - - outdated info about kernel-doc documentation. 233 231 kdump/ 234 232 - directory with mini HowTo on getting the crash dump code to work. 235 233 doc-guide/

-322

Documentation/kernel-doc-nano-HOWTO.txt

··· 1 - NOTE: this document is outdated and will eventually be removed. See 2 - Documentation/doc-guide/ for current information. 3 - 4 - kernel-doc nano-HOWTO 5 - ===================== 6 - 7 - How to format kernel-doc comments 8 - --------------------------------- 9 - 10 - In order to provide embedded, 'C' friendly, easy to maintain, 11 - but consistent and extractable documentation of the functions and 12 - data structures in the Linux kernel, the Linux kernel has adopted 13 - a consistent style for documenting functions and their parameters, 14 - and structures and their members. 15 - 16 - The format for this documentation is called the kernel-doc format. 17 - It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file. 18 - 19 - This style embeds the documentation within the source files, using 20 - a few simple conventions. The scripts/kernel-doc perl script, the 21 - Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand 22 - these conventions, and are used to extract this embedded documentation 23 - into various documents. 24 - 25 - In order to provide good documentation of kernel functions and data 26 - structures, please use the following conventions to format your 27 - kernel-doc comments in Linux kernel source. 28 - 29 - We definitely need kernel-doc formatted documentation for functions 30 - that are exported to loadable modules using EXPORT_SYMBOL. 31 - 32 - We also look to provide kernel-doc formatted documentation for 33 - functions externally visible to other kernel files (not marked 34 - "static"). 35 - 36 - We also recommend providing kernel-doc formatted documentation 37 - for private (file "static") routines, for consistency of kernel 38 - source code layout. But this is lower priority and at the 39 - discretion of the MAINTAINER of that kernel source file. 40 - 41 - Data structures visible in kernel include files should also be 42 - documented using kernel-doc formatted comments. 43 - 44 - The opening comment mark "/**" is reserved for kernel-doc comments. 45 - Only comments so marked will be considered by the kernel-doc scripts, 46 - and any comment so marked must be in kernel-doc format. Do not use 47 - "/**" to be begin a comment block unless the comment block contains 48 - kernel-doc formatted comments. The closing comment marker for 49 - kernel-doc comments can be either "*/" or "**/", but "*/" is 50 - preferred in the Linux kernel tree. 51 - 52 - Kernel-doc comments should be placed just before the function 53 - or data structure being described. 54 - 55 - Example kernel-doc function comment: 56 - 57 - /** 58 - * foobar() - short function description of foobar 59 - * @arg1: Describe the first argument to foobar. 60 - * @arg2: Describe the second argument to foobar. 61 - * One can provide multiple line descriptions 62 - * for arguments. 63 - * 64 - * A longer description, with more discussion of the function foobar() 65 - * that might be useful to those using or modifying it. Begins with 66 - * empty comment line, and may include additional embedded empty 67 - * comment lines. 68 - * 69 - * The longer description can have multiple paragraphs. 70 - * 71 - * Return: Describe the return value of foobar. 72 - */ 73 - 74 - The short description following the subject can span multiple lines 75 - and ends with an @argument description, an empty line or the end of 76 - the comment block. 77 - 78 - The @argument descriptions must begin on the very next line following 79 - this opening short function description line, with no intervening 80 - empty comment lines. 81 - 82 - If a function parameter is "..." (varargs), it should be listed in 83 - kernel-doc notation as: 84 - * @...: description 85 - 86 - The return value, if any, should be described in a dedicated section 87 - named "Return". 88 - 89 - Example kernel-doc data structure comment. 90 - 91 - /** 92 - * struct blah - the basic blah structure 93 - * @mem1: describe the first member of struct blah 94 - * @mem2: describe the second member of struct blah, 95 - * perhaps with more lines and words. 96 - * 97 - * Longer description of this structure. 98 - */ 99 - 100 - The kernel-doc function comments describe each parameter to the 101 - function, in order, with the @name lines. 102 - 103 - The kernel-doc data structure comments describe each structure member 104 - in the data structure, with the @name lines. 105 - 106 - The longer description formatting is "reflowed", losing your line 107 - breaks. So presenting carefully formatted lists within these 108 - descriptions won't work so well; derived documentation will lose 109 - the formatting. 110 - 111 - See the section below "How to add extractable documentation to your 112 - source files" for more details and notes on how to format kernel-doc 113 - comments. 114 - 115 - Components of the kernel-doc system 116 - ----------------------------------- 117 - 118 - Many places in the source tree have extractable documentation in the 119 - form of block comments above functions. The components of this system 120 - are: 121 - 122 - - scripts/kernel-doc 123 - 124 - This is a perl script that hunts for the block comments and can mark 125 - them up directly into DocBook, ReST, man, text, and HTML. (No, not 126 - texinfo.) 127 - 128 - - scripts/docproc.c 129 - 130 - This is a program for converting SGML template files into SGML 131 - files. When a file is referenced it is searched for symbols 132 - exported (EXPORT_SYMBOL), to be able to distinguish between internal 133 - and external functions. 134 - It invokes kernel-doc, giving it the list of functions that 135 - are to be documented. 136 - Additionally it is used to scan the SGML template files to locate 137 - all the files referenced herein. This is used to generate dependency 138 - information as used by make. 139 - 140 - - Makefile 141 - 142 - The targets 'xmldocs', 'latexdocs', 'pdfdocs', 'epubdocs'and 'htmldocs' 143 - are used to build XML DocBook files, LaTeX files, PDF files, 144 - ePub files and html files in Documentation/. 145 - 146 - How to extract the documentation 147 - -------------------------------- 148 - 149 - If you just want to read the ready-made books on the various 150 - subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs', 151 - depending on your preference. If you would rather read a different format, 152 - you can type 'make xmldocs' and then use DocBook tools to convert 153 - Documentation/output/*.xml to a format of your choice (for example, 154 - 'db2html ...' if 'make htmldocs' was not defined). 155 - 156 - If you want to see man pages instead, you can do this: 157 - 158 - $ cd linux 159 - $ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man 160 - $ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man 161 - 162 - Here is split-man.pl: 163 - 164 - --> 165 - #!/usr/bin/perl 166 - 167 - if ($#ARGV < 0) { 168 - die "where do I put the results?\n"; 169 - } 170 - 171 - mkdir $ARGV[0],0777; 172 - $state = 0; 173 - while (<STDIN>) { 174 - if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) { 175 - if ($state == 1) { close OUT } 176 - $state = 1; 177 - $fn = "$ARGV[0]/$1.9"; 178 - print STDERR "Creating $fn\n"; 179 - open OUT, ">$fn" or die "can't open $fn: $!\n"; 180 - print OUT $_; 181 - } elsif ($state != 0) { 182 - print OUT $_; 183 - } 184 - } 185 - 186 - close OUT; 187 - <-- 188 - 189 - If you just want to view the documentation for one function in one 190 - file, you can do this: 191 - 192 - $ scripts/kernel-doc -man -function fn file | nroff -man | less 193 - 194 - or this: 195 - 196 - $ scripts/kernel-doc -text -function fn file 197 - 198 - 199 - How to add extractable documentation to your source files 200 - --------------------------------------------------------- 201 - 202 - The format of the block comment is like this: 203 - 204 - /** 205 - * function_name(:)? (- short description)? 206 - (* @parameterx(space)*: (description of parameter x)?)* 207 - (* a blank line)? 208 - * (Description:)? (Description of function)? 209 - * (section header: (section description)? )* 210 - (*)?*/ 211 - 212 - All "description" text can span multiple lines, although the 213 - function_name & its short description are traditionally on a single line. 214 - Description text may also contain blank lines (i.e., lines that contain 215 - only a "*"). 216 - 217 - "section header:" names must be unique per function (or struct, 218 - union, typedef, enum). 219 - 220 - Use the section header "Return" for sections describing the return value 221 - of a function. 222 - 223 - Avoid putting a spurious blank line after the function name, or else the 224 - description will be repeated! 225 - 226 - All descriptive text is further processed, scanning for the following special 227 - patterns, which are highlighted appropriately. 228 - 229 - 'funcname()' - function 230 - '$ENVVAR' - environment variable 231 - '&struct_name' - name of a structure (up to two words including 'struct') 232 - '@parameter' - name of a parameter 233 - '%CONST' - name of a constant. 234 - 235 - NOTE 1: The multi-line descriptive text you provide does *not* recognize 236 - line breaks, so if you try to format some text nicely, as in: 237 - 238 - Return: 239 - 0 - cool 240 - 1 - invalid arg 241 - 2 - out of memory 242 - 243 - this will all run together and produce: 244 - 245 - Return: 0 - cool 1 - invalid arg 2 - out of memory 246 - 247 - NOTE 2: If the descriptive text you provide has lines that begin with 248 - some phrase followed by a colon, each of those phrases will be taken as 249 - a new section heading, which means you should similarly try to avoid text 250 - like: 251 - 252 - Return: 253 - 0: cool 254 - 1: invalid arg 255 - 2: out of memory 256 - 257 - every line of which would start a new section. Again, probably not 258 - what you were after. 259 - 260 - Take a look around the source tree for examples. 261 - 262 - 263 - kernel-doc for structs, unions, enums, and typedefs 264 - --------------------------------------------------- 265 - 266 - Beside functions you can also write documentation for structs, unions, 267 - enums and typedefs. Instead of the function name you must write the name 268 - of the declaration; the struct/union/enum/typedef must always precede 269 - the name. Nesting of declarations is not supported. 270 - Use the argument mechanism to document members or constants. 271 - 272 - Inside a struct description, you can use the "private:" and "public:" 273 - comment tags. Structure fields that are inside a "private:" area 274 - are not listed in the generated output documentation. The "private:" 275 - and "public:" tags must begin immediately following a "/*" comment 276 - marker. They may optionally include comments between the ":" and the 277 - ending "*/" marker. 278 - 279 - Example: 280 - 281 - /** 282 - * struct my_struct - short description 283 - * @a: first member 284 - * @b: second member 285 - * 286 - * Longer description 287 - */ 288 - struct my_struct { 289 - int a; 290 - int b; 291 - /* private: internal use only */ 292 - int c; 293 - }; 294 - 295 - 296 - Including documentation blocks in source files 297 - ---------------------------------------------- 298 - 299 - To facilitate having source code and comments close together, you can 300 - include kernel-doc documentation blocks that are free-form comments 301 - instead of being kernel-doc for functions, structures, unions, 302 - enums, or typedefs. This could be used for something like a 303 - theory of operation for a driver or library code, for example. 304 - 305 - This is done by using a DOC: section keyword with a section title. E.g.: 306 - 307 - /** 308 - * DOC: Theory of Operation 309 - * 310 - * The whizbang foobar is a dilly of a gizmo. It can do whatever you 311 - * want it to do, at any time. It reads your mind. Here's how it works. 312 - * 313 - * foo bar splat 314 - * 315 - * The only drawback to this gizmo is that is can sometimes damage 316 - * hardware, software, or its subject(s). 317 - */ 318 - 319 - DOC: sections are used in ReST files. 320 - 321 - Tim. 322 - */ <twaugh@redhat.com>

+1 -1

scripts/kernel-doc

··· 48 48 and print formatted documentation to standard output. 49 49 50 50 The documentation comments are identified by "/**" opening comment mark. See 51 - Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax. 51 + Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. 52 52 53 53 Output format selection (mutually exclusive): 54 54 -docbook Output DocBook format.

Configure Feed

Configure Feed