Commit 3f330db3 authored by Jakub Kicinski's avatar Jakub Kicinski
Browse files

net: reformat kdoc return statements 



kernel-doc -Wall warns about missing Return: statement for non-void
functions. We have a number of kdocs in our headers which are missing
the colon, IOW they use
 * Return some value
or
 * Returns some value

Having the colon makes some sense, it should help kdoc parser avoid
false positives. So add them. This is mostly done with a sed script,
and removing the unnecessary cases (mostly the comments which aren't
kdoc).

Acked-by: default avatarJohannes Berg <johannes@sipsolutions.net>
Acked-by: default avatarRichard Cochran <richardcochran@gmail.com>
Acked-by: default avatarSergey Ryazanov <ryazanov.s.a@gmail.com>
Reviewed-by: default avatarEdward Cree <ecree.xilinx@gmail.com>
Acked-by: default avatarAlexandra Winter <wintera@linux.ibm.com>
Acked-by: default avatarPablo Neira Ayuso <pablo@netfilter.org>
Link: https://patch.msgid.link/20241205165914.1071102-1-kuba@kernel.org


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent ca785888

include/linux/etherdevice.h

+9 −9
Original line number Diff line number Diff line
@@ -81,7 +81,7 @@ static const u8 eth_ipv6_mcast_addr_base[ETH_ALEN] __aligned(2) = 
 * is_link_local_ether_addr - Determine if given Ethernet address is link-local

 * @addr: Pointer to a six-byte array containing the Ethernet address

 *

 * Return true if address is link local reserved addr (01:80:c2:00:00:0X) per

 * Return: true if address is link local reserved addr (01:80:c2:00:00:0X) per

 * IEEE 802.1Q 8.6.3 Frame filtering.

 *

 * Please note: addr must be aligned to u16.
@@ -104,7 +104,7 @@ static inline bool is_link_local_ether_addr(const u8 *addr) 
 * is_zero_ether_addr - Determine if give Ethernet address is all zeros.

 * @addr: Pointer to a six-byte array containing the Ethernet address

 *

 * Return true if the address is all zeroes.

 * Return: true if the address is all zeroes.

 *

 * Please note: addr must be aligned to u16.

 */
@@ -123,7 +123,7 @@ static inline bool is_zero_ether_addr(const u8 *addr) 
 * is_multicast_ether_addr - Determine if the Ethernet address is a multicast.

 * @addr: Pointer to a six-byte array containing the Ethernet address

 *

 * Return true if the address is a multicast address.

 * Return: true if the address is a multicast address.

 * By definition the broadcast address is also a multicast address.

 */

static inline bool is_multicast_ether_addr(const u8 *addr)
@@ -157,7 +157,7 @@ static inline bool is_multicast_ether_addr_64bits(const u8 *addr) 
 * is_local_ether_addr - Determine if the Ethernet address is locally-assigned one (IEEE 802).

 * @addr: Pointer to a six-byte array containing the Ethernet address

 *

 * Return true if the address is a local address.

 * Return: true if the address is a local address.

 */

static inline bool is_local_ether_addr(const u8 *addr)

