linux-kernel - [PATCH 2/3] doc: debugobjects: actually pull in the kerneldoc comments

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <1479515655-20556-3-git-send-email-corbet@lwn.net>
Date:   Fri, 18 Nov 2016 17:34:14 -0700
From:   Jonathan Corbet <corbet@....net>
To:     linux-doc@...r.kernel.org
Cc:     linux-kernel@...r.kernel.org, Thomas Gleixner <tglx@...utronix.de>,
        Jason Baron <jbaron@...hat.com>,
        William Cohen <wcohen@...hat.com>,
        Jonathan Corbet <corbet@....net>
Subject: [PATCH 2/3] doc: debugobjects: actually pull in the kerneldoc comments

Add the appropriate markup to get the kerneldoc comments out of
lib/debugobjects.c that have never seen the light of day until now.

A logical next step, left for the reader at the moment, is to move the
function descriptions *out* of debug-objects.rst and into the kerneldoc
comments themselves.

Signed-off-by: Jonathan Corbet <corbet@....net>
---
 Documentation/core-api/debug-objects.rst | 34 ++++++++++++++------------------
 1 file changed, 15 insertions(+), 19 deletions(-)

diff --git a/Documentation/core-api/debug-objects.rst b/Documentation/core-api/debug-objects.rst
index 50a9707addfe..ac926fd55a64 100644
--- a/Documentation/core-api/debug-objects.rst
+++ b/Documentation/core-api/debug-objects.rst
@@ -64,14 +64,8 @@ tracking objects and the state of the internal tracking objects pool.
 Debug functions
 ===============
 
-Debug object function reference
--------------------------------
-
 .. kernel-doc:: lib/debugobjects.c
-   :export:
-
-debug_object_init
--------------------
+   :functions: debug_object_init
 
 This function is called whenever the initialization function of a real
 object is called.
@@ -93,8 +87,8 @@ number of warnings including a full stack trace is printk'ed. The
 calling code must use debug_object_init_on_stack() and remove the
 object before leaving the function which allocated it. See next section.
 
-debug_object_init_on_stack
-------------------------------
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_init_on_stack
 
 This function is called whenever the initialization function of a real
 object which resides on the stack is called.
@@ -117,8 +111,8 @@ An object which is on the stack must be removed from the tracker by
 calling debug_object_free() before the function which allocates the
 object returns. Otherwise we keep track of stale objects.
 
-debug_object_activate
------------------------
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_activate
 
 This function is called whenever the activation function of a real
 object is called.
@@ -141,8 +135,9 @@ object.
 When the activation is legitimate, then the state of the associated
 tracker object is set to ODEBUG_STATE_ACTIVE.
 
-debug_object_deactivate
--------------------------
+
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_deactivate
 
 This function is called whenever the deactivation function of a real
 object is called.
@@ -154,8 +149,8 @@ or destroyed objects.
 When the deactivation is legitimate, then the state of the associated
 tracker object is set to ODEBUG_STATE_INACTIVE.
 
-debug_object_destroy
-----------------------
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_destroy
 
 This function is called to mark an object destroyed. This is useful to
 prevent the usage of invalid objects, which are still available in
@@ -173,8 +168,8 @@ deactivate an active object in order to prevent damage to the subsystem.
 When the destruction is legitimate, then the state of the associated
 tracker object is set to ODEBUG_STATE_DESTROYED.
 
-debug_object_free
--------------------
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_free
 
 This function is called before an object is freed.
 
@@ -189,8 +184,9 @@ prevent damage to the subsystem.
 Note that debug_object_free removes the object from the tracker. Later
 usage of the object is detected by the other debug checks.
 
-debug_object_assert_init
----------------------------
+
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_assert_init
 
 This function is called to assert that an object has been initialized.
 
-- 
2.7.4