Re: [pci:pci/docs 2/12] htmldocs: include/linux/pci.h:831: warning: Function parameter or member 'node' not described in 'pci_driver'

[Bjorn Helgaas <helgaas@kernel.org>]

On Fri, May 31, 2019 at 12:17:54AM +0800, kbuild test robot wrote:
> tree:   https://git.kernel.org/pub/scm/linux/kernel/git/helgaas/pci.git pci/docs
> head:   5b76337ac1d54eb1c82414f17e29883290ce87de
> commit: fe6cdee86aeb83ee6ed2dc98928fb9fefc138612 [2/12] Documentation: PCI: convert pci.txt to reST
> reproduce: make htmldocs
> 
> If you fix the issue, kindly add following tag
> Reported-by: kbuild test robot <lkp@intel.com>
> 
> All warnings (new ones prefixed by >>):
> 
>    WARNING: convert(1) not found, for SVG to PDF conversion install ImageMagick (https://www.imagemagick.org)
>    include/linux/pci.h:158: warning: cannot understand function prototype: 'typedef unsigned int __bitwise pci_channel_state_t; '
> >> include/linux/pci.h:831: warning: Function parameter or member 'node' not described in 'pci_driver'
> >> include/linux/pci.h:831: warning: Function parameter or member 'name' not described in 'pci_driver'
> >> include/linux/pci.h:831: warning: Function parameter or member 'sriov_configure' not described in 'pci_driver'
> >> include/linux/pci.h:831: warning: Function parameter or member 'groups' not described in 'pci_driver'
> >> include/linux/pci.h:831: warning: Function parameter or member 'driver' not described in 'pci_driver'
> >> include/linux/pci.h:831: warning: Function parameter or member 'dynids' not described in 'pci_driver'
>    include/linux/pci.h:2251: warning: Excess function parameter 'lrdt' description in 'pci_vpd_info_field_size'

I fixed these by folding the patch below into fe6cdee86aeb
("Documentation: PCI: convert pci.txt to reST").  A couple of these
fixes are for pre-existing warnings unrelated to fe6cdee86aeb.

diff --git a/include/linux/pci.h b/include/linux/pci.h
index df22373c9164..b74b2a4e6df2 100644
--- a/include/linux/pci.h
+++ b/include/linux/pci.h
@@ -151,6 +151,8 @@ static inline const char *pci_power_name(pci_power_t state)
 #define PCI_PM_BUS_WAIT		50
 
 /**
+ * typedef pci_channel_state_t
+ *
  * The pci_channel state describes connectivity between the CPU and
  * the PCI device.  If some PCI bus between here and the PCI device
  * has crashed or locked up, this info is reflected here.
@@ -778,6 +780,8 @@ struct module;
 
 /**
  * struct pci_driver - PCI driver structure
+ * @node:	List of driver structures.
+ * @name:	Driver name.
  * @id_table:	Pointer to table of device IDs the driver is
  *		interested in.  Most drivers should export this
  *		table using MODULE_DEVICE_TABLE(pci,...).
@@ -786,7 +790,7 @@ struct module;
  *		devices or later if a new device gets inserted) for
  *		all PCI devices which match the ID table and are not
  *		"owned" by the other drivers yet. This function gets
- *		passed a "struct pci_dev *" for each device whose
+ *		passed a "struct pci_dev \*" for each device whose
  *		entry in the ID table matches the device. The probe
  *		function returns zero when the driver chooses to
  *		take "ownership" of the device or an error code
@@ -810,7 +814,12 @@ struct module;
  *		Useful for enabling wake-on-lan (NIC) or changing
  *		the power state of a device before reboot.
  *		e.g. drivers/net/e100.c.
+ * @sriov_configure: Optional driver callback to allow configuration of
+ *		number of VFs to enable via sysfs "sriov_numvfs" file.
  * @err_handler: See Documentation/PCI/pci-error-recovery.rst
+ * @groups:	Sysfs attribute groups.
+ * @driver:	Driver model structure.
+ * @dynids:	List of dynamically added device IDs.
  */
 struct pci_driver {
 	struct list_head	node;
@@ -2243,7 +2252,7 @@ static inline u8 pci_vpd_srdt_tag(const u8 *srdt)
 
 /**
  * pci_vpd_info_field_size - Extracts the information field length
- * @lrdt: Pointer to the beginning of an information field header
+ * @info_field: Pointer to the beginning of an information field header
  *
  * Returns the extracted information field length.
  */