pci hotplug: kernel-doc fixes

acpiphp.h: not using kernel-doc, so change /** to /*
acpiphp_core.c: lots of kernel-doc cleanups
acpiphp_glue.c: lots of kernel-doc cleanups
acpiphp_ibm.c: lots of kernel-doc cleanups
cpqphp_core.c: lots of kernel-doc cleanups
cpqphp_ctrl.c: lots of kernel-doc cleanups
fakephp.c:  correct kernel-doc notation
pciehp_ctrl.c: correct kernel-doc notation
rpadlpar_core.c: correct function names & kernel-doc notation
rpaphp_core.c: correct kernel-doc notation
shpchp_ctrl.c: correct kernel-doc notation
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: Kristen Accardi <kristen.c.accardi@intel.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

drivers/pci/hotplug/acpiphp.h

@@ -66,7 +66,7 @@ struct slot {
 	char name[SLOT_NAME_SIZE];
 };
 
-/**
+/*
  * struct acpiphp_bridge - PCI bridge information
  *
  * for each bridge device in ACPI namespace
@@ -97,7 +97,7 @@ struct acpiphp_bridge {
 };
 
 
-/**
+/*
  * struct acpiphp_slot - PCI slot information
  *
  * PCI slot information for each *physical* PCI slot
@@ -118,7 +118,7 @@ struct acpiphp_slot {
 };
 
 
-/**
+/*
  * struct acpiphp_func - PCI function information
  *
  * PCI function information for each object in ACPI namespace
@@ -137,7 +137,7 @@ struct acpiphp_func {
 	u32		flags;		/* see below */
 };
 
