Commit | Line | Data |
---|---|---|
17defc28 JN |
1 | ========================== |
2 | Linux Kernel Documentation | |
3 | ========================== | |
4 | ||
5 | Introduction | |
6 | ============ | |
7 | ||
8 | The Linux kernel uses `Sphinx`_ to generate pretty documentation from | |
9 | `reStructuredText`_ files under ``Documentation``. To build the documentation in | |
10 | HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated | |
11 | documentation is placed in ``Documentation/output``. | |
12 | ||
13 | .. _Sphinx: http://www.sphinx-doc.org/ | |
14 | .. _reStructuredText: http://docutils.sourceforge.net/rst.html | |
15 | ||
16 | The reStructuredText files may contain directives to include structured | |
17 | documentation comments, or kernel-doc comments, from source files. Usually these | |
18 | are used to describe the functions and types and design of the code. The | |
19 | kernel-doc comments have some special structure and formatting, but beyond that | |
20 | they are also treated as reStructuredText. | |
21 | ||
22 | There is also the deprecated DocBook toolchain to generate documentation from | |
23 | DocBook XML template files under ``Documentation/DocBook``. The DocBook files | |
24 | are to be converted to reStructuredText, and the toolchain is slated to be | |
25 | removed. | |
26 | ||
27 | Finally, there are thousands of plain text documentation files scattered around | |
28 | ``Documentation``. Some of these will likely be converted to reStructuredText | |
29 | over time, but the bulk of them will remain in plain text. | |
30 | ||
31 | Sphinx Build | |
32 | ============ | |
33 | ||
34 | The usual way to generate the documentation is to run ``make htmldocs`` or | |
35 | ``make pdfdocs``. There are also other formats available, see the documentation | |
36 | section of ``make help``. The generated documentation is placed in | |
37 | format-specific subdirectories under ``Documentation/output``. | |
38 | ||
39 | To generate documentation, Sphinx (``sphinx-build``) must obviously be | |
40 | installed. For prettier HTML output, the Read the Docs Sphinx theme | |
41 | (``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also | |
42 | needed. All of these are widely available and packaged in distributions. | |
43 | ||
44 | To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make | |
45 | variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose | |
46 | output. | |
47 | ||
48 | To remove the generated documentation, run ``make cleandocs``. | |
49 | ||
50 | Writing Documentation | |
51 | ===================== | |
52 | ||
53 | Adding new documentation can be as simple as: | |
54 | ||
55 | 1. Add a new ``.rst`` file somewhere under ``Documentation``. | |
56 | 2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``. | |
57 | ||
58 | .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html | |
59 | ||
60 | This is usually good enough for simple documentation (like the one you're | |
61 | reading right now), but for larger documents it may be advisable to create a | |
62 | subdirectory (or use an existing one). For example, the graphics subsystem | |
63 | documentation is under ``Documentation/gpu``, split to several ``.rst`` files, | |
64 | and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from | |
65 | the main index. | |
66 | ||
67 | See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do | |
68 | with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place | |
69 | to get started with reStructuredText. There are also some `Sphinx specific | |
70 | markup constructs`_. | |
71 | ||
72 | .. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html | |
73 | .. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html | |
74 | ||
75 | Specific guidelines for the kernel documentation | |
76 | ------------------------------------------------ | |
77 | ||
78 | Here are some specific guidelines for the kernel documentation: | |
79 | ||
80 | * Please don't go overboard with reStructuredText markup. Keep it simple. | |
81 | ||
82 | * Please stick to this order of heading adornments: | |
83 | ||
84 | 1. ``=`` with overline for document title:: | |
85 | ||
86 | ============== | |
87 | Document title | |
88 | ============== | |
89 | ||
90 | 2. ``=`` for chapters:: | |
91 | ||
92 | Chapters | |
93 | ======== | |
94 | ||
95 | 3. ``-`` for sections:: | |
96 | ||
97 | Section | |
98 | ------- | |
99 | ||
100 | 4. ``~`` for subsections:: | |
101 | ||
102 | Subsection | |
103 | ~~~~~~~~~~ | |
104 | ||
105 | Although RST doesn't mandate a specific order ("Rather than imposing a fixed | |
106 | number and order of section title adornment styles, the order enforced will be | |
107 | the order as encountered."), having the higher levels the same overall makes | |
108 | it easier to follow the documents. | |
109 | ||
0249a764 MH |
110 | list tables |
111 | ----------- | |
112 | ||
113 | We recommend the use of *list table* formats. The *list table* formats are | |
114 | double-stage lists. Compared to the ASCII-art they might not be as | |
115 | comfortable for | |
116 | readers of the text files. Their advantage is that they are easy to | |
117 | create or modify and that the diff of a modification is much more meaningful, | |
118 | because it is limited to the modified content. | |
119 | ||
120 | The ``flat-table`` is a double-stage list similar to the ``list-table`` with | |
121 | some additional features: | |
122 | ||
123 | * column-span: with the role ``cspan`` a cell can be extended through | |
124 | additional columns | |
125 | ||
126 | * row-span: with the role ``rspan`` a cell can be extended through | |
127 | additional rows | |
128 | ||
129 | * auto span rightmost cell of a table row over the missing cells on the right | |
130 | side of that table-row. With Option ``:fill-cells:`` this behavior can | |
131 | changed from *auto span* to *auto fill*, which automatically inserts (empty) | |
132 | cells instead of spanning the last cell. | |
133 | ||
134 | options: | |
135 | ||
136 | * ``:header-rows:`` [int] count of header rows | |
137 | * ``:stub-columns:`` [int] count of stub columns | |
138 | * ``:widths:`` [[int] [int] ... ] widths of columns | |
139 | * ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells | |
140 | ||
141 | roles: | |
142 | ||
143 | * ``:cspan:`` [int] additional columns (*morecols*) | |
144 | * ``:rspan:`` [int] additional rows (*morerows*) | |
145 | ||
146 | The example below shows how to use this markup. The first level of the staged | |
147 | list is the *table-row*. In the *table-row* there is only one markup allowed, | |
148 | the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` ) | |
149 | and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row | |
150 | <last row>`). | |
151 | ||
152 | .. code-block:: rst | |
153 | ||
154 | .. flat-table:: table title | |
155 | :widths: 2 1 1 3 | |
156 | ||
157 | * - head col 1 | |
158 | - head col 2 | |
159 | - head col 3 | |
160 | - head col 4 | |
161 | ||
162 | * - column 1 | |
163 | - field 1.1 | |
164 | - field 1.2 with autospan | |
165 | ||
166 | * - column 2 | |
167 | - field 2.1 | |
168 | - :rspan:`1` :cspan:`1` field 2.2 - 3.3 | |
169 | ||
170 | * .. _`last row`: | |
171 | ||
172 | - column 3 | |
173 | ||
174 | Rendered as: | |
175 | ||
176 | .. flat-table:: table title | |
177 | :widths: 2 1 1 3 | |
178 | ||
179 | * - head col 1 | |
180 | - head col 2 | |
181 | - head col 3 | |
182 | - head col 4 | |
183 | ||
184 | * - column 1 | |
185 | - field 1.1 | |
186 | - field 1.2 with autospan | |
187 | ||
188 | * - column 2 | |
189 | - field 2.1 | |
190 | - :rspan:`1` :cspan:`1` field 2.2 - 3.3 | |
191 | ||
192 | * .. _`last row`: | |
193 | ||
194 | - column 3 | |
195 | ||
17defc28 JN |
196 | |
197 | Including kernel-doc comments | |
198 | ============================= | |
199 | ||
200 | The Linux kernel source files may contain structured documentation comments, or | |
201 | kernel-doc comments to describe the functions and types and design of the | |
202 | code. The documentation comments may be included to any of the reStructuredText | |
203 | documents using a dedicated kernel-doc Sphinx directive extension. | |
204 | ||
205 | The kernel-doc directive is of the format:: | |
206 | ||
207 | .. kernel-doc:: source | |
208 | :option: | |
209 | ||
210 | The *source* is the path to a source file, relative to the kernel source | |
211 | tree. The following directive options are supported: | |
212 | ||
213 | export: *[source-pattern ...]* | |
214 | Include documentation for all functions in *source* that have been exported | |
215 | using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any | |
216 | of the files specified by *source-pattern*. | |
217 | ||
218 | The *source-pattern* is useful when the kernel-doc comments have been placed | |
219 | in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to | |
220 | the function definitions. | |
221 | ||
222 | Examples:: | |
223 | ||
224 | .. kernel-doc:: lib/bitmap.c | |
225 | :export: | |
226 | ||
227 | .. kernel-doc:: include/net/mac80211.h | |
228 | :export: net/mac80211/*.c | |
229 | ||
230 | internal: *[source-pattern ...]* | |
231 | Include documentation for all functions and types in *source* that have | |
232 | **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either | |
233 | in *source* or in any of the files specified by *source-pattern*. | |
234 | ||
235 | Example:: | |
236 | ||
237 | .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c | |
238 | :internal: | |
239 | ||
240 | doc: *title* | |
241 | Include documentation for the ``DOC:`` paragraph identified by *title* in | |
242 | *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* | |
243 | is only used as an identifier for the paragraph, and is not included in the | |
244 | output. Please make sure to have an appropriate heading in the enclosing | |
245 | reStructuredText document. | |
246 | ||
247 | Example:: | |
248 | ||
249 | .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c | |
250 | :doc: High Definition Audio over HDMI and Display Port | |
251 | ||
252 | functions: *function* *[...]* | |
253 | Include documentation for each *function* in *source*. | |
254 | ||
255 | Example:: | |
256 | ||
257 | .. kernel-doc:: lib/bitmap.c | |
258 | :functions: bitmap_parselist bitmap_parselist_user | |
259 | ||
260 | Without options, the kernel-doc directive includes all documentation comments | |
261 | from the source file. | |
262 | ||
263 | The kernel-doc extension is included in the kernel source tree, at | |
264 | ``Documentation/sphinx/kernel-doc.py``. Internally, it uses the | |
265 | ``scripts/kernel-doc`` script to extract the documentation comments from the | |
266 | source. | |
267 | ||
268 | Writing kernel-doc comments | |
269 | =========================== | |
270 | ||
271 | In order to provide embedded, "C" friendly, easy to maintain, but consistent and | |
272 | extractable overview, function and type documentation, the Linux kernel has | |
273 | adopted a consistent style for documentation comments. The format for this | |
274 | documentation is called the kernel-doc format, described below. This style | |
275 | embeds the documentation within the source files, using a few simple conventions | |
276 | for adding documentation paragraphs and documenting functions and their | |
277 | parameters, structures and unions and their members, enumerations, and typedefs. | |
278 | ||
279 | .. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen, | |
280 | yet distinctively different, for historical reasons. The kernel source | |
281 | contains tens of thousands of kernel-doc comments. Please stick to the style | |
282 | described here. | |
283 | ||
284 | The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in | |
285 | the documentation build to extract this embedded documentation into the various | |
286 | HTML, PDF, and other format documents. | |
287 | ||
288 | In order to provide good documentation of kernel functions and data structures, | |
289 | please use the following conventions to format your kernel-doc comments in the | |
290 | Linux kernel source. | |
291 | ||
292 | How to format kernel-doc comments | |
293 | --------------------------------- | |
294 | ||
295 | The opening comment mark ``/**`` is reserved for kernel-doc comments. Only | |
296 | comments so marked will be considered by the ``kernel-doc`` tool. Use it only | |
297 | for comment blocks that contain kernel-doc formatted comments. The usual ``*/`` | |
298 | should be used as the closing comment marker. The lines in between should be | |
299 | prefixed by ``Â *Â `` (space star space). | |
300 | ||
301 | The function and type kernel-doc comments should be placed just before the | |
302 | function or type being described. The overview kernel-doc comments may be freely | |
303 | placed at the top indentation level. | |
304 | ||
305 | Example kernel-doc function comment:: | |
306 | ||
307 | /** | |
308 | * foobar() - Brief description of foobar. | |
309 | * @arg: Description of argument of foobar. | |
310 | * | |
311 | * Longer description of foobar. | |
312 | * | |
313 | * Return: Description of return value of foobar. | |
314 | */ | |
315 | int foobar(int arg) | |
316 | ||
317 | The format is similar for documentation for structures, enums, paragraphs, | |
318 | etc. See the sections below for details. | |
319 | ||
320 | The kernel-doc structure is extracted from the comments, and proper `Sphinx C | |
321 | Domain`_ function and type descriptions with anchors are generated for them. The | |
322 | descriptions are filtered for special kernel-doc highlights and | |
323 | cross-references. See below for details. | |
324 | ||
325 | .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html | |
326 | ||
327 | Highlights and cross-references | |
328 | ------------------------------- | |
329 | ||
330 | The following special patterns are recognized in the kernel-doc comment | |
331 | descriptive text and converted to proper reStructuredText markup and `Sphinx C | |
332 | Domain`_ references. | |
333 | ||
334 | .. attention:: The below are **only** recognized within kernel-doc comments, | |
335 | **not** within normal reStructuredText documents. | |
336 | ||
337 | ``funcname()`` | |
338 | Function reference. | |
339 | ||
340 | ``@parameter`` | |
341 | Name of a function parameter. (No cross-referencing, just formatting.) | |
342 | ||
343 | ``%CONST`` | |
344 | Name of a constant. (No cross-referencing, just formatting.) | |
345 | ||
346 | ``$ENVVAR`` | |
347 | Name of an environment variable. (No cross-referencing, just formatting.) | |
348 | ||
349 | ``&struct name`` | |
350 | Structure reference. | |
351 | ||
352 | ``&enum name`` | |
353 | Enum reference. | |
354 | ||
355 | ``&typedef name`` | |
356 | Typedef reference. | |
357 | ||
358 | ``&struct_name->member`` or ``&struct_name.member`` | |
359 | Structure or union member reference. The cross-reference will be to the struct | |
360 | or union definition, not the member directly. | |
361 | ||
362 | ``&name`` | |
363 | A generic type reference. Prefer using the full reference described above | |
364 | instead. This is mostly for legacy comments. | |
365 | ||
366 | Cross-referencing from reStructuredText | |
367 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
368 | ||
369 | To cross-reference the functions and types defined in the kernel-doc comments | |
370 | from reStructuredText documents, please use the `Sphinx C Domain`_ | |
371 | references. For example:: | |
372 | ||
373 | See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`. | |
374 | ||
375 | While the type reference works with just the type name, without the | |
376 | struct/union/enum/typedef part in front, you may want to use:: | |
377 | ||
378 | See :c:type:`struct foo <foo>`. | |
379 | See :c:type:`union bar <bar>`. | |
380 | See :c:type:`enum baz <baz>`. | |
381 | See :c:type:`typedef meh <meh>`. | |
382 | ||
383 | This will produce prettier links, and is in line with how kernel-doc does the | |
384 | cross-references. | |
385 | ||
386 | For further details, please refer to the `Sphinx C Domain`_ documentation. | |
387 | ||
388 | Function documentation | |
389 | ---------------------- | |
390 | ||
391 | The general format of a function and function-like macro kernel-doc comment is:: | |
392 | ||
393 | /** | |
394 | * function_name() - Brief description of function. | |
395 | * @arg1: Describe the first argument. | |
396 | * @arg2: Describe the second argument. | |
397 | * One can provide multiple line descriptions | |
398 | * for arguments. | |
399 | * | |
400 | * A longer description, with more discussion of the function function_name() | |
401 | * that might be useful to those using or modifying it. Begins with an | |
402 | * empty comment line, and may include additional embedded empty | |
403 | * comment lines. | |
404 | * | |
405 | * The longer description may have multiple paragraphs. | |
406 | * | |
407 | * Return: Describe the return value of foobar. | |
408 | * | |
409 | * The return value description can also have multiple paragraphs, and should | |
410 | * be placed at the end of the comment block. | |
411 | */ | |
412 | ||
413 | The brief description following the function name may span multiple lines, and | |
414 | ends with an ``@argument:`` description, a blank comment line, or the end of the | |
415 | comment block. | |
416 | ||
417 | The kernel-doc function comments describe each parameter to the function, in | |
418 | order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions | |
419 | must begin on the very next line following the opening brief function | |
420 | description line, with no intervening blank comment lines. The ``@argument:`` | |
421 | descriptions may span multiple lines. The continuation lines may contain | |
422 | indentation. If a function parameter is ``...`` (varargs), it should be listed | |
423 | in kernel-doc notation as: ``@...:``. | |
424 | ||
425 | The return value, if any, should be described in a dedicated section at the end | |
426 | of the comment starting with "Return:". | |
427 | ||
428 | Structure, union, and enumeration documentation | |
429 | ----------------------------------------------- | |
430 | ||
431 | The general format of a struct, union, and enum kernel-doc comment is:: | |
432 | ||
433 | /** | |
434 | * struct struct_name - Brief description. | |
435 | * @member_name: Description of member member_name. | |
436 | * | |
437 | * Description of the structure. | |
438 | */ | |
439 | ||
440 | Below, "struct" is used to mean structs, unions and enums, and "member" is used | |
441 | to mean struct and union members as well as enumerations in an enum. | |
442 | ||
443 | The brief description following the structure name may span multiple lines, and | |
444 | ends with a ``@member:`` description, a blank comment line, or the end of the | |
445 | comment block. | |
446 | ||
447 | The kernel-doc data structure comments describe each member of the structure, in | |
448 | order, with the ``@member:`` descriptions. The ``@member:`` descriptions must | |
449 | begin on the very next line following the opening brief function description | |
450 | line, with no intervening blank comment lines. The ``@member:`` descriptions may | |
451 | span multiple lines. The continuation lines may contain indentation. | |
452 | ||
453 | In-line member documentation comments | |
454 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
455 | ||
456 | The structure members may also be documented in-line within the definition:: | |
457 | ||
458 | /** | |
459 | * struct foo - Brief description. | |
460 | * @foo: The Foo member. | |
461 | */ | |
462 | struct foo { | |
463 | int foo; | |
464 | /** | |
465 | * @bar: The Bar member. | |
466 | */ | |
467 | int bar; | |
468 | /** | |
469 | * @baz: The Baz member. | |
470 | * | |
471 | * Here, the member description may contain several paragraphs. | |
472 | */ | |
473 | int baz; | |
474 | } | |
475 | ||
476 | Private members | |
477 | ~~~~~~~~~~~~~~~ | |
478 | ||
479 | Inside a struct description, you can use the "private:" and "public:" comment | |
480 | tags. Structure fields that are inside a "private:" area are not listed in the | |
481 | generated output documentation. The "private:" and "public:" tags must begin | |
482 | immediately following a ``/*`` comment marker. They may optionally include | |
483 | comments between the ``:`` and the ending ``*/`` marker. | |
484 | ||
485 | Example:: | |
486 | ||
487 | /** | |
488 | * struct my_struct - short description | |
489 | * @a: first member | |
490 | * @b: second member | |
491 | * | |
492 | * Longer description | |
493 | */ | |
494 | struct my_struct { | |
495 | int a; | |
496 | int b; | |
497 | /* private: internal use only */ | |
498 | int c; | |
499 | }; | |
500 | ||
501 | ||
502 | Typedef documentation | |
503 | --------------------- | |
504 | ||
505 | The general format of a typedef kernel-doc comment is:: | |
506 | ||
507 | /** | |
508 | * typedef type_name - Brief description. | |
509 | * | |
510 | * Description of the type. | |
511 | */ | |
512 | ||
513 | Overview documentation comments | |
514 | ------------------------------- | |
515 | ||
516 | To facilitate having source code and comments close together, you can include | |
517 | kernel-doc documentation blocks that are free-form comments instead of being | |
518 | kernel-doc for functions, structures, unions, enums, or typedefs. This could be | |
519 | used for something like a theory of operation for a driver or library code, for | |
520 | example. | |
521 | ||
522 | This is done by using a ``DOC:`` section keyword with a section title. | |
523 | ||
524 | The general format of an overview or high-level documentation comment is:: | |
525 | ||
526 | /** | |
527 | * DOC: Theory of Operation | |
528 | * | |
529 | * The whizbang foobar is a dilly of a gizmo. It can do whatever you | |
530 | * want it to do, at any time. It reads your mind. Here's how it works. | |
531 | * | |
532 | * foo bar splat | |
533 | * | |
534 | * The only drawback to this gizmo is that is can sometimes damage | |
535 | * hardware, software, or its subject(s). | |
536 | */ | |
537 | ||
538 | The title following ``DOC:`` acts as a heading within the source file, but also | |
539 | as an identifier for extracting the documentation comment. Thus, the title must | |
540 | be unique within the file. | |
541 | ||
542 | Recommendations | |
543 | --------------- | |
544 | ||
545 | We definitely need kernel-doc formatted documentation for functions that are | |
546 | exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``. | |
547 | ||
548 | We also look to provide kernel-doc formatted documentation for functions | |
549 | externally visible to other kernel files (not marked "static"). | |
550 | ||
551 | We also recommend providing kernel-doc formatted documentation for private (file | |
552 | "static") routines, for consistency of kernel source code layout. But this is | |
553 | lower priority and at the discretion of the MAINTAINER of that kernel source | |
554 | file. | |
555 | ||
556 | Data structures visible in kernel include files should also be documented using | |
557 | kernel-doc formatted comments. | |
558 | ||
559 | DocBook XML [DEPRECATED] | |
560 | ======================== | |
561 | ||
562 | .. attention:: | |
563 | ||
564 | This section describes the deprecated DocBook XML toolchain. Please do not | |
565 | create new DocBook XML template files. Please consider converting existing | |
566 | DocBook XML templates files to Sphinx/reStructuredText. | |
567 | ||
568 | Converting DocBook to Sphinx | |
569 | ---------------------------- | |
570 | ||
571 | Over time, we expect all of the documents under ``Documentation/DocBook`` to be | |
572 | converted to Sphinx and reStructuredText. For most DocBook XML documents, a good | |
573 | enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script, | |
574 | which uses ``pandoc`` under the hood. For example:: | |
575 | ||
576 | $ cd Documentation/sphinx | |
577 | $ ./tmplcvt ../DocBook/in.tmpl ../out.rst | |
578 | ||
579 | Then edit the resulting rst files to fix any remaining issues, and add the | |
580 | document in the ``toctree`` in ``Documentation/index.rst``. | |
581 | ||
582 | Components of the kernel-doc system | |
583 | ----------------------------------- | |
584 | ||
585 | Many places in the source tree have extractable documentation in the form of | |
586 | block comments above functions. The components of this system are: | |
587 | ||
588 | - ``scripts/kernel-doc`` | |
589 | ||
590 | This is a perl script that hunts for the block comments and can mark them up | |
591 | directly into reStructuredText, DocBook, man, text, and HTML. (No, not | |
592 | texinfo.) | |
593 | ||
594 | - ``Documentation/DocBook/*.tmpl`` | |
595 | ||
596 | These are XML template files, which are normal XML files with special | |
597 | place-holders for where the extracted documentation should go. | |
598 | ||
599 | - ``scripts/docproc.c`` | |
600 | ||
601 | This is a program for converting XML template files into XML files. When a | |
602 | file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be | |
603 | able to distinguish between internal and external functions. | |
604 | ||
605 | It invokes kernel-doc, giving it the list of functions that are to be | |
606 | documented. | |
607 | ||
608 | Additionally it is used to scan the XML template files to locate all the files | |
609 | referenced herein. This is used to generate dependency information as used by | |
610 | make. | |
611 | ||
612 | - ``Makefile`` | |
613 | ||
614 | The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build | |
615 | DocBook XML files, PostScript files, PDF files, and html files in | |
616 | Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'. | |
617 | ||
618 | - ``Documentation/DocBook/Makefile`` | |
619 | ||
620 | This is where C files are associated with SGML templates. | |
621 | ||
622 | How to use kernel-doc comments in DocBook XML template files | |
623 | ------------------------------------------------------------ | |
624 | ||
625 | DocBook XML template files (\*.tmpl) are like normal XML files, except that they | |
626 | can contain escape sequences where extracted documentation should be inserted. | |
627 | ||
628 | ``!E<filename>`` is replaced by the documentation, in ``<filename>``, for | |
629 | functions that are exported using ``EXPORT_SYMBOL``: the function list is | |
630 | collected from files listed in ``Documentation/DocBook/Makefile``. | |
631 | ||
632 | ``!I<filename>`` is replaced by the documentation for functions that are **not** | |
633 | exported using ``EXPORT_SYMBOL``. | |
634 | ||
635 | ``!D<filename>`` is used to name additional files to search for functions | |
636 | exported using ``EXPORT_SYMBOL``. | |
637 | ||
638 | ``!F<filename> <function [functions...]>`` is replaced by the documentation, in | |
639 | ``<filename>``, for the functions listed. | |
640 | ||
641 | ``!P<filename> <section title>`` is replaced by the contents of the ``DOC:`` | |
642 | section titled ``<section title>`` from ``<filename>``. Spaces are allowed in | |
643 | ``<section title>``; do not quote the ``<section title>``. | |
644 | ||
645 | ``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC: | |
646 | sections and documented functions, symbols, etc. are used. This makes sense to | |
647 | use when you use ``!F`` or ``!P`` only and want to verify that all documentation | |
648 | is included. |