Skip to contentSkip to conversation

PCI: hotplug: Fix kernel-doc formatting and add missing documentation

PATCH In review Krzysztof Wilczyński 2 participants 3 messages Jul 2, 2021 – Jul 3, 2021 PCI

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 PCI: hotplug: Fix kernel-doc formatting and add missing documentation

Fix kernel-doc formatting and add missing documentation for the parameters "bus" of the get_slot_mapping() function, "t" of the cpqhp_pushbutton_thread() function and "controller" of the inband_presence_disabled() function.

Additionally, fix formatting and add missing documentation for the members "slot_list" and "pci_slot" of the struct hotplug_slot.

Also remove surplus parameter "slot" from the description of the function cpqhp_pushbutton_thread().

Thus, resolve build time warnings related to kernel-doc:

drivers/pci/hotplug/cpqphp_core.c:308: warning: Function parameter or member 'bus' not described in 'get_slot_mapping' drivers/pci/hotplug/cpqphp_core.c:308: warning: Function parameter or member 'bus_num' not described in 'get_slot_mapping' drivers/pci/hotplug/cpqphp_core.c:308: warning: Function parameter or member 'dev_num' not described in 'get_slot_mapping' drivers/pci/hotplug/cpqphp_core.c:308: warning: Function parameter or member 'slot' not described in 'get_slot_mapping'

drivers/pci/hotplug/cpqphp_ctrl.c:1887: warning: Function parameter or member 't' not described in 'cpqhp_pushbutton_thread' drivers/pci/hotplug/cpqphp_ctrl.c:1887: warning: Excess function parameter 'slot' description in 'cpqhp_pushbutton_thread'

drivers/pci/hotplug/pciehp.h:110: warning: Function parameter or member 'inband_presence_disabled' not described in 'controller'

include/linux/pci_hotplug.h:64: warning: Function parameter or member 'slot_list' not described in 'hotplug_slot' include/linux/pci_hotplug.h:64: warning: Function parameter or member 'pci_slot' not described in 'hotplug_slot'

No change to functionality intended.

---
Changes in v3:
Added kernel-doc fixes for the file include/linux/pci_hotplug.h.
Changes in v2:
Added kernel-doc fixes for the files drivers/pci/hotplug/cpqphp_ctrl.c and drivers/pci/hotplug/pciehp.h.

 drivers/pci/hotplug/cpqphp_core.c | 16 ++++---
 drivers/pci/hotplug/cpqphp_ctrl.c |  4 +-
 drivers/pci/hotplug/pciehp.h      | 80 ++++++++++++++++++-------------
 include/linux/pci_hotplug.h       | 12 +++--
 4 files changed, 67 insertions(+), 45 deletions(-)
drivers/pci/hotplug/cpqphp_core.c +9 -7
index b8aacb41a83c..efe6031c1e68 100644
@@ -292,15 +292,17 @@ static int ctrl_slot_cleanup(struct controller *ctrl)
 
 
 /**
- * get_slot_mapping - determine logical slot mapping for PCI device
+ * get_slot_mapping - Determine logical slot mapping for PCI device.
+ * @bus:	Pointer to the PCI bus structure.
+ * @bus_num:	Bus number of the PCI device.
+ * @dev_num:	Device number of the PCI device.
+ * @slot:	Pointer to where slot number will be returned.
  *
- * Won't work for more than one PCI-PCI bridge in a slot.
+ * Will not work for more than one PCI-PCI bridge in a slot.
  *
- * @bus_num - bus number of PCI device
- * @dev_num - device number of PCI device
- * @slot - Pointer to u8 where slot number will	be returned
- *
- * Output:	SUCCESS or FAILURE
+ * Return:
+ * * 0		- Logical slot mapping has been found for this PCI device.
+ * * < 0	- Unable to find entry in the routing table for this PCI device.
  */
 static int
 get_slot_mapping(struct pci_bus *bus, u8 bus_num, u8 dev_num, u8 *slot)
