Re: make htmldocs errors

[Randy Dunlap]

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/
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/