{
@@ -168,7 +168,7 @@ static inline bool is_local_ether_addr(const u8 *addr) 
 * is_broadcast_ether_addr - Determine if the Ethernet address is broadcast

 * @addr: Pointer to a six-byte array containing the Ethernet address

 *

 * Return true if the address is the broadcast address.

 * Return: true if the address is the broadcast address.

 *

 * Please note: addr must be aligned to u16.

 */
@@ -183,7 +183,7 @@ static inline bool is_broadcast_ether_addr(const u8 *addr) 
 * is_unicast_ether_addr - Determine if the Ethernet address is unicast

 * @addr: Pointer to a six-byte array containing the Ethernet address

 *

 * Return true if the address is a unicast address.

 * Return: true if the address is a unicast address.

 */

static inline bool is_unicast_ether_addr(const u8 *addr)

{
@@ -197,7 +197,7 @@ static inline bool is_unicast_ether_addr(const u8 *addr) 
 * Check that the Ethernet address (MAC) is not 00:00:00:00:00:00, is not

 * a multicast address, and is not FF:FF:FF:FF:FF:FF.

 *

 * Return true if the address is valid.

 * Return: true if the address is valid.

 *

 * Please note: addr must be aligned to u16.

 */
@@ -214,7 +214,7 @@ static inline bool is_valid_ether_addr(const u8 *addr) 
 *

 * Check that the value from the Ethertype/length field is a valid Ethertype.

 *

 * Return true if the valid is an 802.3 supported Ethertype.

 * Return: true if the valid is an 802.3 supported Ethertype.

 */

static inline bool eth_proto_is_802_3(__be16 proto)

{
@@ -458,7 +458,7 @@ static inline bool ether_addr_is_ip_mcast(const u8 *addr) 
 * ether_addr_to_u64 - Convert an Ethernet address into a u64 value.

 * @addr: Pointer to a six-byte array containing the Ethernet address

 *

 * Return a u64 value of the address

 * Return: a u64 value of the address

 */

static inline u64 ether_addr_to_u64(const u8 *addr)

{

include/linux/ethtool.h

+3 −3
Original line number Diff line number Diff line
@@ -257,7 +257,7 @@ struct ethtool_link_ksettings { 
 *   @mode : one of the ETHTOOL_LINK_MODE_*_BIT

 * (not atomic, no bound checking)

 *

 * Returns true/false.

 * Returns: true/false.

 */

#define ethtool_link_ksettings_test_link_mode(ptr, name, mode)		\

	test_bit(ETHTOOL_LINK_MODE_ ## mode ## _BIT, (ptr)->link_modes.name)
@@ -1199,7 +1199,7 @@ ethtool_params_from_link_mode(struct ethtool_link_ksettings *link_ksettings, 
 * @dev: pointer to net_device structure

 * @vclock_index: pointer to pointer of vclock index

 *

 * Return number of phc vclocks

 * Return: number of phc vclocks

 */

int ethtool_get_phc_vclocks(struct net_device *dev, int **vclock_index);
@@ -1253,7 +1253,7 @@ static inline int ethtool_mm_frag_size_min_to_add(u32 val_min, u32 *val_add, 
 * ethtool_get_ts_info_by_layer - Obtains time stamping capabilities from the MAC or PHY layer.

 * @dev: pointer to net_device structure

 * @info: buffer to hold the result

 * Returns zero on success, non-zero otherwise.

 * Returns: zero on success, non-zero otherwise.

 */

int ethtool_get_ts_info_by_layer(struct net_device *dev,

				 struct kernel_ethtool_ts_info *info);

include/linux/if_vlan.h

+14 −14
Original line number Diff line number Diff line
@@ -310,7 +310,7 @@ static inline bool vlan_uses_dev(const struct net_device *dev) 
 * eth_type_vlan - check for valid vlan ether type.

 * @ethertype: ether type to check

 *

 * Returns true if the ether type is a vlan ether type.

 * Returns: true if the ether type is a vlan ether type.

 */

static inline bool eth_type_vlan(__be16 ethertype)

{
@@ -341,9 +341,9 @@ static inline bool vlan_hw_offload_capable(netdev_features_t features, 
 * @mac_len: MAC header length including outer vlan headers

 *

 * Inserts the VLAN tag into @skb as part of the payload at offset mac_len

 * Returns error if skb_cow_head fails.

 *

 * Does not change skb->protocol so this function can be used during receive.

 *

 * Returns: error if skb_cow_head fails.

 */

static inline int __vlan_insert_inner_tag(struct sk_buff *skb,

					  __be16 vlan_proto, u16 vlan_tci,
@@ -390,9 +390,9 @@ static inline int __vlan_insert_inner_tag(struct sk_buff *skb, 
 * @vlan_tci: VLAN TCI to insert

 *

 * Inserts the VLAN tag into @skb as part of the payload

 * Returns error if skb_cow_head fails.

 *

 * Does not change skb->protocol so this function can be used during receive.

 *

 * Returns: error if skb_cow_head fails.

 */

static inline int __vlan_insert_tag(struct sk_buff *skb,

				    __be16 vlan_proto, u16 vlan_tci)
@@ -533,7 +533,7 @@ static inline void __vlan_hwaccel_put_tag(struct sk_buff *skb, 
 * @skb: skbuff to query

 * @vlan_tci: buffer to store value

 *

 * Returns error if the skb is not of VLAN type

 * Returns: error if the skb is not of VLAN type

 */

static inline int __vlan_get_tag(const struct sk_buff *skb, u16 *vlan_tci)

{
@@ -551,7 +551,7 @@ static inline int __vlan_get_tag(const struct sk_buff *skb, u16 *vlan_tci) 
 * @skb: skbuff to query

 * @vlan_tci: buffer to store value

 *

 * Returns error if @skb->vlan_tci is not set correctly

 * Returns: error if @skb->vlan_tci is not set correctly

 */

static inline int __vlan_hwaccel_get_tag(const struct sk_buff *skb,

					 u16 *vlan_tci)
@@ -570,7 +570,7 @@ static inline int __vlan_hwaccel_get_tag(const struct sk_buff *skb, 
 * @skb: skbuff to query

 * @vlan_tci: buffer to store value

 *

 * Returns error if the skb is not VLAN tagged

 * Returns: error if the skb is not VLAN tagged

 */

static inline int vlan_get_tag(const struct sk_buff *skb, u16 *vlan_tci)

{
@@ -587,7 +587,7 @@ static inline int vlan_get_tag(const struct sk_buff *skb, u16 *vlan_tci) 
 * @type: first vlan protocol

 * @depth: buffer to store length of eth and vlan tags in bytes

 *

 * Returns the EtherType of the packet, regardless of whether it is

 * Returns: the EtherType of the packet, regardless of whether it is

 * vlan encapsulated (normal or hardware accelerated) or not.

 */

static inline __be16 __vlan_get_protocol(const struct sk_buff *skb, __be16 type,
@@ -629,7 +629,7 @@ static inline __be16 __vlan_get_protocol(const struct sk_buff *skb, __be16 type, 
 * vlan_get_protocol - get protocol EtherType.

 * @skb: skbuff to query

 *

 * Returns the EtherType of the packet, regardless of whether it is

 * Returns: the EtherType of the packet, regardless of whether it is

 * vlan encapsulated (normal or hardware accelerated) or not.

 */

static inline __be16 vlan_get_protocol(const struct sk_buff *skb)
@@ -710,7 +710,7 @@ static inline void vlan_set_encap_proto(struct sk_buff *skb, 
 * Expects the skb to contain a VLAN tag in the payload, and to have skb->data

 * pointing at the MAC header.

 *

 * Returns a new pointer to skb->data, or NULL on failure to pull.

 * Returns: a new pointer to skb->data, or NULL on failure to pull.

 */

static inline void *vlan_remove_tag(struct sk_buff *skb, u16 *vlan_tci)

{
@@ -727,7 +727,7 @@ static inline void *vlan_remove_tag(struct sk_buff *skb, u16 *vlan_tci) 
 * skb_vlan_tagged - check if skb is vlan tagged.

 * @skb: skbuff to query

 *

 * Returns true if the skb is tagged, regardless of whether it is hardware

 * Returns: true if the skb is tagged, regardless of whether it is hardware

 * accelerated or not.

 */

static inline bool skb_vlan_tagged(const struct sk_buff *skb)
@@ -743,7 +743,7 @@ static inline bool skb_vlan_tagged(const struct sk_buff *skb) 
 * skb_vlan_tagged_multi - check if skb is vlan tagged with multiple headers.

 * @skb: skbuff to query

 *

 * Returns true if the skb is tagged with multiple vlan headers, regardless

 * Returns: true if the skb is tagged with multiple vlan headers, regardless

 * of whether it is hardware accelerated or not.

 */

static inline bool skb_vlan_tagged_multi(struct sk_buff *skb)
@@ -774,7 +774,7 @@ static inline bool skb_vlan_tagged_multi(struct sk_buff *skb) 
 * @skb: skbuff to query

 * @features: features to be checked

 *

 * Returns features without unsafe ones if the skb has multiple tags.

 * Returns: features without unsafe ones if the skb has multiple tags.

 */

static inline netdev_features_t vlan_features_check(struct sk_buff *skb,

						    netdev_features_t features)

include/linux/netdevice.h

+8 −6
Original line number Diff line number Diff line
@@ -509,7 +509,7 @@ static inline bool napi_prefer_busy_poll(struct napi_struct *n) 
 * is scheduled for example in the context of delayed timer

 * that can be skipped if a NAPI is already scheduled.

 *

 * Return True if NAPI is scheduled, False otherwise.

 * Return: True if NAPI is scheduled, False otherwise.

 */

static inline bool napi_is_scheduled(struct napi_struct *n)

{
@@ -524,7 +524,7 @@ bool napi_schedule_prep(struct napi_struct *n); 
 *

 * Schedule NAPI poll routine to be called if it is not already

 * running.

 * Return true if we schedule a NAPI or false if not.

 * Return: true if we schedule a NAPI or false if not.

 * Refer to napi_schedule_prep() for additional reason on why

 * a NAPI might not be scheduled.

 */
@@ -558,7 +558,7 @@ static inline void napi_schedule_irqoff(struct napi_struct *n) 
 * Mark NAPI processing as complete. Should only be called if poll budget

 * has not been completely consumed.

 * Prefer over napi_complete().

 * Return false if device should avoid rearming interrupts.

 * Return: false if device should avoid rearming interrupts.

 */

bool napi_complete_done(struct napi_struct *n, int work_done);
@@ -3851,7 +3851,7 @@ static inline bool netif_attr_test_mask(unsigned long j, 
 *	@online_mask: bitmask for CPUs/Rx queues that are online

 *	@nr_bits: number of bits in the bitmask

 *

 * Returns true if a CPU/Rx queue is online.

 * Returns: true if a CPU/Rx queue is online.

 */

static inline bool netif_attr_test_online(unsigned long j,

					  const unsigned long *online_mask,
@@ -3871,7 +3871,8 @@ static inline bool netif_attr_test_online(unsigned long j, 
 *	@srcp: the cpumask/Rx queue mask pointer

 *	@nr_bits: number of bits in the bitmask

 *

 * Returns >= nr_bits if no further CPUs/Rx queues set.

 * Returns: next (after n) CPU/Rx queue index in the mask;

 * >= nr_bits if no further CPUs/Rx queues set.

 */

static inline unsigned int netif_attrmask_next(int n, const unsigned long *srcp,

					       unsigned int nr_bits)
@@ -3893,7 +3894,8 @@ static inline unsigned int netif_attrmask_next(int n, const unsigned long *srcp, 
 *	@src2p: the second CPUs/Rx queues mask pointer

 *	@nr_bits: number of bits in the bitmask

 *

 * Returns >= nr_bits if no further CPUs/Rx queues set in both.

 * Returns: next (after n) CPU/Rx queue index set in both masks;

 * >= nr_bits if no further CPUs/Rx queues set in both.

 */

static inline int netif_attrmask_next_and(int n, const unsigned long *src1p,

					  const unsigned long *src2p,

include/linux/netfilter_netdev.h

+2 −1
Original line number Diff line number Diff line
@@ -66,7 +66,6 @@ static inline bool nf_hook_egress_active(void) 
 * @rc: result code which shall be returned by __dev_queue_xmit() on failure

 * @dev: netdev whose egress hooks shall be applied to @skb

 *

 * Returns @skb on success or %NULL if the packet was consumed or filtered.

 * Caller must hold rcu_read_lock.

 *

 * On ingress, packets are classified first by tc, then by netfilter.
@@ -81,6 +80,8 @@ static inline bool nf_hook_egress_active(void) 
 * called recursively by tunnel drivers such as vxlan, the flag is reverted to

 * false after sch_handle_egress().  This ensures that netfilter is applied

 * both on the overlay and underlying network.

 *

 * Returns: @skb on success or %NULL if the packet was consumed or filtered.

 */

static inline struct sk_buff *nf_hook_egress(struct sk_buff *skb, int *rc,

					     struct net_device *dev)