linux-kernel - Re: [PATCH v2 33/33] lib: bitmap.c: get rid of some doc warnings

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <634b1157-a78a-806f-2872-0a9a8efa3730@bikeshed.quignogs.org.uk>
Date:   Fri, 24 Apr 2020 18:30:31 +0100
From:   Peter Lister <peter@...eshed.quignogs.org.uk>
To:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc:     linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>
Subject: Re: [PATCH v2 33/33] lib: bitmap.c: get rid of some doc warnings

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.