diff options
author | Ingo Molnar <mingo@elte.hu> | 2008-06-16 05:24:43 -0400 |
---|---|---|
committer | Ingo Molnar <mingo@elte.hu> | 2008-06-16 05:24:43 -0400 |
commit | 8bbd54d69e9c66adbf544e21d8dcfb15fb9198f7 (patch) | |
tree | 95f30814fc759c2cb523dbea95bc531c7f8f3231 /Documentation/kernel-doc-nano-HOWTO.txt | |
parent | 8c2238eaaf0f774ca0f8d9daad7a616429bbb7f1 (diff) | |
parent | 066519068ad2fbe98c7f45552b1f592903a9c8c8 (diff) |
Merge branch 'linus' into core/softlockup
Diffstat (limited to 'Documentation/kernel-doc-nano-HOWTO.txt')
-rw-r--r-- | Documentation/kernel-doc-nano-HOWTO.txt | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 2075c0658bf5..0bd32748a467 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt | |||
@@ -1,6 +1,105 @@ | |||
1 | kernel-doc nano-HOWTO | 1 | kernel-doc nano-HOWTO |
2 | ===================== | 2 | ===================== |
3 | 3 | ||
4 | How to format kernel-doc comments | ||
5 | --------------------------------- | ||
6 | |||
7 | In order to provide embedded, 'C' friendly, easy to maintain, | ||
8 | but consistent and extractable documentation of the functions and | ||
9 | data structures in the Linux kernel, the Linux kernel has adopted | ||
10 | a consistent style for documenting functions and their parameters, | ||
11 | and structures and their members. | ||
12 | |||
13 | The format for this documentation is called the kernel-doc format. | ||
14 | It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file. | ||
15 | |||
16 | This style embeds the documentation within the source files, using | ||
17 | a few simple conventions. The scripts/kernel-doc perl script, some | ||
18 | SGML templates in Documentation/DocBook, and other tools understand | ||
19 | these conventions, and are used to extract this embedded documentation | ||
20 | into various documents. | ||
21 | |||
22 | In order to provide good documentation of kernel functions and data | ||
23 | structures, please use the following conventions to format your | ||
24 | kernel-doc comments in Linux kernel source. | ||
25 | |||
26 | We definitely need kernel-doc formatted documentation for functions | ||
27 | that are exported to loadable modules using EXPORT_SYMBOL. | ||
28 | |||
29 | We also look to provide kernel-doc formatted documentation for | ||
30 | functions externally visible to other kernel files (not marked | ||
31 | "static"). | ||
32 | |||
33 | We also recommend providing kernel-doc formatted documentation | ||
34 | for private (file "static") routines, for consistency of kernel | ||
35 | source code layout. But this is lower priority and at the | ||
36 | discretion of the MAINTAINER of that kernel source file. | ||
37 | |||
38 | Data structures visible in kernel include files should also be | ||
39 | documented using kernel-doc formatted comments. | ||
40 | |||
41 | The opening comment mark "/**" is reserved for kernel-doc comments. | ||
42 | Only comments so marked will be considered by the kernel-doc scripts, | ||
43 | and any comment so marked must be in kernel-doc format. Do not use | ||
44 | "/**" to be begin a comment block unless the comment block contains | ||
45 | kernel-doc formatted comments. The closing comment marker for | ||
46 | kernel-doc comments can be either "*/" or "**/". | ||
47 | |||
48 | Kernel-doc comments should be placed just before the function | ||
49 | or data structure being described. | ||
50 | |||
51 | Example kernel-doc function comment: | ||
52 | |||
53 | /** | ||
54 | * foobar() - short function description of foobar | ||
55 | * @arg1: Describe the first argument to foobar. | ||
56 | * @arg2: Describe the second argument to foobar. | ||
57 | * One can provide multiple line descriptions | ||
58 | * for arguments. | ||
59 | * | ||
60 | * A longer description, with more discussion of the function foobar() | ||
61 | * that might be useful to those using or modifying it. Begins with | ||
62 | * empty comment line, and may include additional embedded empty | ||
63 | * comment lines. | ||
64 | * | ||
65 | * The longer description can have multiple paragraphs. | ||
66 | **/ | ||
67 | |||
68 | The first line, with the short description, must be on a single line. | ||
69 | |||
70 | The @argument descriptions must begin on the very next line following | ||
71 | this opening short function description line, with no intervening | ||
72 | empty comment lines. | ||
73 | |||
74 | Example kernel-doc data structure comment. | ||
75 | |||
76 | /** | ||
77 | * struct blah - the basic blah structure | ||
78 | * @mem1: describe the first member of struct blah | ||
79 | * @mem2: describe the second member of struct blah, | ||
80 | * perhaps with more lines and words. | ||
81 | * | ||
82 | * Longer description of this structure. | ||
83 | **/ | ||
84 | |||
85 | The kernel-doc function comments describe each parameter to the | ||
86 | function, in order, with the @name lines. | ||
87 | |||
88 | The kernel-doc data structure comments describe each structure member | ||
89 | in the data structure, with the @name lines. | ||
90 | |||
91 | The longer description formatting is "reflowed", losing your line | ||
92 | breaks. So presenting carefully formatted lists within these | ||
93 | descriptions won't work so well; derived documentation will lose | ||
94 | the formatting. | ||
95 | |||
96 | See the section below "How to add extractable documentation to your | ||
97 | source files" for more details and notes on how to format kernel-doc | ||
98 | comments. | ||
99 | |||
100 | Components of the kernel-doc system | ||
101 | ----------------------------------- | ||
102 | |||
4 | Many places in the source tree have extractable documentation in the | 103 | Many places in the source tree have extractable documentation in the |
5 | form of block comments above functions. The components of this system | 104 | form of block comments above functions. The components of this system |
6 | are: | 105 | are: |