You are viewing landley

The Conversation Pit - Just spent several hours on kernel documentation. [entries|archive|friends|userinfo]
Rob Landley

[ website | My Website ]
[ userinfo | livejournal userinfo ]
[ archive | journal archive ]

Just spent several hours on kernel documentation. [Feb. 19th, 2011|10:44 pm]
Previous Entry Add to Memories Share Next Entry
I didn't _mean_ to, but the kernel documentation page is in much better shape than it's been in years. (I fixed the menuconfig parser. I made the htmldocs thing translate more than it has in a while, although there's still some bugs. I fixed the RFC file so that it generates links to kernel source in the format the git repository wants _this_ week. And I fixed the top level index so that the interesting stuff is no longer buried under buckets of todo items.)

Back to NFS...
linkReply

Comments:
[User Picture]From: mad_soft
2011-03-04 12:30 pm (UTC)

(Link)

Hi, Rob. Thanks for your work!

BTW, in RFC section all those one-digit RFCs (rfc1,2,3,6,7,8) seems to be a false positives - you may want to teach your scripts to ignore them.

Also generated htmls for files containing kerneldoc-style comments would be a nice addition to site. You can use something like this to generate them:
mkdir kerneldoc-htmls ; find . -type f -name '*.[hc]' | while read file ; do if grep -q '/\*\*[[:space:]]*$' $file ; then echo $file ; scripts/kernel-doc -html $file > kerneldoc-htmls/`echo $file | sed -e 's:^\./::g' -e 's:/:-:g'`.html ; fi ; done 2>&1 | tee kerneldoc.log ; find kerneldoc-htmls/ -size 0 | xargs rm
[User Picture]From: landley
2011-03-05 01:24 am (UTC)

(Link)

I thought the make htmldocs step got some of those?

Possibly the kernel's make htmldocs needs to be updated to produce misc output somehow...?
[User Picture]From: mad_soft
2011-03-05 02:00 pm (UTC)

(Link)

> I thought the make htmldocs step got some of those?

Looks like make htmldocs just compiles Documentation/DocBook/*.xml and nothing more. It seems that currently the only way to get html/pdf/anything generated from embedded kerneldoc comments is to run scripts/kernel-doc manually with needed file. That probably explains why these comments is not in a perfect shape - on 2.6.38-rc7 with script above I get:
> grep Warning kerneldoc.log | wc -l
14512
> grep Error kerneldoc.log | wc -l
1338


Yep, I agree that it would be nice to have a generic way to generate all those kerneldocs htmls via kbuild/make - either extend make htmldocs, or create another make target perhaps ('make kerneldoc' or something).