* make htmldocs errors
@ 2008-07-22 11:07 Peter Teoh
2008-07-22 15:42 ` Randy Dunlap
0 siblings, 1 reply; 7+ messages in thread
From: Peter Teoh @ 2008-07-22 11:07 UTC (permalink / raw
To: LKML, linuxkernelnewbies@googlegroups.com
"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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: make htmldocs errors
2008-07-22 11:07 Peter Teoh
@ 2008-07-22 15:42 ` Randy Dunlap
2008-07-23 2:48 ` Peter Teoh
0 siblings, 1 reply; 7+ messages in thread
From: Randy Dunlap @ 2008-07-22 15:42 UTC (permalink / raw
To: Peter Teoh; +Cc: LKML, linuxkernelnewbies@googlegroups.com
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/
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: make htmldocs errors
2008-07-22 15:42 ` Randy Dunlap
@ 2008-07-23 2:48 ` Peter Teoh
2008-07-23 3:23 ` Randy Dunlap
0 siblings, 1 reply; 7+ messages in thread
From: Peter Teoh @ 2008-07-23 2:48 UTC (permalink / raw
To: Randy Dunlap; +Cc: KML
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: make htmldocs errors
2008-07-23 2:48 ` Peter Teoh
@ 2008-07-23 3:23 ` Randy Dunlap
0 siblings, 0 replies; 7+ messages in thread
From: Randy Dunlap @ 2008-07-23 3:23 UTC (permalink / raw
To: Peter Teoh; +Cc: KML
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/
^ permalink raw reply [flat|nested] 7+ messages in thread
* make htmldocs errors
@ 2008-11-05 16:25 Peter Teoh
2008-11-05 16:35 ` Randy Dunlap
0 siblings, 1 reply; 7+ messages in thread
From: Peter Teoh @ 2008-11-05 16:25 UTC (permalink / raw
To: LKML; +Cc: Randy Dunlap
This is on the latest linus tree (75fa67706cce5272bcfc51ed646f2da21f3bdb6e):
/mnt/hd0/download/linux-2.6-latest>make htmldocs
make[1]: *** No rule to make target `include/asm-x86/io_32.h', needed
by `Documentation/DocBook/deviceiobook.xml'. Stop.
make: *** [htmldocs] Error 2
--
Regards,
Peter Teoh
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: make htmldocs errors
2008-11-05 16:25 make htmldocs errors Peter Teoh
@ 2008-11-05 16:35 ` Randy Dunlap
2008-11-05 17:04 ` Randy Dunlap
0 siblings, 1 reply; 7+ messages in thread
From: Randy Dunlap @ 2008-11-05 16:35 UTC (permalink / raw
To: Peter Teoh; +Cc: LKML
Peter Teoh wrote:
> This is on the latest linus tree (75fa67706cce5272bcfc51ed646f2da21f3bdb6e):
>
> /mnt/hd0/download/linux-2.6-latest>make htmldocs
> make[1]: *** No rule to make target `include/asm-x86/io_32.h', needed
> by `Documentation/DocBook/deviceiobook.xml'. Stop.
> make: *** [htmldocs] Error 2
Hi,
I thought that I had already fixed that, but I'll take another look
at it.
Thanks,
--
~Randy
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: make htmldocs errors
2008-11-05 16:35 ` Randy Dunlap
@ 2008-11-05 17:04 ` Randy Dunlap
0 siblings, 0 replies; 7+ messages in thread
From: Randy Dunlap @ 2008-11-05 17:04 UTC (permalink / raw
To: lkml; +Cc: Peter Teoh
On Wed, 05 Nov 2008 08:35:19 -0800 Randy Dunlap wrote:
> Peter Teoh wrote:
> > This is on the latest linus tree (75fa67706cce5272bcfc51ed646f2da21f3bdb6e):
> >
> > /mnt/hd0/download/linux-2.6-latest>make htmldocs
> > make[1]: *** No rule to make target `include/asm-x86/io_32.h', needed
> > by `Documentation/DocBook/deviceiobook.xml'. Stop.
> > make: *** [htmldocs] Error 2
>
> Hi,
> I thought that I had already fixed that, but I'll take another look
> at it.
Peter,
Please check again. I suspect some files or the git tree is not current.
> git describe
v2.6.28-rc3-54-g75fa677
> grep asm-x86 Documentation/DocBook/deviceiobook.tmpl
# finds nothing
and I fixed this error here (in Linus's git tree):
commit a1a739c56ad031b8bf8b3804f568ac88899f8dd7
Author: Randy Dunlap <randy.dunlap@oracle.com>
Date: Sat Oct 25 17:24:36 2008 -0700
docbooks: fix fatal filename errors
---
~Randy
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2008-11-05 17:05 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2008-11-05 16:25 make htmldocs errors Peter Teoh
2008-11-05 16:35 ` Randy Dunlap
2008-11-05 17:04 ` Randy Dunlap
-- strict thread matches above, loose matches on Subject: below --
2008-07-22 11:07 Peter Teoh
2008-07-22 15:42 ` Randy Dunlap
2008-07-23 2:48 ` Peter Teoh
2008-07-23 3:23 ` Randy Dunlap
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.