Em Mon, 26 Oct 2020 09:10:59 +0100
Peter Zijlstra <peterz@xxxxxxxxxxxxx> 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@xxxxxxxxxx>
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
