linux-kernel - Re: [PATCH] sysctl: fix kernel-doc format warning

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 for Android: free password hash cracker in your pocket

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

Message-ID: <v7wxokakvlnewgifh3xp672surr4hncsapyfc3tj7mwod6sev6@ixqd7qjsrusk>
Date: Fri, 24 Oct 2025 15:18:37 +0200
From: Joel Granados <joel.granados@...nel.org>
To: Randy Dunlap <rdunlap@...radead.org>
Cc: linux-kernel@...r.kernel.org, Luis Chamberlain <mcgrof@...nel.org>, 
	Kees Cook <kees@...nel.org>, linux-fsdevel@...r.kernel.org
Subject: Re: [PATCH] sysctl: fix kernel-doc format warning

On Fri, Oct 24, 2025 at 03:03:17PM +0200, Joel Granados wrote:
> On Fri, Oct 17, 2025 at 12:08:02AM -0700, Randy Dunlap wrote:
> > Describe the "type" struct member using '@...e' to avoid a kernel-doc
> > warning:
...
> >  	/**
> > -	 * enum type - Enumeration to differentiate between ctl target types
> > +	 * @type: Enumeration to differentiate between ctl target types
> >  	 * @SYSCTL_TABLE_TYPE_DEFAULT: ctl target with no special considerations
> >  	 * @SYSCTL_TABLE_TYPE_PERMANENTLY_EMPTY: Used to identify a permanently
> >  	 *                                       empty directory target to serve
> 
> Yes! I'll push it through with a little tweek by putting it together
> with the general documentation for the ctl_table_header. That is the way
> it is supposed to be (according to Documentation/doc-guide/kernel-doc.rst)
> 
> Best
> -- 
> 
> Joel Granados

Going to look something like this

sysctl: fix kernel-doc format warning

Describe the "type" struct member using '@...e' and move it together
with the rest of the doc for ctl_table_header to avoid a kernel-doc
warning:

Warning: include/linux/sysctl.h:178 Incorrect use of kernel-doc format:
 * enum type - Enumeration to differentiate between ctl target types

Fixes: 2f2665c13af4 ("sysctl: replace child with an enumeration")
Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
Signed-off-by: Joel Granados <joel.granados@...nel.org>

diff --git a/include/linux/sysctl.h b/include/linux/sysctl.h
index 92e9146b1104..f59d5677ee09 100644
--- a/include/linux/sysctl.h
+++ b/include/linux/sysctl.h
@@ -156,7 +156,12 @@ struct ctl_node {
  * @nreg: When nreg drops to 0 the ctl_table_header will be unregistered.
  * @rcu: Delays the freeing of the inode. Introduced with "unfuck proc_sysctl ->d_compare()"
  *
+ * @type: Enumeration to differentiate between ctl target types
+ * @type.SYSCTL_TABLE_TYPE_DEFAULT: ctl target with no special considerations
+ * @type.SYSCTL_TABLE_TYPE_PERMANENTLY_EMPTY: Identifies a permanently empty dir
+ *                                            target to serve as a mount point
  */
+
 struct ctl_table_header {
        union {
                struct {
@@ -175,13 +180,6 @@ struct ctl_table_header {
        struct ctl_dir *parent;
        struct ctl_node *node;
        struct hlist_head inodes; /* head for proc_inode->sysctl_inodes */
-       /**
-        * enum type - Enumeration to differentiate between ctl target types
-        * @SYSCTL_TABLE_TYPE_DEFAULT: ctl target with no special considerations
-        * @SYSCTL_TABLE_TYPE_PERMANENTLY_EMPTY: Used to identify a permanently
-        *                                       empty directory target to serve
-        *                                       as mount point.
-        */
        enum {
                SYSCTL_TABLE_TYPE_DEFAULT,
                SYSCTL_TABLE_TYPE_PERMANENTLY_EMPTY,
~



Best
-- 

Joel Granados

Download attachment "signature.asc" of type "application/pgp-signature" (660 bytes)