drivers/pci/hotplug/cpqphp_ctrl.c +2 -2
index 68de958a9be8..035114423ebb 100644
@@ -1876,8 +1876,8 @@ static void interrupt_event_handler(struct controller *ctrl)
 
 
 /**
- * cpqhp_pushbutton_thread - handle pushbutton events
- * @slot: target slot (struct)
+ * cpqhp_pushbutton_thread - Handle pushbutton events.
+ * @t: Pointer to struct timer_list which holds all timer related callbacks.
  *
  * Scheduled procedure to handle blocking stuff for the pushbuttons.
  * Handles all pending events and exits.
drivers/pci/hotplug/pciehp.h +48 -32

86 lines not on this page · raw message

include/linux/pci_hotplug.h +8 -4
index b482e42d7153..a73851884b81 100644
@@ -48,10 +48,14 @@ struct hotplug_slot_ops {
 };
 
 /**
- * struct hotplug_slot - used to register a physical slot with the hotplug pci core
- * @ops: pointer to the &struct hotplug_slot_ops to be used for this slot
- * @owner: The module owner of this structure
- * @mod_name: The module name (KBUILD_MODNAME) of this structure
+ * struct hotplug_slot - Used to register a physical slot with the hotplug PCI
+ *			 core.
+ * @ops:	Pointer to the &struct hotplug_slot_ops to be used for this
+ *		slot.
+ * @slot_list:	Internal list used to track hotplug PCI slots.
+ * @pci_slot:	Pepresents a physical slot.
+ * @owner:	The module owner of this structure.
+ * @mod_name:	The module name (KBUILD_MODNAME) of this structure.
  */
 struct hotplug_slot {
 	const struct hotplug_slot_ops	*ops;
Signature · 1 line
2.32.0
#1 lore raw
Quoted 1 line · Krzysztof Wilczy??ski

Fix kernel-doc formatting and add missing documentation for the

[...]

Quoted 1 line

drivers/pci/hotplug/pciehp.h:110: warning: Function parameter or member 'inband_presence_disabled' not described in 'controller'

[...]

Quoted 12 lines
drivers/pci/hotplug/pciehp.h +0 -4
index 4fd200d8b0a9..c8b2b1e046e8 100644
@@ -44,38 +44,54 @@ extern int pciehp_poll_time;
 #define SLOT_NAME_SIZE 10
 
 /**
- * struct controller - PCIe hotplug controller
- * @pcie: pointer to the controller's PCIe port service device
- * @slot_cap: cached copy of the Slot Capabilities register
- * @slot_ctrl: cached copy of the Slot Control register

[...]

Quoted 4 lines

+ * struct controller - PCIe hotplug controller.
+ * @pcie: Pointer to the controller's PCIe port service
+ * device.
+ * @slot_cap: Cached copy of the Slot Capabilities register.

Is it really necessary to change the indentation and add the trailing period *everywhere*? What value does that add?

Changes like this make it more difficult to determine the commit from which a certain line originates.

I respectfully submit that the formatting is fine and there's nothing to be "fixed" here (as the commit message claims).

Quoted 2 lines

+ * @inband_presence_disabled: Flag to used to track whether the in-band
+ * presence detection is disabled.

That's not proper English and also not very useful because the documentation merely repeats what the flag's name says. I'd suggest something along the lines of:

* @inband_presence_disabled: whether In-Band Presence Detect Disable is
* supported by the controller and disabled per spec recommendation
* (PCIe r5.0, appendix I implementation note)

Thanks,

Lukas

#2 lore raw

Hi Lukas,

Thank you for feedback!

[...]

Quoted 2 lines

I respectfully submit that the formatting is fine and there's nothing to be "fixed" here (as the commit message claims).

The fixing it probably more relevant to the two first hunks, everything else would be more of a style update so that kernel-doc is kept with the following guideline:
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html

Which is something other users of kernel-doc seldom embrace as I could only find a handful of places where this format is somewhat followed.

Thus, like you say, keeping the scope of changes to only updating what matters would be more appropriate. I will send another revision that does exactly that.

Quoted 9 lines
Quoted 2 lines

+ * @inband_presence_disabled: Flag to used to track whether the in-band
+ * presence detection is disabled.

That's not proper English and also not very useful because the documentation merely repeats what the flag's name says. I'd suggest something along the lines of:
* @inband_presence_disabled: whether In-Band Presence Detect Disable is
* supported by the controller and disabled per spec recommendation
* (PCIe r5.0, appendix I implementation note)

Thank you! I will use your version going forward.

Krzysztof