Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 01f2c180 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 63ac8517

Documentation/doc-guide/kernel-doc.rst

+30 −26
Original line number Diff line number Diff line
@@ -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

---------------------