lkml.org 
[lkml]   [2015]   [Aug]   [17]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH v2 1/4] scripts/kernel-doc: Adding cross-reference links to html documentation.
From
Date
On 08/17/2015 01:10 AM, Jonathan Corbet wrote:
> On Tue, 28 Jul 2015 16:45:15 -0300
> Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> wrote:
>
>> Functions, Structs and Parameters definitions on kernel documentation
>> are pure cosmetic, it only highlights the element.
>>
>> To ease the navigation in the documentation we should use <links> inside
>> those tags so readers can easily jump between methods directly.
>>
>> This was discussed in 2014[1] and is implemented by getting a list
>> of <refentries> from the DocBook XML to generate a database. Then it looks
>> for <function>,<structnames> and <paramdef> tags that matches the ones in
>> the database. As it only links existent references, no broken links are
>> added.
>
> So I had some airplane time today and was able to mess with this some. I
> can't make it break anymore, and it clearly improves the resulting
> documentation, so I've applied it to the docs tree for 4.3.
>
> I want to look at the rest of the stuff a bit more and play with it, but
> it's hard to imagine why we wouldn't want that as well. I'm a bit more
> leery just because it adds another dependency to the build, even if it's
> an optional dependency. My thinking at the moment is to apply it shortly

I totally agree about the dependency stuff. I even discussed it with
Daniel Vetter a bit. I started by writing my-very-own-markup-parser to
put alongside kernel-doc to avoid external dependencies, but it gets too
complex too quickly (specially when dealing with tables and multi-line
stuff). It would be a pain to maintain a something like that, and the
world probably doesn't need yet-another-markup-parser, so I decided to
use another tool.

> after the merge window so it can have a long soak in linux-next before a
> 4.4 merge; hope that sounds good.

It does sound good. Thanks!

>
> Thanks for doing this work,

Glad I could help.


Danilo


\
 
 \ /
  Last update: 2015-08-17 15:41    [W:0.059 / U:1.664 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site