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

Groups > linux.kernel > #1223752

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

Show all headers | View raw

Hi,

On Sun, Sep 13, 2015 at 02:36:47PM -0600, Jonathan Corbet wrote:
> 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.

Shouldn't kernel-doc print a warning for syntactic mistakes like this
rather than silently accomodating to it in whatever way?

As to the usage of markdown in general, there's documentation coming up
for vga_switcheroo which makes use of that so I'd love to see it merged:
https://github.com/l1k/linux/commit/d1476d748b5f1adf5bffe8e0a8bafad1e879d22f
https://github.com/l1k/linux/commit/11c55ae65788162970d8fa23cd1fd2518af55d34

The large set of dependencies pulled in on Fedora is likely to be blamed
on the RedHat packaging being notoriously coarse-grained. By comparison,
Debian is extremely fine-grained, kind of the opposite extreme, and
therefore has comparatively few prerequisites:
https://packages.debian.org/jessie/pandoc

I do agree however that alternative tools with fewer dependencies should
be supported and it would be great if the markdown patches were amended
to that end.

Best regards,

Lukas
--
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