linux-kernel - Re: make htmldocs errors

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:	Tue, 22 Jul 2008 08:42:11 -0700
From:	Randy Dunlap <rdunlap@...otime.net>
To:	"Peter Teoh" <htmldeveloper@...il.com>
Cc:	LKML <linux-kernel@...r.kernel.org>,
	"linuxkernelnewbies@...glegroups.com" 
	<linuxkernelnewbies@...glegroups.com>
Subject: 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@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/