Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Peter Zijlstra <peterz@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>,
	Kees Cook <keescook@chromium.org>,
	Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Ard Biesheuvel <ardb@kernel.org>, Ingo Molnar <mingo@kernel.org>,
	Jann Horn <jannh@google.com>, Will Deacon <will@kernel.org>,
	linux-kernel@vger.kernel.org
Subject: Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup
Date: Mon, 26 Oct 2020 10:16:20 +0100	[thread overview]
Message-ID: <20201026101620.1a11ef3e@coco.lan> (raw)
In-Reply-To: <20201026081059.GB2628@hirez.programming.kicks-ass.net>

Em Mon, 26 Oct 2020 09:10:59 +0100
Peter Zijlstra <peterz@infradead.org> escreveu:

> On Sat, Oct 24, 2020 at 08:28:27AM +0200, Mauro Carvalho Chehab wrote:
> > If the intent is to document the struct and its internal fields,
> > this kernel-doc should work:
> > 
> > 	/**
> > 	 * struct refcount_struct - variant of atomic_t specialized for reference counts
> > 	 * @refs: atomic_t counter field
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 */
> > 
> > Which produces this result:  
> 
> Who cares... :-(

Anyone that would need to use refcount_t, instead of atomic_t.

> 
> > If you want both, then you would either split struct and typedef, e. g.
> > with something like:
> > 
> > 	/**
> > 	 * struct refcount_struct - variant of atomic_t specialized for reference counts
> > 	 * @refs: atomic_t counter field
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 */
> > 	struct refcount_struct {
> > 	        atomic_t refs;
> > 	};
> > 
> > 	/**
> > 	 * typedef refcount_t - variant of atomic_t specialized for reference counts
> > 	 * @refs: atomic_t counter field
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 */
> > 	typedef struct refcount_struct refcount_t;
> > 
> > Or, you could add the member at the description field. E. g. something
> > like this:
> > 
> > 	/**
> > 	 * typedef refcount_t - variant of atomic_t specialized for reference counts
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 *
> > 	 * Members:
> > 	 *   ``refs``
> > 	 *        atomic_t counter field
> > 	 */
> > 	typedef struct refcount_struct {
> > 	        atomic_t refs;
> > 	} refcount_t;
> > 
> > If you want to test it, you can run kernel-doc directly, to see how
> > it will parse it. For ReST output, that's the syntax:
> > 
> > 	./scripts/kernel-doc --sphinx-version 3 include/linux/refcount.h  
> 
> I'll just go ahead and remove the superfluous * from the comment... It's
> trivially clear what is meant. If the stupid tool can't deal with that,
> I don't care.

The tool is not that stupid. What's wrong here is that the markup is
asking kernel-doc to document the struct, instead documenting the typedef:

 	/**
 	 * struct refcount_t - variant of atomic_t specialized for reference counts
...

There is no such struct!

Just doing:

	s/struct/typedef/

will do what you intend to document.

Thanks,
Mauro

[PATCH] refcount.h: fix a kernel-doc markup

The kernel-doc markup is wrong: it is asking the tool to document
struct refcount_struct, instead of documenting typedef refcount_t.

Fix it.
    
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/include/linux/refcount.h b/include/linux/refcount.h
index 0e3ee25eb156..f572c62261a8 100644
--- a/include/linux/refcount.h
+++ b/include/linux/refcount.h
@@ -101,7 +101,7 @@
 struct mutex;
 
 /**
- * struct refcount_t - variant of atomic_t specialized for reference counts
+ * typedef refcount_t - variant of atomic_t specialized for reference counts
  * @refs: atomic_t counter field
  *
  * The counter saturates at REFCOUNT_SATURATED and will not move once


