linux-kernel - Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <20150913143647.1c7a9b05@lwn.net>
Date:	Sun, 13 Sep 2015 14:36:47 -0600
From:	Jonathan Corbet <corbet@....net>
To:	Danilo Cesar Lemes de Paula <danilo.cesar@...labora.co.uk>
Cc:	Randy Dunlap <rdunlap@...radead.org>,
	Daniel Vetter <daniel.vetter@...ll.ch>,
	Laurent Pinchart <laurent.pinchart@...asonboard.com>,
	Herbert Xu <herbert@...dor.apana.org.au>,
	Stephan Mueller <smueller@...onox.de>,
	Michal Marek <mmarek@...e.cz>, linux-kernel@...r.kernel.org,
	linux-doc@...r.kernel.org,
	intel-gfx <intel-gfx@...ts.freedesktop.org>,
	dri-devel <dri-devel@...ts.freedesktop.org>
Subject: Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an
 array

On Mon,  7 Sep 2015 17:01:59 -0300
Danilo Cesar Lemes de Paula <danilo.cesar@...labora.co.uk> wrote:

> The "highlight" code is very sensible to the order of the hash keys,
> but the order of the keys cannot be predicted. It generates
> faulty DocBook entries like:
> 	- @<function>device_for_each_child</function>
> 
> Sorting the result is not enough some times (as it's deterministic but
> we can't control it).
> We should use an array for that job, so we can guarantee that the order
> of the regex execution on dohighlight is correct.

OK, I've spent a bunch of time with this, comparing the results before
and after.  The output you mention is clearly wrong, but there might be
room to differ over what the root cause is.

That output is caused by @device_for_each_child() in the comments.  This
happens for a few other functions as well, and I think it's wrong.  @ is
used to indicate parameters (or structure fields); I'm not sure why
people are using it for functions that are *not* one of the above.
Formatting the function names as a parameter doesn't seem right either.

There is the occasional case where the parameter *is* a function and the
text uses the () notation (threadfn(), for example).  Having the
"parameter" style win out over the "function" style in such cases is OK,
I guess, but it would be good to format the parentheses along with the
name.  The function patterns there now drop the parentheses entirely,
which seems a bit strange to me.

I guess I'll apply the patch; determinism is good, and it doesn't make
anything screwy that wasn't already that way.  But I think we should fix
the misapplied @s and sort out function formatting in general.  One of
these days...

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/