make htmldocs errors - Kernel

This is a discussion on make htmldocs errors - Kernel ; "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 ...

+ Reply to Thread
Results 1 to 4 of 4

Thread: make htmldocs errors

  1. make htmldocs errors

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

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

  3. Re: make htmldocs errors

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

  4. Re: make htmldocs errors

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

+ Reply to Thread