Describe the "type" struct member using '@type' 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@infradead.org>
---
Cc: Luis Chamberlain <mcgrof@kernel.org>
Cc: Kees Cook <kees@kernel.org>
Cc: Joel Granados <joel.granados@kernel.org>
Cc: linux-fsdevel@vger.kernel.org
---
 include/linux/sysctl.h |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

--- linux-next-20251016.orig/include/linux/sysctl.h
+++ linux-next-20251016/include/linux/sysctl.h
@@ -176,7 +176,7 @@ struct ctl_table_header {
 	struct ctl_node *node;
 	struct hlist_head inodes; /* head for proc_inode->sysctl_inodes */
 	/**
-	 * 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

On Fri, Oct 17, 2025 at 12:08:02AM -0700, Randy Dunlap wrote:
> Describe the "type" struct member using '@type' 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@infradead.org>
> ---
> Cc: Luis Chamberlain <mcgrof@kernel.org>
> Cc: Kees Cook <kees@kernel.org>
> Cc: Joel Granados <joel.granados@kernel.org>
> Cc: linux-fsdevel@vger.kernel.org
> ---
>  include/linux/sysctl.h |    2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> --- linux-next-20251016.orig/include/linux/sysctl.h
> +++ linux-next-20251016/include/linux/sysctl.h
> @@ -176,7 +176,7 @@ struct ctl_table_header {
>  	struct ctl_node *node;
>  	struct hlist_head inodes; /* head for proc_inode->sysctl_inodes */
>  	/**
> -	 * 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

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 '@type' 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 '@type' 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@infradead.org>
Signed-off-by: Joel Granados <joel.granados@kernel.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