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