lkml.org 
[lkml]   [2008]   [Jul]   [22]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: 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/


\
 
 \ /
  Last update: 2008-07-22 17:45    [W:0.239 / U:0.332 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site