Messages in this thread Patch in this message | | | Date | Mon, 26 Oct 2020 10:16:20 +0100 | From | Mauro Carvalho Chehab <> | Subject | Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup |
| |
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
| |