lkml.org 
[lkml]   [2015]   [Sep]   [13]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH 1/6] scripts/kernel-doc: Replacing highlights hash by an array
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


\
 
 \ /
  Last update: 2015-09-13 23:41    [W:0.057 / U:0.472 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site