Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kernel-doc.rst: improve private members description
The private members section can now be moved to be together
with the arguments section. Move it there and add an example
about the usage of public:
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
01f2c180
63ac8517
+30
-26
+30
-26
Documentation/doc-guide/kernel-doc.rst
+30
-26
Documentation/doc-guide/kernel-doc.rst
···
167
167
168
168
* @...: description
169
169
170
+
Private members
171
+
~~~~~~~~~~~~~~~
172
+
173
+
Inside a struct or union description, you can use the ``private:`` and
174
+
``public:`` comment tags. Structure fields that are inside a ``private:``
175
+
area are not listed in the generated output documentation.
176
+
177
+
The ``private:`` and ``public:`` tags must begin immediately following a
178
+
``/*`` comment marker. They may optionally include comments between the
179
+
``:`` and the ending ``*/`` marker.
180
+
181
+
Example::
182
+
183
+
/**
184
+
* struct my_struct - short description
185
+
* @a: first member
186
+
* @b: second member
187
+
* @d: fourth member
188
+
*
189
+
* Longer description
190
+
*/
191
+
struct my_struct {
192
+
int a;
193
+
int b;
194
+
/* private: internal use only */
195
+
int c;
196
+
/* public: the next one is public */
197
+
int d;
198
+
};
199
+
170
200
171
201
Highlights and cross-references
172
202
-------------------------------
···
361
331
/** @foobar: Single line description. */
362
332
int foobar;
363
333
}
364
-
365
-
Private members
366
-
~~~~~~~~~~~~~~~
367
-
368
-
Inside a struct description, you can use the "private:" and "public:" comment
369
-
tags. Structure fields that are inside a "private:" area are not listed in the
370
-
generated output documentation. The "private:" and "public:" tags must begin
371
-
immediately following a ``/*`` comment marker. They may optionally include
372
-
comments between the ``:`` and the ending ``*/`` marker.
373
-
374
-
Example::
375
-
376
-
/**
377
-
* struct my_struct - short description
378
-
* @a: first member
379
-
* @b: second member
380
-
*
381
-
* Longer description
382
-
*/
383
-
struct my_struct {
384
-
int a;
385
-
int b;
386
-
/* private: internal use only */
387
-
int c;
388
-
};
389
-
390
334
391
335
Typedef documentation
392
336
---------------------