Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1223747

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

Show all headers | View raw

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

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> - 2015-09-07 22:10 +0200
  [PATCH 2/6] scripts/kernel-doc: Adding infrastructure for markdown support Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> - 2015-09-07 22:10 +0200
  [PATCH 5/6] scripts/kernel-doc: Improve Markdown results Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> - 2015-09-07 22:10 +0200
  [PATCH 3/6] drm/doc: Convert to markdown Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> - 2015-09-07 22:10 +0200
  [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> - 2015-09-07 22:10 +0200
    Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an  array Jonathan Corbet <corbet@lwn.net> - 2015-09-13 22:40 +0200
      Re: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an  array Lukas Wunner <lukas@wunner.de> - 2015-09-13 23:30 +0200
  [PATCH 6/6] scripts/kernel-doc: Processing -nofunc for functions only Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> - 2015-09-07 22:10 +0200
  [PATCH 4/6] drm/doc: Fixing xml documentation warning Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> - 2015-09-07 22:10 +0200
  Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements Jonathan Corbet <corbet@lwn.net> - 2015-09-12 23:30 +0200
    Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements Daniel Vetter <daniel@ffwll.ch> - 2015-09-13 12:40 +0200
      Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements Jonathan Corbet <corbet@lwn.net> - 2015-09-13 21:20 +0200
        Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements Daniel Vetter <daniel@ffwll.ch> - 2015-09-13 23:00 +0200
          Re: [PATCH 0/6] scripts/kernel-doc: Kernel-doc improvements Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> - 2015-09-14 14:20 +0200

csiph-web