"make htmldocs" generated the following errors:
Warning(/sda4/download/linux_linus/linux-2.6//include/asm-x86/unaligned.h):
no structured comments found
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'
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'
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'
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?
Thank you.
--
Regards,
Peter Teoh
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/
Thank you Randy for the explanation.
Just for your interest, other tree like tracing/for-linus at:
git://git.kernel.org/pub/scm/linux/kernel/git/tip/linux-2.6-tip.git
has somewhat similar problem too (but different files altogether)...
/sda3/ftrace/tracing/for-linus>make htmldocs
DOCPROC Documentation/DocBook/debugobjects.xml
HTML Documentation/DocBook/debugobjects.html
DOCPROC Documentation/DocBook/deviceiobook.xml
HTML Documentation/DocBook/deviceiobook.html
DOCPROC Documentation/DocBook/filesystems.xml
HTML Documentation/DocBook/filesystems.html
DOCPROC Documentation/DocBook/gadget.xml
Error(/sda3/ftrace/tracing/for-linus//drivers/usb/gadget/config.c:132):
cannot understand prototype: 'struct usb_descriptor_header **__init
usb_copy_descriptors(struct usb_descriptor_header **src) '
Error(/sda3/ftrace/tracing/for-linus//drivers/usb/gadget/config.c:183):
cannot understand prototype: 'struct usb_endpoint_descriptor *__init
usb_find_endpoint( struct usb_descriptor_header **src, struct
usb_descriptor_header **copy, struct usb_endpoint_descriptor *match
) '
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:129):
No description found for parameter 'list'
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
No description found for parameter 'list'
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
No description found for parameter 'functions'
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
No description found for parameter 'next_interface_id'
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
No description found for parameter 'highspeed'
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
No description found for parameter 'fullspeed'
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
No description found for parameter 'interface[MAX_CONFIG_INTERFACES]'
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:322):
No description found for parameter 'desc'
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:322):
No description found for parameter 'configs'
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:322):
No description found for parameter 'driver'
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:322):
No description found for parameter 'next_string_id'
Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:322):
No description found for parameter 'lock'
make[1]: *** [Documentation/DocBook/gadget.xml] Error 2
make: *** [htmldocs] Error 2
Thank you.
On Wed, 23 Jul 2008 10:48:52 +0800 Peter Teoh wrote:
> Thank you Randy for the explanation.
>
> Just for your interest, other tree like tracing/for-linus at:
>
> git://git.kernel.org/pub/scm/linux/kernel/git/tip/linux-2.6-tip.git
AFAIAC, one person cannot fix _all_ git trees. There are at least
200 kernel git trees at git.kernel.org (probably lots of them are defunct).
It just doesn't scale IMHO, so please send patches after you confirm that
patches are indeed needed.
> has somewhat similar problem too (but different files altogether)...
>
> /sda3/ftrace/tracing/for-linus>make htmldocs
> DOCPROC Documentation/DocBook/debugobjects.xml
> HTML Documentation/DocBook/debugobjects.html
> DOCPROC Documentation/DocBook/deviceiobook.xml
> HTML Documentation/DocBook/deviceiobook.html
> DOCPROC Documentation/DocBook/filesystems.xml
> HTML Documentation/DocBook/filesystems.html
> DOCPROC Documentation/DocBook/gadget.xml
> Error(/sda3/ftrace/tracing/for-linus//drivers/usb/gadget/config.c:132):
> cannot understand prototype: 'struct usb_descriptor_header **__init
> usb_copy_descriptors(struct usb_descriptor_header **src) '
> Error(/sda3/ftrace/tracing/for-linus//drivers/usb/gadget/config.c:183):
> cannot understand prototype: 'struct usb_endpoint_descriptor *__init
> usb_find_endpoint( struct usb_descriptor_header **src, struct
> usb_descriptor_header **copy, struct usb_endpoint_descriptor *match
> ) '
Fix for above is in the kbuild tree and I have ask that it be merged Soon.
Otherwise I'll need to merge it separately.
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:129):
> No description found for parameter 'list'
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
> No description found for parameter 'list'
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
> No description found for parameter 'functions'
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
> No description found for parameter 'next_interface_id'
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
> No description found for parameter 'highspeed'
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
> No description found for parameter 'fullspeed'
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:226):
> No description found for parameter 'interface[MAX_CONFIG_INTERFACES]'
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:322):
> No description found for parameter 'desc'
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:322):
> No description found for parameter 'configs'
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:322):
> No description found for parameter 'driver'
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:322):
> No description found for parameter 'next_string_id'
> Warning(/sda3/ftrace/tracing/for-linus//include/linux/usb/composite.h:322):
> No description found for parameter 'lock'
I've already sent that list to the linux-usb mailing list...
I mainly try to focus on the fatal errors or changes that need to be made
to scripts/kernel-doc.
---
~Randy
Linux Plumbers Conference, 17-19 September 2008, Portland, Oregon USA
http://linuxplumbersconf.org/