Messages in this thread | | | Date | Thu, 9 Jul 2015 17:56:32 -0600 | From | Jonathan Corbet <> | Subject | Re: [PATCH v2] scripts/kernel-doc: Adding cross-reference links to html documentation. |
| |
On Fri, 26 Jun 2015 12:08:57 -0300 Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> wrote:
> 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 put a lot more time into this today than I really had available. I think it's cool stuff, and we definitely want it. But can I ask for one more pass? In particular:
- It makes the docs build a lot more noisy, that would be nice to fix.
- A bit more documentation in the script would be nice. It also is happy to run with silly arguments; a detail since nobody will run it directly, but still...
- Most importantly, it breaks "make htmldocs"; in particular, vast amounts of error spew results when it gets around to media_api.html. I spent a while trying to figure out what was going on but didn't come up with anything conclusive; my suspicion is that it has to do with the separate makefile in Documentation/DocBook/media/.
Thanks,
jon
| |