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