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

[Lukas Wunner]

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