Skip to contentSkip to conversation

Fix wrong identifiers on kernel-doc markups

PATCH RESEND In review Mauro Carvalho Chehab 4 participants 7 messages Oct 26, 2020 – Oct 28, 2020

Subsystems (7)
lore
Share & tools
lore
#0 lore raw

cover Fix wrong identifiers on kernel-doc markups

Hi Mark/Jakub,

As you requested, I'm resending the three -net patches from the /56 patch series I sent last Friday:

[PATCH v3 00/56] Fix several bad kernel-doc markups

They fix a few kernel-doc markups that are using different identifiers than the function/struct that they are actually documenting.

This should help checking them via CI automation.

Regards,
Mauro

Mauro Carvalho Chehab (3):
net: phy: fix kernel-doc markups
net: datagram: fix some kernel-doc markups
net: core: fix some kernel-doc markups

 drivers/net/phy/mdio_bus.c   |  2 +-
 drivers/net/phy/phy-c45.c    |  2 +-
 drivers/net/phy/phy.c        |  2 +-
 drivers/net/phy/phy_device.c |  2 +-
 drivers/net/phy/phylink.c    |  2 +-
 include/linux/netdevice.h    | 11 +++++++++--
 net/core/datagram.c          |  2 +-
 net/core/dev.c               |  4 ++--
 net/core/skbuff.c            |  2 +-
 net/ethernet/eth.c           |  6 +++---
 net/sunrpc/rpc_pipe.c        |  3 ++-
 11 files changed, 23 insertions(+), 15 deletions(-)
Signature · 1 line
2.26.2
#1 lore raw

PATCH RESEND 1/3 net: phy: fix kernel-doc markups

Some functions have different names between their prototypes and the kernel-doc markup.

---
 drivers/net/phy/mdio_bus.c   | 2 +-
 drivers/net/phy/phy-c45.c    | 2 +-
 drivers/net/phy/phy.c        | 2 +-
 drivers/net/phy/phy_device.c | 2 +-
 drivers/net/phy/phylink.c    | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)
