net: Fix (nearly-)kernel-doc comments for various functions
Fix incorrect start markers, wrapped summary lines, missing section
breaks, incorrect separators, and some name mismatches.
Signed-off-by: Ben Hutchings <bhutchings@solarflare.com>
Signed-off-by: David S. Miller <davem@davemloft.net>
diff --git a/net/tipc/bcast.c b/net/tipc/bcast.c
index 2625f5e..d9df34f 100644
--- a/net/tipc/bcast.c
+++ b/net/tipc/bcast.c
@@ -162,7 +162,7 @@
}
-/*
+/**
* tipc_bclink_retransmit_to - get most recent node to request retransmission
*
* Called with bc_lock locked
@@ -270,7 +270,7 @@
spin_unlock_bh(&bc_lock);
}
-/*
+/**
* tipc_bclink_update_link_state - update broadcast link state
*
* tipc_net_lock and node lock set
@@ -330,7 +330,7 @@
}
}
-/*
+/**
* bclink_peek_nack - monitor retransmission requests sent by other nodes
*
* Delay any upcoming NACK by this node if another node has already
@@ -381,7 +381,7 @@
return res;
}
-/*
+/**
* bclink_accept_pkt - accept an incoming, in-sequence broadcast packet
*
* Called with both sending node's lock and bc_lock taken.
@@ -406,7 +406,7 @@
}
}
-/*
+/**
* tipc_bclink_recv_pkt - receive a broadcast packet, and deliver upwards
*
* tipc_net_lock is read_locked, no other locks set
diff --git a/net/tipc/bearer.c b/net/tipc/bearer.c
index a297e3a..86b703f 100644
--- a/net/tipc/bearer.c
+++ b/net/tipc/bearer.c
@@ -172,8 +172,8 @@
/**
* bearer_name_validate - validate & (optionally) deconstruct bearer name
- * @name - ptr to bearer name string
- * @name_parts - ptr to area for bearer name components (or NULL if not needed)
+ * @name: ptr to bearer name string
+ * @name_parts: ptr to area for bearer name components (or NULL if not needed)
*
* Returns 1 if bearer name is valid, otherwise 0.
*/
@@ -520,8 +520,7 @@
}
/**
- * tipc_block_bearer(): Block the bearer with the given name,
- * and reset all its links
+ * tipc_block_bearer - Block the bearer with the given name, and reset all its links
*/
int tipc_block_bearer(const char *name)
{
diff --git a/net/tipc/bearer.h b/net/tipc/bearer.h
index e3b2be3..4680de1 100644
--- a/net/tipc/bearer.h
+++ b/net/tipc/bearer.h
@@ -57,7 +57,7 @@
*/
#define TIPC_MEDIA_TYPE_ETH 1
-/*
+/**
* struct tipc_media_addr - destination address used by TIPC bearers
* @value: address info (format defined by media)
* @media_id: TIPC media type identifier
diff --git a/net/tipc/link.c b/net/tipc/link.c
index 7a614f4..f6bf483 100644
--- a/net/tipc/link.c
+++ b/net/tipc/link.c
@@ -153,8 +153,8 @@
/**
* link_name_validate - validate & (optionally) deconstruct tipc_link name
- * @name - ptr to link name string
- * @name_parts - ptr to area for link name components (or NULL if not needed)
+ * @name: ptr to link name string
+ * @name_parts: ptr to area for link name components (or NULL if not needed)
*
* Returns 1 if link name is valid, otherwise 0.
*/
@@ -944,7 +944,7 @@
return res;
}
-/*
+/**
* tipc_link_send_names - send name table entries to new neighbor
*
* Send routine for bulk delivery of name table messages when contact
@@ -1787,7 +1787,7 @@
read_unlock_bh(&tipc_net_lock);
}
-/*
+/**
* tipc_link_defer_pkt - Add out-of-sequence message to deferred reception queue
*
* Returns increase in queue length (i.e. 0 or 1)
@@ -2635,8 +2635,8 @@
/**
* link_find_link - locate link by name
- * @name - ptr to link name string
- * @node - ptr to area to be filled with ptr to associated node
+ * @name: ptr to link name string
+ * @node: ptr to area to be filled with ptr to associated node
*
* Caller must hold 'tipc_net_lock' to ensure node and bearer are not deleted;
* this also prevents link deletion.
@@ -2671,8 +2671,8 @@
/**
* link_value_is_valid -- validate proposed link tolerance/priority/window
*
- * @cmd - value type (TIPC_CMD_SET_LINK_*)
- * @new_value - the new value
+ * @cmd: value type (TIPC_CMD_SET_LINK_*)
+ * @new_value: the new value
*
* Returns 1 if value is within range, 0 if not.
*/
@@ -2693,9 +2693,9 @@
/**
* link_cmd_set_value - change priority/tolerance/window for link/bearer/media
- * @name - ptr to link, bearer, or media name
- * @new_value - new value of link, bearer, or media setting
- * @cmd - which link, bearer, or media attribute to set (TIPC_CMD_SET_LINK_*)
+ * @name: ptr to link, bearer, or media name
+ * @new_value: new value of link, bearer, or media setting
+ * @cmd: which link, bearer, or media attribute to set (TIPC_CMD_SET_LINK_*)
*
* Caller must hold 'tipc_net_lock' to ensure link/bearer/media is not deleted.
*
diff --git a/net/tipc/name_table.c b/net/tipc/name_table.c
index 010f24a..13fb9d5 100644
--- a/net/tipc/name_table.c
+++ b/net/tipc/name_table.c
@@ -191,7 +191,7 @@
}
}
-/*
+/**
* nameseq_find_subseq - find sub-sequence (if any) matching a name instance
*
* Very time-critical, so binary searches through sub-sequence array.
@@ -435,7 +435,7 @@
}
/**
- * tipc_nameseq_subscribe: attach a subscription, and issue
+ * tipc_nameseq_subscribe - attach a subscription, and issue
* the prescribed number of events if there is any sub-
* sequence overlapping with the requested sequence
*/
@@ -520,7 +520,7 @@
return publ;
}
-/*
+/**
* tipc_nametbl_translate - perform name translation
*
* On entry, 'destnode' is the search domain used during translation.
@@ -751,7 +751,7 @@
/**
- * subseq_list: print specified sub-sequence contents into the given buffer
+ * subseq_list - print specified sub-sequence contents into the given buffer
*/
static void subseq_list(struct sub_seq *sseq, struct print_buf *buf, u32 depth,
u32 index)
@@ -787,7 +787,7 @@
}
/**
- * nameseq_list: print specified name sequence contents into the given buffer
+ * nameseq_list - print specified name sequence contents into the given buffer
*/
static void nameseq_list(struct name_seq *seq, struct print_buf *buf, u32 depth,
u32 type, u32 lowbound, u32 upbound, u32 index)
diff --git a/net/tipc/port.c b/net/tipc/port.c
index a1e8289..70bf78b 100644
--- a/net/tipc/port.c
+++ b/net/tipc/port.c
@@ -69,7 +69,7 @@
return msg_destport(&p_ptr->phdr);
}
-/*
+/**
* tipc_port_peer_msg - verify message was sent by connected port's peer
*
* Handles cases where the node's network address has changed from
diff --git a/net/tipc/port.h b/net/tipc/port.h
index 98cbec9..4660e30 100644
--- a/net/tipc/port.h
+++ b/net/tipc/port.h
@@ -79,6 +79,7 @@
* struct user_port - TIPC user port (used with native API)
* @usr_handle: user-specified field
* @ref: object reference to associated TIPC port
+ *
* <various callback routines>
*/
struct user_port {