Messages in this thread | | | Date | Tue, 22 Jul 2008 08:42:11 -0700 | From | Randy Dunlap <> | Subject | Re: make htmldocs errors |
| |
On Tue, 22 Jul 2008 19:07:59 +0800 Peter Teoh wrote:
> "make htmldocs" generated the following errors: > > Warning(/sda4/download/linux_linus/linux-2.6//include/asm-x86/unaligned.h): > no structured comments found
kernel-api.tmpl "includes" asm-x86/unaligned.h, but the latter contains no kernel-doc comments. This is due to some unaligned macro/inline function "fixes" (movement/restructuring). This head file used to contain kernel-doc comments for unaligned functions, but it no longer does. I'm not sure if any header file does now. If one does, it needs to be used here instead of this header file.
> Warning(/sda4/download/linux_linus/linux-2.6//kernel/rcupdate.c:81): > No description found for parameter 'synchronize_rcu' > Warning(/sda4/download/linux_linus/linux-2.6//kernel/rcupdate.c:81): > No description found for parameter 'call_rcu'
Confusing syntax for a simplistic perl parser. I'll have to take a look at that.
> Error(/sda4/download/linux_linus/linux-2.6//drivers/pci/pci.c:1133): > duplicate section name 'Description' > Error(/sda4/download/linux_linus/linux-2.6//drivers/pci/pci.c:1189): > duplicate section name 'Description'
I have already posted a patch for these. The function short description must be on one line. Having it on multiple lines confused scripts/kernel-doc.
> Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'id' > Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'attach_adapter' > Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'detach_adapter' > Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'detach_client' > Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'probe' > Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'remove' > Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'shutdown' > Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'suspend' > Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'resume' > Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'command' > Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'driver' > Warning(/sda4/download/linux_linus/linux-2.6//include/linux/i2c.h:169): > No description found for parameter 'id_table'
These aren't a mystery at all: include/linux/i2c.h is missing lots of struct i2c_driver field/member descriptions.
> make[1]: *** [Documentation/DocBook/kernel-api.xml] Error 2 > make: *** [htmldocs] Error 2 > > Can someone explain what is the cause of the error? Is it because > "make htmldocs" attempt to detect for description marked as "/* */" > beside the field name?
No. drivers/pci/pci.c had invalid kernel-doc comments in it (function short description on multiple lines).
--- ~Randy Linux Plumbers Conference, 17-19 September 2008, Portland, Oregon USA http://linuxplumbersconf.org/
| |