drivers/net/phy/mdio_bus.c +1 -1
index 757e950fb745..e59067c64e97 100644
@@ -472,7 +472,7 @@ static inline void of_mdiobus_link_mdiodev(struct mii_bus *mdio,
 #endif
 
 /**
- * mdiobus_create_device_from_board_info - create a full MDIO device given
+ * mdiobus_create_device - create a full MDIO device given
  * a mdio_board_info structure
  * @bus: MDIO bus to create the devices on
  * @bi: mdio_board_info structure describing the devices
drivers/net/phy/phy-c45.c +1 -1
index bd11e62bfdfe..077f2929c45e 100644
@@ -9,7 +9,7 @@
 #include <linux/phy.h>
 
 /**
- * genphy_c45_setup_forced - configures a forced speed
+ * genphy_c45_pma_setup_forced - configures a forced speed
  * @phydev: target phy_device struct
  */
 int genphy_c45_pma_setup_forced(struct phy_device *phydev)
drivers/net/phy/phy.c +1 -1
index 35525a671400..71ed2596acf5 100644
@@ -489,7 +489,7 @@ void phy_queue_state_machine(struct phy_device *phydev, unsigned long jiffies)
 EXPORT_SYMBOL(phy_queue_state_machine);
 
 /**
- * phy_queue_state_machine - Trigger the state machine to run now
+ * phy_trigger_machine - Trigger the state machine to run now
  *
  * @phydev: the phy_device struct
  */
drivers/net/phy/phy_device.c +1 -1
index 5dab6be6fc38..ea5d5fb42d01 100644
@@ -2735,7 +2735,7 @@ static int phy_get_int_delay_property(struct device *dev, const char *name)
 #endif
 
 /**
- * phy_get_delay_index - returns the index of the internal delay
+ * phy_get_internal_delay - returns the index of the internal delay
  * @phydev: phy_device struct
  * @dev: pointer to the devices device struct
  * @delay_values: array of delays the PHY supports
drivers/net/phy/phylink.c +1 -1
index fe2296fdda19..1318ccb62bd7 100644
@@ -1649,7 +1649,7 @@ int phylink_ethtool_set_pauseparam(struct phylink *pl,
 EXPORT_SYMBOL_GPL(phylink_ethtool_set_pauseparam);
 
 /**
- * phylink_ethtool_get_eee_err() - read the energy efficient ethernet error
+ * phylink_get_eee_err() - read the energy efficient ethernet error
  *   counter
  * @pl: a pointer to a &struct phylink returned from phylink_create().
  *
Signature · 1 line
2.26.2
#3 lore raw

PATCH RESEND 2/3 net: datagram: fix some kernel-doc markups

In reply to Mauro Carvalho Chehab

Some identifiers have different names between their prototypes and the kernel-doc markup.

---
 net/core/datagram.c   | 2 +-
 net/core/dev.c        | 4 ++--
 net/core/skbuff.c     | 2 +-
 net/ethernet/eth.c    | 6 +++---
 net/sunrpc/rpc_pipe.c | 3 ++-
 5 files changed, 9 insertions(+), 8 deletions(-)
net/core/datagram.c +1 -1
index 9fcaa544f11a..81809fa735a7 100644
@@ -709,7 +709,7 @@ int zerocopy_sg_from_iter(struct sk_buff *skb, struct iov_iter *from)
 EXPORT_SYMBOL(zerocopy_sg_from_iter);
 
 /**
- *	skb_copy_and_csum_datagram_iter - Copy datagram to an iovec iterator
+ *	skb_copy_and_csum_datagram - Copy datagram to an iovec iterator
  *          and update a checksum.
  *	@skb: buffer to copy
  *	@offset: offset in the buffer to start copying from
net/core/dev.c +2 -2
index 751e5264fd49..75c879f8ab3f 100644
@@ -6915,7 +6915,7 @@ bool netdev_has_upper_dev(struct net_device *dev,
 EXPORT_SYMBOL(netdev_has_upper_dev);
 
 /**
- * netdev_has_upper_dev_all - Check if device is linked to an upper device
+ * netdev_has_upper_dev_all_rcu - Check if device is linked to an upper device
  * @dev: device
  * @upper_dev: upper device to check
  *
@@ -8153,7 +8153,7 @@ EXPORT_SYMBOL(netdev_lower_dev_get_private);
 
 
 /**
- * netdev_lower_change - Dispatch event about lower device state change
+ * netdev_lower_state_changed - Dispatch event about lower device state change
  * @lower_dev: device
  * @lower_state_info: state to dispatch
  *
net/core/skbuff.c +1 -1
index 1ba8f0163744..49da6b259444 100644
@@ -837,7 +837,7 @@ EXPORT_SYMBOL(consume_skb);
 #endif
 
 /**
- *	consume_stateless_skb - free an skbuff, assuming it is stateless
+ *	__consume_stateless_skb - free an skbuff, assuming it is stateless
  *	@skb: buffer to free
  *
  *	Alike consume_skb(), but this variant assumes that this is the last
net/ethernet/eth.c +3 -3
index dac65180c4ef..4106373180c6 100644
@@ -272,7 +272,7 @@ void eth_header_cache_update(struct hh_cache *hh,
 EXPORT_SYMBOL(eth_header_cache_update);
 
 /**
- * eth_header_parser_protocol - extract protocol from L2 header
+ * eth_header_parse_protocol - extract protocol from L2 header
  * @skb: packet to extract protocol from
  */
 __be16 eth_header_parse_protocol(const struct sk_buff *skb)
@@ -523,8 +523,8 @@ int eth_platform_get_mac_address(struct device *dev, u8 *mac_addr)
 EXPORT_SYMBOL(eth_platform_get_mac_address);
 
 /**
- * Obtain the MAC address from an nvmem cell named 'mac-address' associated
- * with given device.
+ * nvmem_get_mac_address - Obtain the MAC address from an nvmem cell named
+ * 'mac-address' associated with given device.
  *
  * @dev:	Device with which the mac-address cell is associated.
  * @addrbuf:	Buffer to which the MAC address will be copied on success.
net/sunrpc/rpc_pipe.c +2 -1
index eadc0ede928c..8241f5a4a01c 100644
@@ -781,7 +781,8 @@ static int rpc_rmdir_depopulate(struct dentry *dentry,
 }
 
 /**
- * rpc_mkpipe - make an rpc_pipefs file for kernel<->userspace communication
+ * rpc_mkpipe_dentry - make an rpc_pipefs file for kernel<->userspace
+ *		       communication
  * @parent: dentry of directory to create new "pipe" in
  * @name: name of pipe
  * @private: private data to associate with the pipe, for the caller's use
Signature · 1 line
2.26.2
#4 lore raw

PATCH RESEND 3/3 net: core: fix some kernel-doc markups

In reply to Mauro Carvalho Chehab

Some identifiers have different names between their prototypes and the kernel-doc markup.

In the specific case of netif_subqueue_stopped(), keep the current markup for __netif_subqueue_stopped(), adding a new one for netif_subqueue_stopped().

---
 include/linux/netdevice.h | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)
include/linux/netdevice.h +9 -2
index 964b494b0e8d..db79ab7580dd 100644
@@ -1490,7 +1490,7 @@ struct net_device_ops {
 };
 
 /**
- * enum net_device_priv_flags - &struct net_device priv_flags
+ * enum netdev_priv_flags - &struct net_device priv_flags
  *
  * These are the &struct net_device, they are only set internally
  * by drivers and used in the kernel. These flags are invisible to
@@ -3576,7 +3576,7 @@ static inline void netif_stop_subqueue(struct net_device *dev, u16 queue_index)
 }
 
 /**
- *	netif_subqueue_stopped - test status of subqueue
+ *	__netif_subqueue_stopped - test status of subqueue
  *	@dev: network device
  *	@queue_index: sub queue index
  *
@@ -3590,6 +3590,13 @@ static inline bool __netif_subqueue_stopped(const struct net_device *dev,
 	return netif_tx_queue_stopped(txq);
 }
 
+/**
+ *	netif_subqueue_stopped - test status of subqueue
+ *	@dev: network device
+ *	@skb: sub queue buffer pointer
+ *
+ * Check individual transmit queue of a device with multiple transmit queues.
+ */
 static inline bool netif_subqueue_stopped(const struct net_device *dev,
 					  struct sk_buff *skb)
 {
Signature · 1 line
2.26.2
maintainer
#5 lore raw

Re: [PATCH RESEND 3/3] net: core: fix some kernel-doc markups

Quoted 10 lines · On Mon, 26 Oct 2020 10:47:38 +0100 Mauro Carvalho Chehab wrote:

Some identifiers have different names between their prototypes and the kernel-doc markup.

In the specific case of netif_subqueue_stopped(), keep the current markup for __netif_subqueue_stopped(), adding a new one for netif_subqueue_stopped().

include/linux/netdevice.h static inline bool __netif_subqueue_stopped(const struct net_device *dev, · line 3596

Quoted 7 lines
include/linux/netdevice.h +4 -0
@@ -3590,6 +3590,13 @@ static inline bool __netif_subqueue_stopped(const struct net_device *dev,
 	return netif_tx_queue_stopped(txq);
 }
 
+/**
+ *	netif_subqueue_stopped - test status of subqueue
+ *	@dev: network device
+ *	@skb: sub queue buffer pointer

Ah, no: "socket buffer from which to get the mapping"

Quoted 6 lines
include/linux/netdevice.h +3 -0
+ *
+ * Check individual transmit queue of a device with multiple transmit queues.
+ */
 static inline bool netif_subqueue_stopped(const struct net_device *dev,
 					  struct sk_buff *skb)
 {
#6 lore raw
In reply to Mauro Carvalho Chehab
Quoted 4 lines · Mauro Carvalho Chehab

Hi Mark/Jakub,

As you requested, I'm resending the three -net patches from the /56 patch series I sent last Friday:

I was asking for you to do the same for the patches for my subsystems rather than resend the net patches to me - in general it's better to not to bundle things for multiple subsystems (or tangentially related changes in general) together like this. Splitting things up makes it easier to find the relevant changes and means that automations that work with patch serieses don't have to deal with things that span multiple different trees when it's not required.