-/**
+/*
  * struct acpiphp_attention_info - device specific attention registration
  *
  * ACPI has no generic method of setting/getting attention status

drivers/pci/hotplug/acpiphp_core.c

@@ -91,10 +91,10 @@ static struct hotplug_slot_ops acpi_hotplug_slot_ops = {
  * acpiphp_register_attention - set attention LED callback
  * @info: must be completely filled with LED callbacks
  *
- * Description: this is used to register a hardware specific ACPI
+ * Description: This is used to register a hardware specific ACPI
  * driver that manipulates the attention LED.  All the fields in
  * info must be set.
- **/
+ */
 int acpiphp_register_attention(struct acpiphp_attention_info *info)
 {
 	int retval = -EINVAL;
@@ -112,10 +112,10 @@ int acpiphp_register_attention(struct acpiphp_attention_info *info)
  * acpiphp_unregister_attention - unset attention LED callback
  * @info: must match the pointer used to register
  *
- * Description: this is used to un-register a hardware specific acpi
+ * Description: This is used to un-register a hardware specific acpi
  * driver that manipulates the attention LED.  The pointer to the 
  * info struct must be the same as the one used to set it.
- **/
+ */
 int acpiphp_unregister_attention(struct acpiphp_attention_info *info)
 {
 	int retval = -EINVAL;
@@ -133,7 +133,6 @@ int acpiphp_unregister_attention(struct acpiphp_attention_info *info)
  * @hotplug_slot: slot to enable
  *
  * Actual tasks are done in acpiphp_enable_slot()
- *
  */
 static int enable_slot(struct hotplug_slot *hotplug_slot)
 {
@@ -151,7 +150,6 @@ static int enable_slot(struct hotplug_slot *hotplug_slot)
  * @hotplug_slot: slot to disable
  *
  * Actual tasks are done in acpiphp_disable_slot()
- *
  */
 static int disable_slot(struct hotplug_slot *hotplug_slot)
 {
@@ -168,15 +166,15 @@ static int disable_slot(struct hotplug_slot *hotplug_slot)
 }
 
 
- /**
-  * set_attention_status - set attention LED
+/**
+ * set_attention_status - set attention LED
  * @hotplug_slot: slot to set attention LED on
  * @status: value to set attention LED to (0 or 1)
  *
  * attention status LED, so we use a callback that
  * was registered with us.  This allows hardware specific
  * ACPI implementations to blink the light for us.
- **/
+ */
  static int set_attention_status(struct hotplug_slot *hotplug_slot, u8 status)
  {
 	int retval = -ENODEV;
@@ -199,7 +197,6 @@ static int disable_slot(struct hotplug_slot *hotplug_slot)
  *
  * Some platforms may not implement _STA method properly.
  * In that case, the value returned may not be reliable.
- *
  */
 static int get_power_status(struct hotplug_slot *hotplug_slot, u8 *value)
 {
@@ -213,7 +210,7 @@ static int get_power_status(struct hotplug_slot *hotplug_slot, u8 *value)
 }
 
 
- /**
+/**
  * get_attention_status - get attention LED status
  * @hotplug_slot: slot to get status from
  * @value: returns with value of attention LED
@@ -221,8 +218,8 @@ static int get_power_status(struct hotplug_slot *hotplug_slot, u8 *value)
  * ACPI doesn't have known method to determine the state
  * of the attention status LED, so we use a callback that
  * was registered with us.  This allows hardware specific
- * ACPI implementations to determine its state
- **/
+ * ACPI implementations to determine its state.
+ */
 static int get_attention_status(struct hotplug_slot *hotplug_slot, u8 *value)
 {
 	int retval = -EINVAL;
@@ -244,8 +241,7 @@ static int get_attention_status(struct hotplug_slot *hotplug_slot, u8 *value)
  * @value: pointer to store status
  *
  * ACPI doesn't provide any formal means to access latch status.
- * Instead, we fake latch status from _STA
- *
+ * Instead, we fake latch status from _STA.
  */
 static int get_latch_status(struct hotplug_slot *hotplug_slot, u8 *value)
 {
@@ -265,8 +261,7 @@ static int get_latch_status(struct hotplug_slot *hotplug_slot, u8 *value)
  * @value: pointer to store status
  *
  * ACPI doesn't provide any formal means to access adapter status.
- * Instead, we fake adapter status from _STA
- *
+ * Instead, we fake adapter status from _STA.
  */
 static int get_adapter_status(struct hotplug_slot *hotplug_slot, u8 *value)
 {

drivers/pci/hotplug/acpiphp_glue.c

@@ -82,7 +82,6 @@ static void handle_hotplug_event_func(acpi_handle handle, u32 type, void *contex
  *  2. has _PS0 method
  *  3. has _PS3 method
  *  4. ..
- *
  */
 static int is_ejectable(acpi_handle handle)
 {
@@ -986,10 +985,8 @@ static int power_off_slot(struct acpiphp_slot *slot)
 
 
 /**
- * acpiphp_max_busnr - return the highest reserved bus number under
- * the given bus.
+ * acpiphp_max_busnr - return the highest reserved bus number under the given bus.
  * @bus: bus to start search with
- *
  */
 static unsigned char acpiphp_max_busnr(struct pci_bus *bus)
 {
@@ -1018,7 +1015,6 @@ static unsigned char acpiphp_max_busnr(struct pci_bus *bus)
 /**
  * acpiphp_bus_add - add a new bus to acpi subsystem
  * @func: acpiphp_func of the bridge
- *
  */
 static int acpiphp_bus_add(struct acpiphp_func *func)
 {
@@ -1063,7 +1059,6 @@ static int acpiphp_bus_add(struct acpiphp_func *func)
 /**
  * acpiphp_bus_trim - trim a bus from acpi subsystem
  * @handle: handle to acpi namespace
- *
  */
 static int acpiphp_bus_trim(acpi_handle handle)
 {
@@ -1089,7 +1084,6 @@ static int acpiphp_bus_trim(acpi_handle handle)
  *
  * This function should be called per *physical slot*,
  * not per each slot object in ACPI namespace.
- *
  */
 static int enable_device(struct acpiphp_slot *slot)
 {
@@ -1185,6 +1179,7 @@ static void disable_bridges(struct pci_bus *bus)
 
 /**
  * disable_device - disable a slot
+ * @slot: ACPI PHP slot
  */
 static int disable_device(struct acpiphp_slot *slot)
 {
@@ -1240,14 +1235,15 @@ static int disable_device(struct acpiphp_slot *slot)
 
 /**
  * get_slot_status - get ACPI slot status
+ * @slot: ACPI PHP slot
  *
- * if a slot has _STA for each function and if any one of them
- * returned non-zero status, return it
+ * If a slot has _STA for each function and if any one of them
+ * returned non-zero status, return it.
  *
- * if a slot doesn't have _STA and if any one of its functions'
- * configuration space is configured, return 0x0f as a _STA
+ * If a slot doesn't have _STA and if any one of its functions'
+ * configuration space is configured, return 0x0f as a _STA.
  *
- * otherwise return 0
+ * Otherwise return 0.
  */
 static unsigned int get_slot_status(struct acpiphp_slot *slot)
 {
@@ -1281,6 +1277,7 @@ static unsigned int get_slot_status(struct acpiphp_slot *slot)
 
 /**
  * acpiphp_eject_slot - physically eject the slot
+ * @slot: ACPI PHP slot
  */
 int acpiphp_eject_slot(struct acpiphp_slot *slot)
 {
@@ -1314,6 +1311,7 @@ int acpiphp_eject_slot(struct acpiphp_slot *slot)
 
 /**
  * acpiphp_check_bridge - re-enumerate devices
+ * @bridge: where to begin re-enumeration
  *
  * Iterate over all slots under this bridge and make sure that if a
  * card is present they are enabled, and if not they are disabled.
@@ -1538,13 +1536,11 @@ check_sub_bridges(acpi_handle handle, u32 lvl, void *context, void **rv)
 
 /**
  * handle_hotplug_event_bridge - handle ACPI event on bridges
- *
  * @handle: Notify()'ed acpi_handle
  * @type: Notify code
  * @context: pointer to acpiphp_bridge structure
  *
- * handles ACPI event notification on {host,p2p} bridges
- *
+ * Handles ACPI event notification on {host,p2p} bridges.
  */
 static void handle_hotplug_event_bridge(acpi_handle handle, u32 type, void *context)
 {
@@ -1634,13 +1630,11 @@ static void handle_hotplug_event_bridge(acpi_handle handle, u32 type, void *cont
 
 /**
  * handle_hotplug_event_func - handle ACPI event on functions (i.e. slots)
- *
  * @handle: Notify()'ed acpi_handle
  * @type: Notify code
  * @context: pointer to acpiphp_func structure
  *
- * handles ACPI event notification on slots
- *
+ * Handles ACPI event notification on slots.
  */
 static void handle_hotplug_event_func(acpi_handle handle, u32 type, void *context)
 {
@@ -1705,7 +1699,6 @@ static struct acpi_pci_driver acpi_pci_hp_driver = {
 
 /**
  * acpiphp_glue_init - initializes all PCI hotplug - ACPI glue data structures
- *
  */
 int __init acpiphp_glue_init(void)
 {
@@ -1726,7 +1719,7 @@ int __init acpiphp_glue_init(void)
 /**
  * acpiphp_glue_exit - terminates all PCI hotplug - ACPI glue data structures
  *
- * This function frees all data allocated in acpiphp_glue_init()
+ * This function frees all data allocated in acpiphp_glue_init().
  */
 void  acpiphp_glue_exit(void)
 {
@@ -1760,7 +1753,6 @@ int __init acpiphp_get_num_slots(void)
  * acpiphp_for_each_slot - call function for each slot
  * @fn: callback function
  * @data: context to be passed to callback function
- *
  */
 static int acpiphp_for_each_slot(acpiphp_callback fn, void *data)
 {
@@ -1786,6 +1778,7 @@ static int acpiphp_for_each_slot(acpiphp_callback fn, void *data)
 
 /**
  * acpiphp_enable_slot - power on slot
+ * @slot: ACPI PHP slot
  */
 int acpiphp_enable_slot(struct acpiphp_slot *slot)
 {
@@ -1815,6 +1808,7 @@ int acpiphp_enable_slot(struct acpiphp_slot *slot)
 
 /**
  * acpiphp_disable_slot - power off slot
+ * @slot: ACPI PHP slot
  */
 int acpiphp_disable_slot(struct acpiphp_slot *slot)
 {

drivers/pci/hotplug/acpiphp_ibm.c

@@ -134,11 +134,11 @@ static struct acpiphp_attention_info ibm_attention_info =
  * ibm_slot_from_id - workaround for bad ibm hardware
  * @id: the slot number that linux refers to the slot by
  *
- * Description: this method returns the aCPI slot descriptor
+ * Description: This method returns the aCPI slot descriptor
  * corresponding to the Linux slot number.  This descriptor
  * has info about the aPCI slot id and attention status.
  * This descriptor must be freed using kfree when done.
- **/
+ */
 static union apci_descriptor *ibm_slot_from_id(int id)
 {
 	int ind = 0, size;
@@ -173,9 +173,9 @@ static union apci_descriptor *ibm_slot_from_id(int id)
  * @slot: the hotplug_slot to work with
  * @status: what to set the LED to (0 or 1)
  *
- * Description: this method is registered with the acpiphp module as a
- * callback to do the device specific task of setting the LED status
- **/
+ * Description: This method is registered with the acpiphp module as a
+ * callback to do the device specific task of setting the LED status.
+ */
 static int ibm_set_attention_status(struct hotplug_slot *slot, u8 status)
 {
 	union acpi_object args[2]; 
@@ -213,13 +213,13 @@ static int ibm_set_attention_status(struct hotplug_slot *slot, u8 status)
  * @slot: the hotplug_slot to work with
  * @status: returns what the LED is set to (0 or 1)
  *
- * Description: this method is registered with the acpiphp module as a
- * callback to do the device specific task of getting the LED status
+ * Description: This method is registered with the acpiphp module as a
+ * callback to do the device specific task of getting the LED status.
  * 
  * Because there is no direct method of getting the LED status directly
  * from an ACPI call, we read the aPCI table and parse out our
  * slot descriptor to read the status from that.
- **/
+ */
 static int ibm_get_attention_status(struct hotplug_slot *slot, u8 *status)
 {
 	union apci_descriptor *ibm_slot;
@@ -245,8 +245,8 @@ static int ibm_get_attention_status(struct hotplug_slot *slot, u8 *status)
  * @event: the event info (device specific)
  * @context: passed context (our notification struct)
  *
- * Description: this method is registered as a callback with the ACPI
- * subsystem it is called when this device has an event to notify the OS of
+ * Description: This method is registered as a callback with the ACPI
+ * subsystem it is called when this device has an event to notify the OS of.
  *
  * The events actually come from the device as two events that get
  * synthesized into one event with data by this function.  The event
@@ -256,7 +256,7 @@ static int ibm_get_attention_status(struct hotplug_slot *slot, u8 *status)
  * From section 5.6.2.2 of the ACPI 2.0 spec, I understand that the OSPM will
  * only re-enable the interrupt that causes this event AFTER this method
  * has returned, thereby enforcing serial access for the notification struct.
- **/
+ */
 static void ibm_handle_events(acpi_handle handle, u32 event, void *context)
 {
 	u8 detail = event & 0x0f;
@@ -279,16 +279,16 @@ static void ibm_handle_events(acpi_handle handle, u32 event, void *context)
  * ibm_get_table_from_acpi - reads the APLS buffer from ACPI
  * @bufp: address to pointer to allocate for the table
  *
- * Description: this method reads the APLS buffer in from ACPI and
+ * Description: This method reads the APLS buffer in from ACPI and
  * stores the "stripped" table into a single buffer
- * it allocates and passes the address back in bufp
+ * it allocates and passes the address back in bufp.
  *
  * If NULL is passed in as buffer, this method only calculates
  * the size of the table and returns that without filling
- * in the buffer
+ * in the buffer.
  *
- * returns < 0 on error or the size of the table on success
- **/
+ * Returns < 0 on error or the size of the table on success.
+ */
 static int ibm_get_table_from_acpi(char **bufp)
 {
 	union acpi_object *package;
@@ -349,17 +349,18 @@ static int ibm_get_table_from_acpi(char **bufp)
 /**
  * ibm_read_apci_table - callback for the sysfs apci_table file
  * @kobj: the kobject this binary attribute is a part of
+ * @bin_attr: struct bin_attribute for this file
  * @buffer: the kernel space buffer to fill
  * @pos: the offset into the file
  * @size: the number of bytes requested
  *
- * Description: gets registered with sysfs as the reader callback
- * to be executed when /sys/bus/pci/slots/apci_table gets read
+ * Description: Gets registered with sysfs as the reader callback
+ * to be executed when /sys/bus/pci/slots/apci_table gets read.
  *
  * Since we don't get notified on open and close for this file,
  * things get really tricky here...
- * our solution is to only allow reading the table in all at once
- **/
+ * our solution is to only allow reading the table in all at once.
+ */
 static ssize_t ibm_read_apci_table(struct kobject *kobj,
 				   struct bin_attribute *bin_attr,
 				   char *buffer, loff_t pos, size_t size)
@@ -385,10 +386,10 @@ static ssize_t ibm_read_apci_table(struct kobject *kobj,
  * @context: a pointer to our handle to fill when we find the device
  * @rv: a return value to fill if desired
  *
- * Description: used as a callback when calling acpi_walk_namespace
+ * Description: Used as a callback when calling acpi_walk_namespace
  * to find our device.  When this method returns non-zero
- * acpi_walk_namespace quits its search and returns our value
- **/
+ * acpi_walk_namespace quits its search and returns our value.
+ */
 static acpi_status __init ibm_find_acpi_device(acpi_handle handle,
 		u32 lvl, void *context, void **rv)
 {

drivers/pci/hotplug/cpqphp_core.c

@@ -117,12 +117,10 @@ static inline int is_slot66mhz(struct slot *slot)
 
 /**
  * detect_SMBIOS_pointer - find the System Management BIOS Table in mem region.
- *
  * @begin: begin pointer for region to be scanned.
  * @end: end pointer for region to be scanned.
  *
- * Returns pointer to the head of the SMBIOS tables (or NULL)
- *
+ * Returns pointer to the head of the SMBIOS tables (or %NULL).
  */
 static void __iomem * detect_SMBIOS_pointer(void __iomem *begin, void __iomem *end)
 {
@@ -157,9 +155,9 @@ static void __iomem * detect_SMBIOS_pointer(void __iomem *begin, void __iomem *e
 
 /**
  * init_SERR - Initializes the per slot SERR generation.
+ * @ctrl: controller to use
  *
  * For unexpected switch opens
- *
  */
 static int init_SERR(struct controller * ctrl)
 {
@@ -224,14 +222,15 @@ static int pci_print_IRQ_route (void)
 
 /**
  * get_subsequent_smbios_entry: get the next entry from bios table.
- *
- * Gets the first entry if previous == NULL
- * Otherwise, returns the next entry
- * Uses global SMBIOS Table pointer
- *
+ * @smbios_start: where to start in the SMBIOS table
+ * @smbios_table: location of the SMBIOS table
  * @curr: %NULL or pointer to previously returned structure
  *
- * returns a pointer to an SMBIOS structure or NULL if none found
+ * Gets the first entry if previous == NULL;
+ * otherwise, returns the next entry.
+ * Uses global SMBIOS Table pointer.
+ *
+ * Returns a pointer to an SMBIOS structure or NULL if none found.
  */
 static void __iomem *get_subsequent_smbios_entry(void __iomem *smbios_start,
 						void __iomem *smbios_table,
@@ -272,17 +271,18 @@ static void __iomem *get_subsequent_smbios_entry(void __iomem *smbios_start,
 
 
 /**
- * get_SMBIOS_entry
- *
- * @type:SMBIOS structure type to be returned
+ * get_SMBIOS_entry - return the requested SMBIOS entry or %NULL
+ * @smbios_start: where to start in the SMBIOS table
+ * @smbios_table: location of the SMBIOS table
+ * @type: SMBIOS structure type to be returned
  * @previous: %NULL or pointer to previously returned structure
  *
- * Gets the first entry of the specified type if previous == NULL
+ * Gets the first entry of the specified type if previous == %NULL;
  * Otherwise, returns the next entry of the given type.
- * Uses global SMBIOS Table pointer
- * Uses get_subsequent_smbios_entry
+ * Uses global SMBIOS Table pointer.
+ * Uses get_subsequent_smbios_entry.
  *
- * returns a pointer to an SMBIOS structure or %NULL if none found
+ * Returns a pointer to an SMBIOS structure or %NULL if none found.
  */
 static void __iomem *get_SMBIOS_entry(void __iomem *smbios_start,
 					void __iomem *smbios_table,
@@ -581,7 +581,9 @@ get_slot_mapping(struct pci_bus *bus, u8 bus_num, u8 dev_num, u8 *slot)
 
 /**
  * cpqhp_set_attention_status - Turns the Amber LED for a slot on or off
- *
+ * @ctrl: struct controller to use
+ * @func: PCI device/function info
+ * @status: LED control flag: 1 = LED on, 0 = LED off
  */
 static int
 cpqhp_set_attention_status(struct controller *ctrl, struct pci_func *func,
@@ -621,7 +623,8 @@ cpqhp_set_attention_status(struct controller *ctrl, struct pci_func *func,
 
 /**
  * set_attention_status - Turns the Amber LED for a slot on or off
- *
+ * @hotplug_slot: slot to change LED on
+ * @status: LED control flag
  */
 static int set_attention_status (struct hotplug_slot *hotplug_slot, u8 status)
 {

drivers/pci/hotplug/fakephp.c

@@ -165,11 +165,11 @@ static void remove_slot(struct dummy_slot *dslot)
 }
 
 /**
- * Rescan slot.
- * Tries hard not to re-enable already existing devices
- * also handles scanning of subfunctions
+ * pci_rescan_slot - Rescan slot
+ * @temp: Device template. Should be set: bus and devfn.
  *
- * @param temp   Device template. Should be set: bus and devfn.
+ * Tries hard not to re-enable already existing devices;
+ * also handles scanning of subfunctions.
  */
 static void pci_rescan_slot(struct pci_dev *temp)
 {
@@ -229,10 +229,10 @@ static void pci_rescan_slot(struct pci_dev *temp)
 
 
 /**
- * Rescan PCI bus.
- * call pci_rescan_slot for each possible function of the bus
+ * pci_rescan_bus - Rescan PCI bus
+ * @bus: the PCI bus to rescan
  *
- * @param bus
+ * Call pci_rescan_slot for each possible function of the bus.
  */
 static void pci_rescan_bus(const struct pci_bus *bus)
 {

drivers/pci/hotplug/pciehp_ctrl.c

@@ -208,10 +208,10 @@ static void set_slot_off(struct controller *ctrl, struct slot * pslot)
 
 /**
  * board_added - Called after a board has been added to the system.
+ * @p_slot: &slot where board is added
  *
- * Turns power on for the board
- * Configures board
- *
+ * Turns power on for the board.
+ * Configures board.
  */
 static int board_added(struct slot *p_slot)
 {
@@ -276,8 +276,8 @@ static int board_added(struct slot *p_slot)
 }
 
 /**
- * remove_board - Turns off slot and LED's
- *
+ * remove_board - Turns off slot and LEDs
+ * @p_slot: slot where board is being removed
  */
 static int remove_board(struct slot *p_slot)
 {
@@ -319,11 +319,11 @@ struct power_work_info {
 };
 
 /**
- * pciehp_pushbutton_thread
+ * pciehp_power_thread - handle pushbutton events
+ * @work: &struct work_struct describing work to be done
  *
- * Scheduled procedure to handle blocking stuff for the pushbuttons
+ * Scheduled procedure to handle blocking stuff for the pushbuttons.
  * Handles all pending events and exits.
- *
  */
 static void pciehp_power_thread(struct work_struct *work)
 {

drivers/pci/hotplug/rpadlpar_core.c

@@ -100,6 +100,7 @@ static struct device_node *find_dlpar_node(char *drc_name, int *node_type)
 
 /**
  * find_php_slot - return hotplug slot structure for device node
+ * @dn: target &device_node
  *
  * This routine will return the hotplug slot structure
  * for a given device node. Note that built-in PCI slots
@@ -293,9 +294,8 @@ static int dlpar_add_vio_slot(char *drc_name, struct device_node *dn)
  * dlpar_add_slot - DLPAR add an I/O Slot
  * @drc_name: drc-name of newly added slot
  *
- * Make the hotplug module and the kernel aware
- * of a newly added I/O Slot.
- * Return Codes -
+ * Make the hotplug module and the kernel aware of a newly added I/O Slot.
+ * Return Codes:
  * 0			Success
  * -ENODEV		Not a valid drc_name
  * -EINVAL		Slot already added
@@ -339,9 +339,9 @@ int dlpar_add_slot(char *drc_name)
 /**
  * dlpar_remove_vio_slot - DLPAR remove a virtual I/O Slot
  * @drc_name: drc-name of newly added slot
+ * @dn: &device_node
  *
- * Remove the kernel and hotplug representations
- * of an I/O Slot.
+ * Remove the kernel and hotplug representations of an I/O Slot.
  * Return Codes:
  * 0			Success
  * -EINVAL		Vio dev doesn't exist
@@ -359,11 +359,11 @@ static int dlpar_remove_vio_slot(char *drc_name, struct device_node *dn)
 }
 
 /**
- * dlpar_remove_slot - DLPAR remove a PCI I/O Slot
+ * dlpar_remove_pci_slot - DLPAR remove a PCI I/O Slot
  * @drc_name: drc-name of newly added slot
+ * @dn: &device_node
  *
- * Remove the kernel and hotplug representations
- * of a PCI I/O Slot.
+ * Remove the kernel and hotplug representations of a PCI I/O Slot.
  * Return Codes:
  * 0			Success
  * -ENODEV		Not a valid drc_name
@@ -405,8 +405,7 @@ int dlpar_remove_pci_slot(char *drc_name, struct device_node *dn)
  * dlpar_remove_slot - DLPAR remove an I/O Slot
  * @drc_name: drc-name of newly added slot
  *
- * Remove the kernel and hotplug representations
- * of an I/O Slot.
+ * Remove the kernel and hotplug representations of an I/O Slot.
  * Return Codes:
  * 0			Success
  * -ENODEV		Not a valid drc_name

drivers/pci/hotplug/rpaphp_core.c

@@ -54,10 +54,12 @@ module_param(debug, bool, 0644);
 
 /**
  * set_attention_status - set attention LED
+ * @hotplug_slot: target &hotplug_slot
+ * @value: LED control value
+ *
  * echo 0 > attention -- set LED OFF
  * echo 1 > attention -- set LED ON
  * echo 2 > attention -- set LED ID(identify, light is blinking)
- *
  */
 static int set_attention_status(struct hotplug_slot *hotplug_slot, u8 value)
 {
@@ -99,6 +101,8 @@ static int get_power_status(struct hotplug_slot *hotplug_slot, u8 * value)
 
 /**
  * get_attention_status - get attention LED status
+ * @hotplug_slot: slot to get status
+ * @value: pointer to store status
  */
 static int get_attention_status(struct hotplug_slot *hotplug_slot, u8 * value)
 {
@@ -254,6 +258,11 @@ static int is_php_type(char *drc_type)
 
 /**
  * is_php_dn() - return 1 if this is a hotpluggable pci slot, else 0
+ * @dn: target &device_node
+ * @indexes: passed to get_children_props()
+ * @names: passed to get_children_props()
+ * @types: returned from get_children_props()
+ * @power_domains:
  *
  * This routine will return true only if the device node is
  * a hotpluggable slot. This routine will return false
@@ -279,7 +288,7 @@ static int is_php_dn(struct device_node *dn, const int **indexes,
 
 /**
  * rpaphp_add_slot -- declare a hotplug slot to the hotplug subsystem.
- * @dn device node of slot
+ * @dn: device node of slot
  *
  * This subroutine will register a hotplugable slot with the
  * PCI hotplug infrastructure. This routine is typicaly called
@@ -291,7 +300,7 @@ static int is_php_dn(struct device_node *dn, const int **indexes,
  * routine will just return without doing anything, since embedded
  * slots cannot be hotplugged.
  *
- * To remove a slot, it suffices to call rpaphp_deregister_slot()
+ * To remove a slot, it suffices to call rpaphp_deregister_slot().
  */
 int rpaphp_add_slot(struct device_node *dn)
 {

drivers/pci/hotplug/rpaphp_pci.c

@@ -79,6 +79,7 @@ static void set_slot_name(struct slot *slot)
 
 /**
  * rpaphp_enable_slot - record slot state, config pci device
+ * @slot: target &slot
  *
  * Initialize values in the slot, and the hotplug_slot info
  * structures to indicate if there is a pci card plugged into

drivers/pci/hotplug/shpchp_ctrl.c

@@ -231,10 +231,10 @@ static int fix_bus_speed(struct controller *ctrl, struct slot *pslot,
 
 /**
  * board_added - Called after a board has been added to the system.
+ * @p_slot: target &slot
  *
- * Turns power on for the board
- * Configures board
- *
+ * Turns power on for the board.
+ * Configures board.
  */
 static int board_added(struct slot *p_slot)
 {
@@ -350,8 +350,8 @@ static int board_added(struct slot *p_slot)
 
 
 /**
- * remove_board - Turns off slot and LED's
- *
+ * remove_board - Turns off slot and LEDs
+ * @p_slot: target &slot
  */
 static int remove_board(struct slot *p_slot)
 {
@@ -397,11 +397,11 @@ struct pushbutton_work_info {
 };
 
 /**
- * shpchp_pushbutton_thread
+ * shpchp_pushbutton_thread - handle pushbutton events
+ * @work: &struct work_struct to be handled
  *
- * Scheduled procedure to handle blocking stuff for the pushbuttons
+ * Scheduled procedure to handle blocking stuff for the pushbuttons.
  * Handles all pending events and exits.
- *
  */
 static void shpchp_pushbutton_thread(struct work_struct *work)
 {