PCI: hotplug: Fix kernel-doc formatting and add missing documentation
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
@@ -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
@@ -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
@@ -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
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@@ -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
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