Added some function preamble comments.

diff --git a/src/common_bridge.c b/src/common_bridge.c
index 305228a..68a535e 100644 (file)
--- a/src/common_bridge.c
+++ b/src/common_bridge.c
@@ -188,6 +188,13 @@ read_bridge_info( struct pci_device_private * priv )
 }
 
 
+/**
+ * Get the PCI bridge information for a device
+ *
+ * \returns
+ * If \c dev is a PCI-to-PCI bridge, a pointer to a \c pci_bridge_info
+ * structure.  Otherwise, \c NULL is returned.
+ */
 const struct pci_bridge_info *
 pci_device_get_bridge_info( struct pci_device * dev )
 {
@@ -201,6 +208,13 @@ pci_device_get_bridge_info( struct pci_device * dev )
 }
 
 
+/**
+ * Get the PCMCIA bridge information for a device
+ *
+ * \returns
+ * If \c dev is a PCI-to-PCMCIA bridge, a pointer to a
+ * \c pci_pcmcia_bridge_info structure.  Otherwise, \c NULL is returned.
+ */
 const struct pci_pcmcia_bridge_info *
 pci_device_get_pcmcia_bridge_info( struct pci_device * dev )
 {
@@ -214,6 +228,26 @@ pci_device_get_pcmcia_bridge_info( struct pci_device * dev )
 }
 
 
+/**
+ * Determine the primary, secondary, and subordinate buses for a bridge
+ * 
+ * Determines the IDs of the primary, secondary, and subordinate buses for
+ * a specified bridge.  Not all bridges directly store this information
+ * (e.g., PCI-to-ISA bridges).  For those bridges, no error is returned, but
+ * -1 is stored in the bus IDs that don't make sense.
+ *
+ * For example, for a PCI-to-ISA bridge, \c primary_bus will be set to the ID
+ * of the bus containing the device and both \c secondary_bus and
+ * \c subordinate_bus will be set to -1.
+ *
+ * \return
+ * On success, zero is returned.  If \c dev is not a bridge, \c ENODEV is
+ * returned.
+ * 
+ * \bug
+ * Host bridges are handled the same way as PCI-to-ISA bridges.  This is
+ * almost certainly not correct.
+ */
 int
 pci_device_get_bridge_buses(struct pci_device * dev, int *primary_bus,
                            int *secondary_bus, int *subordinate_bus)

diff --git a/src/common_device_name.c b/src/common_device_name.c
index df2212e..96ee0ee 100644 (file)
--- a/src/common_device_name.c
+++ b/src/common_device_name.c
@@ -270,6 +270,13 @@ populate_vendor( struct pci_id_leaf * vend, int fill_device_data )
 }
 
 
+/**
+ * Find the name of the specified device.
+ *
+ * Finds the actual product name of the specified device.  If a subvendor ID
+ * and subdevice ID are specified in \c m, the returned name will be the name
+ * of the subdevice.
+ */
 static const char *
 find_device_name( const struct pci_id_match * m )
 {
@@ -307,6 +314,13 @@ find_device_name( const struct pci_id_match * m )
 }
 
 
+/**
+ * Find the vendor name of the specified device.
+ *
+ * Finds the actual vendor name of the specified device.  If a subvendor ID
+ * and subdevice ID are specified in \c m, the returned name will be the name
+ * associated with the subvendor.
+ */
 static const char *
 find_vendor_name( const struct pci_id_match * m )
 {
@@ -343,8 +357,8 @@ pci_get_strings( const struct pci_id_match * m,
                 const char ** subvendor_name )
 {
     struct pci_id_match  temp;
-    
-    
+
+
     temp = *m;
     temp.subvendor_id = PCI_MATCH_ANY;
     temp.subdevice_id = PCI_MATCH_ANY;