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

[Jonathan Corbet <corbet@lwn.net>]

On Mon,  7 Sep 2015 17:01:59 -0300
Danilo Cesar Lemes de Paula <danilo.cesar@collabora.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