Docbook update
Subsystems (2)
bugzilla.kernel.org has long complained about make *docs (See entry 228). This updates docbook and some sourcefile to make it compile with success. When building sgmldocs a lot of warnings are now issued about parameters with no description. A good sign that comments needs an update.
There is no functional changes in sis900.c and kmod.c - only docbook related changes.
Sam
Patches will follow as follow-up mails.
Linus please do a
bk pull http://linux-sam.bkbits.net/docbook
This will update the following files:
Documentation/DocBook/Makefile | 48 ++++++++++++++-------- Documentation/DocBook/kernel-api.tmpl | 3 - drivers/net/sis900.c | 72 +++++++++++++++++----------------- kernel/kmod.c | 2 scripts/docproc.c | 2 scripts/kernel-doc | 15 +++++-- 6 files changed, 83 insertions(+), 59 deletions(-)
through these ChangeSets:
<[email protected]> (03/06/07 1.1316.1.4)
docbook: Move definition of MODULENAME_SIZE
The location between the comment and the prototype confused kernel-doc. Kernel-doc requires the prototype to follow after the comment section.
<[email protected]> (03/06/07 1.1316.1.3)
docbook: Warn about missing parameter definitions
Previously kernel-doc silently ignored missing parameter descriptions but sometimes 'make sgmldocs' failed with exit code > 0. When kernel-doc encounter parameters where the description is missing it now prints a warning.
docproc corrected so previously exit code are recorded. docbook makefile cleaned up a bit
<[email protected]> (03/06/07 1.1316.1.2)
docbook: Recognize sis900 functions
Adapted comments to follow what kernel-doc (docbook) understands
<[email protected]> (03/06/07 1.1316.1.1)
docbook/kernel-api: include files updated
Path to pci_hotplug_core corrected.
Added !Eli/string.h to document strlcpy and friends
# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher. # This patch includes the following deltas:
# ChangeSet 1.1316 -> 1.1316.1.1
# Documentation/DocBook/kernel-api.tmpl 1.25 -> 1.26
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 03/06/07 [email protected] 1.1316.1.1
# docbook/kernel-api: include files updated
#
# Path to pci_hotplug_core corrected.
# Added !Eli/string.h to document strlcpy and friends
# --------------------------------------------
#
Documentation/DocBook/kernel-api.tmpl +2 -1
@@ -79,6 +79,7 @@ </sect1> <sect1><title>String Manipulation</title> !Ilib/string.c +!Elib/string.c </sect1> <sect1><title>Bit Operations</title> !Iinclude/asm-i386/bitops.h
@@ -176,7 +177,7 @@ !Edrivers/pci/pci.c </sect1> <sect1><title>PCI Hotplug Support Library</title> -!Edrivers/hotplug/pci_hotplug_core.c +!Edrivers/pci/hotplug/pci_hotplug_core.c </sect1> <sect1><title>MCA Architecture</title> <sect2><title>MCA Device Functions</title>
# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher. # This patch includes the following deltas:
# ChangeSet 1.1316.1.1 -> 1.1316.1.2
# drivers/net/sis900.c 1.36 -> 1.37
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 03/06/07 [email protected] 1.1316.1.2
# docbook: Recognize sis900 functions
#
# Adapted comments to follow what kernel-doc (docbook) understands # --------------------------------------------
#
drivers/net/sis900.c +36 -36
@@ -211,7 +211,7 @@static void sis900_set_mode (long ioaddr,int speed,int duplex);/** -* sis900_get_mac_addr: - Get MAC address for stand alone SiS900 model +* sis900_get_mac_addr - Get MAC address for stand alone SiS900 model * @pci_dev: the sis900 pci device * @net_dev: the net device to get address for *
@@ -241,7 +241,7 @@ }/** -* sis630e_get_mac_addr: - Get MAC address for SiS630E model +* sis630e_get_mac_addr - Get MAC address for SiS630E model * @pci_dev: the sis900 pci device * @net_dev: the net device to get address for *
@@ -274,7 +274,7 @@/** -* sis635_get_mac_addr: - Get MAC address for SIS635 model +* sis635_get_mac_addr - Get MAC address for SIS635 model * @pci_dev: the sis900 pci device * @net_dev: the net device to get address for *
@@ -310,7 +310,7 @@ }/** -* sis96x_get_mac_addr: - Get MAC address for SiS962 or SiS963 model +* sis96x_get_mac_addr - Get MAC address for SiS962 or SiS963 model * @pci_dev: the sis900 pci device * @net_dev: the net device to get address for *
@@ -352,7 +352,7 @@ }/** -* sis900_probe: - Probe for sis900 device +* sis900_probe - Probe for sis900 device * @pci_dev: the sis900 pci device * @pci_id: the pci device ID *
@@ -498,7 +498,7 @@ }/** -* sis900_mii_probe: - Probe MII PHY for sis900 +* sis900_mii_probe - Probe MII PHY for sis900 * @net_dev: the net device to probe for * * Search for total of 32 possible mii phy addresses.
@@ -618,7 +618,7 @@ }/** -* sis900_default_phy: - Select default PHY for sis900 mac. +* sis900_default_phy - Select default PHY for sis900 mac. * @net_dev: the net device to probe for * * Select first detected PHY with link as default.
@@ -671,7 +671,7 @@/** -* sis900_set_capability: - set the media capability of network adapter. +* sis900_set_capability - set the media capability of network adapter. * @net_dev : the net device to probe for * @phy : default PHY *
@@ -701,7 +701,7 @@#define eeprom_delay () inl(ee_addr)/** -* read_eeprom: - Read Serial EEPROM +* read_eeprom - Read Serial EEPROM * @ioaddr: base i/o address * @location: the EEPROM location to read *
@@ -776,7 +776,7 @@ }/** -* mdio_read: - read MII PHY register +* mdio_read - read MII PHY register * @net_dev: the net device to read * @phy_id: the phy address to read * @location: the phy regiester id to read
@@ -818,7 +818,7 @@ }/** -* mdio_write: - write MII PHY register +* mdio_write - write MII PHY register * @net_dev: the net device to write * @phy_id: the phy address to write * @location: the phy regiester id to write
@@ -872,7 +872,7 @@/** -* sis900_reset_phy: - reset sis900 mii phy. +* sis900_reset_phy - reset sis900 mii phy. * @net_dev: the net device to write * @phy_addr: default phy address *
@@ -895,7 +895,7 @@ }/** -* sis900_open: - open sis900 device +* sis900_open - open sis900 device * @net_dev: the net device to open * * Do some initialization and start net interface.
@@ -952,7 +952,7 @@ }/** -* sis900_init_rxfilter: - Initialize the Rx filter +* sis900_init_rxfilter - Initialize the Rx filter * @net_dev: the net device to initialize for * * Set receive filter address to our MAC address
@@ -990,7 +990,7 @@ }/** -* sis900_init_tx_ring: - Initialize the Tx descriptor ring +* sis900_init_tx_ring - Initialize the Tx descriptor ring * @net_dev: the net device to initialize for * * Initialize the Tx descriptor ring,
@@ -1023,7 +1023,7 @@ }/** -* sis900_init_rx_ring: - Initialize the Rx descriptor ring +* sis900_init_rx_ring - Initialize the Rx descriptor ring * @net_dev: the net device to initialize for * * Initialize the Rx descriptor ring,
@@ -1077,7 +1077,7 @@ }/** -* sis630_set_eq: - set phy equalizer value for 630 LAN +* sis630_set_eq - set phy equalizer value for 630 LAN * @net_dev: the net device to set equalizer value * @revision: 630 LAN revision number *
@@ -1165,7 +1165,7 @@ }/** -* sis900_timer: - sis900 timer routine +* sis900_timer - sis900 timer routine * @data: pointer to sis900 net device * * On each timer ticks we check two things,
@@ -1235,7 +1235,7 @@ }/** -* sis900_check_mode: - check the media mode for sis900 +* sis900_check_mode - check the media mode for sis900 * @net_dev: the net device to be checked * @mii_phy: the mii phy *
@@ -1266,7 +1266,7 @@ }/** -* sis900_set_mode: - Set the media mode of mac register. +* sis900_set_mode - Set the media mode of mac register. * @ioaddr: the address of the device * @speed : the transmit speed to be determined * @duplex: the duplex mode to be determined
@@ -1310,7 +1310,7 @@ }/** -* sis900_auto_negotiate: Set the Auto-Negotiation Enable/Reset bit. +* sis900_auto_negotiate - Set the Auto-Negotiation Enable/Reset bit. * @net_dev: the net device to read mode for * @phy_addr: mii phy address *
@@ -1344,7 +1344,7 @@/** -* sis900_read_mode: - read media mode for sis900 internal phy +* sis900_read_mode - read media mode for sis900 internal phy * @net_dev: the net device to read mode for * @speed : the transmit speed to be determined * @duplex : the duplex mode to be determined
@@ -1401,7 +1401,7 @@ }/** -* sis900_tx_timeout: - sis900 transmit timeout routine +* sis900_tx_timeout - sis900 transmit timeout routine * @net_dev: the net device to transmit * * print transmit timeout status
@@ -1456,7 +1456,7 @@ }/** -* sis900_start_xmit: - sis900 start transmit routine +* sis900_start_xmit - sis900 start transmit routine * @skb: socket buffer pointer to put the data being transmitted * @net_dev: the net device to transmit with *
@@ -1526,7 +1526,7 @@ }/** -* sis900_interrupt: - sis900 interrupt handler +* sis900_interrupt - sis900 interrupt handler * @irq: the irq number * @dev_instance: the client data object * @regs: snapshot of processor context
@@ -1587,7 +1587,7 @@ }/** -* sis900_rx: - sis900 receive routine +* sis900_rx - sis900 receive routine * @net_dev: the net device which receives data * * Process receive interrupt events,
@@ -1726,7 +1726,7 @@ }/** -* sis900_finish_xmit: - finish up transmission of packets +* sis900_finish_xmit - finish up transmission of packets * @net_dev: the net device to be transmitted on * * Check for error condition and free socket buffer etc
@@ -1796,7 +1796,7 @@ }/** -* sis900_close: - close sis900 device +* sis900_close - close sis900 device * @net_dev: the net device to be closed * * Disable interrupts, stop the Tx and Rx Status Machine
@@ -1852,7 +1852,7 @@ }/** -* netdev_ethtool_ioctl: - For the basic support of ethtool +* netdev_ethtool_ioctl - For the basic support of ethtool * @net_dev: the net device to command for * @useraddr: start address of interface request *
@@ -1886,7 +1886,7 @@ }/** -* mii_ioctl: - process MII i/o control command +* mii_ioctl - process MII i/o control command * @net_dev: the net device to command for * @rq: parameter for command * @cmd: the i/o command
@@ -1922,7 +1922,7 @@ }/** -* sis900_get_stats: - Get sis900 read/write statistics +* sis900_get_stats - Get sis900 read/write statistics * @net_dev: the net device to get statistics for * * get tx/rx statistics for sis900
@@ -1937,7 +1937,7 @@ }/** -* sis900_set_config: - Set media type by net_device.set_config +* sis900_set_config - Set media type by net_device.set_config * @dev: the net device for media type change * @map: ifmap passed by ifconfig *
@@ -2034,7 +2034,7 @@ }/** -* sis900_mcast_bitnr: - compute hashtable index +* sis900_mcast_bitnr - compute hashtable index * @addr: multicast address * @revision: revision id of chip *
@@ -2057,7 +2057,7 @@ }/** -* set_rx_mode: - Set SiS900 receive mode +* set_rx_mode - Set SiS900 receive mode * @net_dev: the net device to be set * * Set SiS900 receive mode for promiscuous, multicast, or broadcast mode.
@@ -2131,7 +2131,7 @@ }/** -* sis900_reset: - Reset sis900 MAC +* sis900_reset - Reset sis900 MAC * @net_dev: the net device to reset * * reset sis900 MAC and wait until finished
@@ -2166,7 +2166,7 @@ }/** -* sis900_remove: - Remove sis900 device +* sis900_remove - Remove sis900 device * @pci_dev: the pci device to be removed * * remove and release SiS900 net device
# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher. # This patch includes the following deltas:
# ChangeSet 1.1316.1.2 -> 1.1316.1.3
# scripts/docproc.c 1.3 -> 1.4
# scripts/kernel-doc 1.11 -> 1.12
# Documentation/DocBook/Makefile 1.40 -> 1.41
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 03/06/07 [email protected] 1.1316.1.3
# docbook: Warn about missing parameter definitions
#
# Previously kernel-doc silently ignored missing parameter descriptions
# but sometimes 'make sgmldocs' failed with exit code > 0. # When kernel-doc encounter parameters where the description is missing # it now prints a warning. # docproc corrected so previously exit code are recorded. # docbook makefile cleaned up a bit # -------------------------------------------- # diff -Nru a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile --- a/Documentation/DocBook/Makefile Sat Jun 7 09:53:42 2003 +++ b/Documentation/DocBook/Makefile Sat Jun 7 09:53:42 2003 @@ -39,8 +39,8 @@
###
#External programs used
-KERNELDOC=$(objtree)/scripts/kernel-doc
-DOCPROC=$(objtree)/scripts/docproc
+KERNELDOC = scripts/kernel-doc
+DOCPROC = scripts/docproc
###
# DOCPROC is used for two purposes:
@@ -50,14 +50,14 @@
# The following rules are used to generate the .sgml documentation
# required to generate the final targets. (ps, pdf, html).
quiet_cmd_docproc = DOCPROC $@
-cmd_docproc = $(DOCPROC) doc $< >$@
+ cmd_docproc = $(DOCPROC) doc $< >$@
define rule_docproc
- set -e
- $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';)
- $(cmd_$(1)); \
- ( \
- echo 'cmd_$@ := $(cmd_$(1))'; \
- echo $@: `$(DOCPROC) depend $<`; \
+ set -e; \
+ $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \
+ $(cmd_$(1)); \
+ ( \
+ echo 'cmd_$@ := $(cmd_$(1))'; \
+ echo $@: `$(DOCPROC) depend $<`; \
) > $(dir $@).$(notdir $@).cmd
endef@@ -96,41 +96,55 @@
###
# Rules to generate postscript, PDF and HTML
# db2html creates a directory. Generate a html file used for timestamp + +quiet_cmd_db2ps = DB2PS $@ + cmd_db2ps = db2ps -o $(dir $@) $< %.ps : %.sgml @(which db2ps > /dev/null 2>&1) || \ (echo "*** You need to install DocBook stylesheets ***"; \ exit 1) - $(call do_cmd,DB2PS $@,db2ps -o $(dir $@) $<) + $(call cmd,db2ps)
+quiet_cmd_db2pdf = DB2PDF $@
+ cmd_db2pdf = db2pdf -o $(dir $@) $<
%.pdf : %.sgml
@(which db2pdf > /dev/null 2>&1) || \
(echo "*** You need to install DocBook stylesheets ***"; \
exit 1)
- $(call do_cmd,DB2PDF $@,db2pdf -o $(dir $@) $<)
+ $(call cmd,db2pdf)
+
+quiet_cmd_db2html = DB2HTML $@
+ cmd_db2html = db2html -o $(patsubst %.html,%,$@) $< && \
+ echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html"> \
+ Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
%.html: %.sgml
@(which db2html > /dev/null 2>&1) || \
(echo "*** You need to install DocBook stylesheets ***"; \
exit 1)
@rm -rf $@ $(patsubst %.html,%,$@)
- $(call do_cmd,DB2HTML $@,db2html -o $(patsubst %.html,%,$@) $< && \
- echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html">\
- Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@)
+ $(call cmd,db2html)
@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi ###
# Rules to generate postscripts and PNG imgages from .fig format files
+quiet_cmd_fig2eps = FIG2EPS $@
+ cmd_fig2eps = fig2dev -Leps $< $@
+
%.eps: %.fig
- $(call do_cmd,FIG2DEV -Leps $@,fig2dev -Leps $< $@)
+ $(call cmd,fig2eps)
+
+quiet_cmd_fig2png = FIG2PNG $@
+ cmd_fig2png = fig2dev -Lpng $< $@
%.png: %.fig
- $(call do_cmd,FIG2DEV -Lpng $@,fig2dev -Lpng $< $@)
+ $(call cmd,fig2png)
###
# Rule to convert a .c file to inline SGML documentation %.sgml: %.c
- @echo ' Generating $@'
+ @echo ' GEN $@'
@( \ echo "<programlisting>"; \ expand --tabs=8 < $< | \
scripts/docproc.c +1 -1
@@ -93,7 +93,7 @@waitpid (pid, &ret ,0 ); }if (WIFEXITED (ret)) - exitstatus =WEXITSTATUS (ret); + exitstatus |=WEXITSTATUS (ret);else exitstatus =0xff ; }
scripts/kernel-doc +12 -3
@@ -154,6 +154,7 @@ # '%CONST' - name of a constant. my $errors = 0; +my $warnings = 0; # match expressions used to find embedded type information my $type_constant = '\%([-_\w]+)';
@@ -1352,7 +1353,9 @@ "or member '$param' not " . "described in '$declaration_name'\n"; } - ++$errors; + print STDERR "Warning(${file}:$.):". + " No description found for parameter '$param'\n"; + ++$warnings; } push @parameterlist, $param;
@@ -1456,6 +1459,12 @@ chomp; process_file($_); } +if ($verbose && $errors) { + print STDERR "$errors errors\n"; +} +if ($verbose && $warnings) { + print STDERR "$warnings warnings\n"; +} exit($errors);
@@ -1580,7 +1589,7 @@ } else { print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.", " - I thought it was a doc line\n"; - ++$errors; + ++$warnings; $state = 0; } } elsif ($state == 2) { # look for head: lines, and include content
@@ -1633,7 +1642,7 @@ } else { # i dont know - bad line? ignore. print STDERR "Warning(${file}:$.): bad line: $_"; - ++$errors; + ++$warnings; } } elsif ($state == 3) { # scanning for function { (end of prototype) if ($decl_type eq 'function') {
# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher. # This patch includes the following deltas:
# ChangeSet 1.1316.1.3 -> 1.1316.1.4
# kernel/kmod.c 1.27 -> 1.28
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 03/06/07 [email protected] 1.1316.1.4
# docbook: Move definition of MODULENAME_SIZE
#
# The location between the comment and the prototype confused kernel-doc. # Kernel-doc requires the prototype to follow after the comment section. # --------------------------------------------
#
kernel/kmod.c +1 -1
@@ -58,9 +58,9 @@* If module auto-loading support is disabled then this function * becomes a no-operation. */ -#define MODULENAME_SIZE 32int request_module (const char *fmt, ...) { +#define MODULENAME_SIZE 32va_list args;char module_name[MODULENAME_SIZE ];unsigned int max_modprobes;