summaryrefslogtreecommitdiffstats
path: root/Documentation/doc-guide
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2017-12-18 10:30:03 -0200
committerJonathan Corbet <corbet@lwn.net>2017-12-21 13:41:45 -0700
commit01f2c18073e284397f45c94b26e65fd1b66776e4 (patch)
tree831c17c9f9c5d6f7d9f734d1781e16cceeb9a623 /Documentation/doc-guide
parent63ac85174a5455bf0ed14fa37515015de33d0fe9 (diff)
downloadlinux-01f2c18073e284397f45c94b26e65fd1b66776e4.tar.bz2
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>
Diffstat (limited to 'Documentation/doc-guide')
-rw-r--r--Documentation/doc-guide/kernel-doc.rst56
1 files changed, 30 insertions, 26 deletions
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index f1c03c16f03b..7cf58c3489de 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -167,6 +167,36 @@ notation as::
* @...: description
+Private members
+~~~~~~~~~~~~~~~
+
+Inside a struct or union description, you can use the ``private:`` and
+``public:`` comment tags. Structure fields that are inside a ``private:``
+area are not listed in the generated output documentation.
+
+The ``private:`` and ``public:`` tags must begin immediately following a
+``/*`` comment marker. They may optionally include comments between the
+``:`` and the ending ``*/`` marker.
+
+Example::
+
+ /**
+ * struct my_struct - short description
+ * @a: first member
+ * @b: second member
+ * @d: fourth member
+ *
+ * Longer description
+ */
+ struct my_struct {
+ int a;
+ int b;
+ /* private: internal use only */
+ int c;
+ /* public: the next one is public */
+ int d;
+ };
+
Highlights and cross-references
-------------------------------
@@ -332,32 +362,6 @@ on a line of their own, like all other kernel-doc comments::
int foobar;
}
-Private members
-~~~~~~~~~~~~~~~
-
-Inside a struct description, you can use the "private:" and "public:" comment
-tags. Structure fields that are inside a "private:" area are not listed in the
-generated output documentation. The "private:" and "public:" tags must begin
-immediately following a ``/*`` comment marker. They may optionally include
-comments between the ``:`` and the ending ``*/`` marker.
-
-Example::
-
- /**
- * struct my_struct - short description
- * @a: first member
- * @b: second member
- *
- * Longer description
- */
- struct my_struct {
- int a;
- int b;
- /* private: internal use only */
- int c;
- };
-
-
Typedef documentation
---------------------