Messages in this thread | | | From | Peter Lister <> | Subject | Re: [PATCH v2 33/33] lib: bitmap.c: get rid of some doc warnings | Date | Fri, 24 Apr 2020 18:30:31 +0100 |
| |
On 14/04/2020 17:48, Mauro Carvalho Chehab wrote: > There are two ascii art drawings there. Use a block markup tag there > in order to get rid of those warnings: > > ./lib/bitmap.c:189: WARNING: Unexpected indentation. > ./lib/bitmap.c:190: WARNING: Block quote ends without a blank line; unexpected unindent. > ./lib/bitmap.c:190: WARNING: Unexpected indentation. > ./lib/bitmap.c:191: WARNING: Line block ends without a blank line.
A few weeks ago, I asked if anyone had a better suggestion about how to cope with this comment for bitmap_cut(). As far as I can see, this is the first response.
> It should be noticed that there's actually a syntax violation > right now, as something like: > > /** > ... > @src:
I don't see this as a syntax violation. I see it as the failure of kernel-doc to cope with a perfectly reasonable construction. I suggest that kernel-doc should recognise that the first use of @src: is as a param definition, and that the second use isn't.
Actually the *main* bug here is that the second use messes up the sphinx link/search info for this function by overwriting the correct first use.
> will be handled as a definition for @src parameter, and not as > part of a diagram. So, we need to add something before it, in > order for this to be processed the way it should. . > + * The @src bitmap is::
Making editorial changes to the text seems to me a bad way to get rid of warnings. If we are saying that the original developer "got it wrong" then we need to say how. I assert that this idiom is not wrong, and we should not need to add even minor verbosity to the wording.
Developers like compact idioms: someone will use this again before long. Are you going to keep telling developers that they are wrong? This is not a good way to encourage developers to compose annotation.
It's a similar problem to REST's love of multiple line breaks. Maybe one or two are not a big problem, but many little infelicities added together make the C comments less useful as annotation for developers.
| |