[PATCH v3] maple_tree: cleanup function descriptions

[PATCH v3] maple_tree: cleanup function descriptions

[Wei Yang]

This patch tries to cleanup some function description:

  * function name mismatch
  * parameter name mismatch
  * parameter all end up with ':'
  * not prefix '*' if parameter is a pointer

There is still some missing description of parameters, I didn't add them
since I am not sure the exact meaning.

Signed-off-by: Wei Yang <richard.weiyang@gmail.com>
---
v3:
  * s/interface/function/ in change log
v2:
  * not change them to kernel doc since they are inline functions
---
 lib/maple_tree.c | 105 +++++++++++++++++++++--------------------------
 1 file changed, 47 insertions(+), 58 deletions(-)

diff --git a/lib/maple_tree.c b/lib/maple_tree.c
index b0ccd5539913..dda8e292c25b 100644
--- a/lib/maple_tree.c
+++ b/lib/maple_tree.c
@@ -474,6 +474,7 @@ enum maple_type mas_parent_type(struct ma_state *mas, struct maple_enode *enode)
 
 /*
  * mas_set_parent() - Set the parent node and encode the slot
+ * @mas: The maple state
  * @enode: The encoded maple node.
  * @parent: The encoded maple node that is the parent of @enode.
  * @slot: The slot that @enode resides in @parent.
@@ -534,7 +535,7 @@ unsigned int mte_parent_slot(const struct maple_enode *enode)
 
 /*
  * mte_parent() - Get the parent of @node.
- * @node: The encoded maple node.
+ * @enode: The encoded maple node.
  *
  * Return: The parent maple node.
  */
@@ -641,8 +642,8 @@ static inline unsigned int mas_alloc_req(const struct ma_state *mas)
 
 /*
  * ma_pivots() - Get a pointer to the maple node pivots.
- * @node - the maple node
- * @type - the node type
+ * @node: the maple node
+ * @type: the node type
  *
  * In the event of a dead node, this array may be %NULL
  *
@@ -665,8 +666,8 @@ static inline unsigned long *ma_pivots(struct maple_node *node,
 
 /*
  * ma_gaps() - Get a pointer to the maple node gaps.
- * @node - the maple node
- * @type - the node type
+ * @node: the maple node
+ * @type: the node type
  *
  * Return: A pointer to the maple node gaps
  */
@@ -880,8 +881,6 @@ static inline void ma_set_meta(struct maple_node *mn, enum maple_type mt,
  * @mt: The maple tree
  * @mn: The maple node
  * @type: The maple node type
- * @offset: The offset of the highest sub-gap in this node.
- * @end: The end of the data in this node.
  */
 static inline void mt_clear_meta(struct maple_tree *mt, struct maple_node *mn,
 				  enum maple_type type)
@@ -939,7 +938,7 @@ static inline unsigned char ma_meta_gap(struct maple_node *mn)
 /*
  * ma_set_meta_gap() - Set the largest gap location in a nodes metadata
  * @mn: The maple node
- * @mn: The maple node type
+ * @mt: The maple node type
  * @offset: The location of the largest gap.
  */
 static inline void ma_set_meta_gap(struct maple_node *mn, enum maple_type mt,
@@ -953,8 +952,8 @@ static inline void ma_set_meta_gap(struct maple_node *mn, enum maple_type mt,
 
 /*
  * mat_add() - Add a @dead_enode to the ma_topiary of a list of dead nodes.
- * @mat - the ma_topiary, a linked list of dead nodes.
- * @dead_enode - the node to be marked as dead and added to the tail of the list
+ * @mat: the ma_topiary, a linked list of dead nodes.
+ * @dead_enode: the node to be marked as dead and added to the tail of the list
  *
  * Add the @dead_enode to the linked list in @mat.
  */
@@ -977,8 +976,8 @@ static void mt_destroy_walk(struct maple_enode *enode, struct maple_tree *mt,
 			    bool free);
 /*
  * mas_mat_destroy() - Free all nodes and subtrees in a dead list.
- * @mas - the maple state
- * @mat - the ma_topiary linked list of dead nodes to free.
+ * @mas: the maple state
+ * @mat: the ma_topiary linked list of dead nodes to free.
  *
  * Destroy walk a dead list.
  */
@@ -999,7 +998,7 @@ static void mas_mat_destroy(struct ma_state *mas, struct ma_topiary *mat)
 }
 /*
  * mas_descend() - Descend into the slot stored in the ma_state.
- * @mas - the maple state.
+ * @mas: the maple state.
  *
  * Note: Not RCU safe, only use in write side or debug code.
  */
@@ -1448,7 +1447,7 @@ static inline unsigned char mas_data_end(struct ma_state *mas)
 
 /*
  * mas_leaf_max_gap() - Returns the largest gap in a leaf node
- * @mas - the maple state
+ * @mas: the maple state
  *
  * Return: The maximum gap in the leaf.
  */
@@ -1530,7 +1529,7 @@ static unsigned long mas_leaf_max_gap(struct ma_state *mas)
  * @node: The maple node
  * @gaps: The pointer to the gaps
  * @mt: The maple node type
- * @*off: Pointer to store the offset location of the gap.
+ * @off: Pointer to store the offset location of the gap.
  *
  * Uses the metadata data end to scan backwards across set gaps.
  *
@@ -1634,7 +1633,7 @@ static inline void mas_parent_gap(struct ma_state *mas, unsigned long new)
 
 /*
  * mas_update_gap() - Update a nodes gaps and propagate up if necessary.
- * @mas - the maple state.
+ * @mas: the maple state.
  */
 static inline void mas_update_gap(struct ma_state *mas)
 {
@@ -1650,8 +1649,8 @@ static inline void mas_update_gap(struct ma_state *mas)
 /*
  * mas_adopt_children() - Set the parent pointer of all nodes in @parent to
  * @parent with the slot encoded.
- * @mas - the maple state (for the tree)
- * @parent - the maple encoded node containing the children.
+ * @mas: the maple state (for the tree)
+ * @parent: the maple encoded node containing the children.
  */
 static inline void mas_adopt_children(struct ma_state *mas,
 		struct maple_enode *parent)
@@ -1673,8 +1672,8 @@ static inline void mas_adopt_children(struct ma_state *mas,
 /*
  * mas_put_in_tree() - Put a new node in the tree, smp_wmb(), and mark the old
  * node as dead.
- * @mas - the maple state with the new node
- * @old_enode - The old maple encoded node to replace.
+ * @mas: the maple state with the new node
+ * @old_enode: The old maple encoded node to replace.
  */
 static inline void mas_put_in_tree(struct ma_state *mas,
 		struct maple_enode *old_enode)
@@ -1702,8 +1701,8 @@ static inline void mas_put_in_tree(struct ma_state *mas,
  * mas_replace_node() - Replace a node by putting it in the tree, marking it
  * dead, and freeing it.
  * the parent encoding to locate the maple node in the tree.
- * @mas - the ma_state with @mas->node pointing to the new node.
- * @old_enode - The old maple encoded node.
+ * @mas: the ma_state with @mas->node pointing to the new node.
+ * @old_enode: The old maple encoded node.
  */
 static inline void mas_replace_node(struct ma_state *mas,
 		struct maple_enode *old_enode)
@@ -1768,7 +1767,6 @@ static inline void mab_shift_right(struct maple_big_node *b_node,
 /*
  * mab_middle_node() - Check if a middle node is needed (unlikely)
  * @b_node: the maple_big_node that contains the data.
- * @size: the amount of data in the b_node
  * @split: the potential split location
  * @slot_count: the size that can be stored in a single node being considered.
  *
@@ -1816,6 +1814,7 @@ static inline int mab_no_null_split(struct maple_big_node *b_node,
 /*
  * mab_calc_split() - Calculate the split location and if there needs to be two
  * splits.
+ * @mas: The maple state
  * @bn: The maple_big_node with the data
  * @mid_split: The second split, if required.  0 otherwise.
  *
@@ -2142,7 +2141,8 @@ static inline bool mas_next_sibling(struct ma_state *mas)
 }
 
 /*
- * mte_node_or_none() - Set the enode and state.
+ * mas_node_or_none() - Set the enode and state.
+ * @mas: the maple state
  * @enode: The encoded maple node.
  *
  * Set the node to the enode and the status.
@@ -2193,7 +2193,6 @@ static inline void mas_wr_node_walk(struct ma_wr_state *wr_mas)
 /*
  * mast_rebalance_next() - Rebalance against the next node
  * @mast: The maple subtree state
- * @old_r: The encoded maple node to the right (next node).
  */
 static inline void mast_rebalance_next(struct maple_subtree_state *mast)
 {
@@ -2207,7 +2206,6 @@ static inline void mast_rebalance_next(struct maple_subtree_state *mast)
 /*
  * mast_rebalance_prev() - Rebalance against the previous node
  * @mast: The maple subtree state
- * @old_l: The encoded maple node to the left (previous node)
  */
 static inline void mast_rebalance_prev(struct maple_subtree_state *mast)
 {
@@ -2358,9 +2356,9 @@ static inline unsigned char mas_mab_to_node(struct ma_state *mas,
 /*
  * mab_set_b_end() - Add entry to b_node at b_node->b_end and increment the end
  * pointer.
- * @b_node - the big node to add the entry
- * @mas - the maple state to get the pivot (mas->max)
- * @entry - the entry to add, if NULL nothing happens.
+ * @b_node: the big node to add the entry
+ * @mas: the maple state to get the pivot (mas->max)
+ * @entry: the entry to add, if NULL nothing happens.
  */
 static inline void mab_set_b_end(struct maple_big_node *b_node,
 				 struct ma_state *mas,
@@ -2379,11 +2377,11 @@ static inline void mab_set_b_end(struct maple_big_node *b_node,
  * mas_set_split_parent() - combine_then_separate helper function.  Sets the parent
  * of @mas->node to either @left or @right, depending on @slot and @split
  *
- * @mas - the maple state with the node that needs a parent
- * @left - possible parent 1
- * @right - possible parent 2
- * @slot - the slot the mas->node was placed
- * @split - the split location between @left and @right
+ * @mas: the maple state with the node that needs a parent
+ * @left: possible parent 1
+ * @right: possible parent 2
+ * @slot: the slot the mas->node was placed
+ * @split: the split location between @left and @right
  */
 static inline void mas_set_split_parent(struct ma_state *mas,
 					struct maple_enode *left,
@@ -2403,11 +2401,11 @@ static inline void mas_set_split_parent(struct ma_state *mas,
 
 /*
  * mte_mid_split_check() - Check if the next node passes the mid-split
- * @**l: Pointer to left encoded maple node.
- * @**m: Pointer to middle encoded maple node.
- * @**r: Pointer to right encoded maple node.
+ * @l: Pointer to left encoded maple node.
+ * @m: Pointer to middle encoded maple node.
+ * @r: Pointer to right encoded maple node.
  * @slot: The offset
- * @*split: The split location.
+ * @split: The split location.
  * @mid_split: The middle split.
  */
 static inline void mte_mid_split_check(struct maple_enode **l,
@@ -2431,10 +2429,10 @@ static inline void mte_mid_split_check(struct maple_enode **l,
 /*
  * mast_set_split_parents() - Helper function to set three nodes parents.  Slot
  * is taken from @mast->l.
- * @mast - the maple subtree state
- * @left - the left node
- * @right - the right node
- * @split - the split location.
+ * @mast: the maple subtree state
+ * @left: the left node
+ * @right: the right node
+ * @split: the split location.
  */
 static inline void mast_set_split_parents(struct maple_subtree_state *mast,
 					  struct maple_enode *left,
@@ -2468,7 +2466,6 @@ static inline void mast_set_split_parents(struct maple_subtree_state *mast,
 /*
  * mas_topiary_node() - Dispose of a single node
  * @mas: The maple state for pushing nodes
- * @enode: The encoded maple node
  * @in_rcu: If the tree is in rcu mode
  *
  * The node will either be RCU freed or pushed back on the maple state.
@@ -2600,7 +2597,7 @@ static inline void mas_topiary_replace(struct ma_state *mas,
 /*
  * mas_wmb_replace() - Write memory barrier and replace
  * @mas: The maple state
- * @old: The old maple encoded node that is being replaced.
+ * @old_enode: The old maple encoded node that is being replaced.
  *
  * Updates gap as necessary.
  */
@@ -3491,10 +3488,7 @@ static inline void mas_store_root(struct ma_state *mas, void *entry)
 /*
  * mas_is_span_wr() - Check if the write needs to be treated as a write that
  * spans the node.
- * @mas: The maple state
- * @piv: The pivot value being written
- * @type: The maple node type
- * @entry: The data to write
+ * @wr_mas: The maple write state
  *
  * Spanning writes are writes that start in one node and end in another OR if
  * the write of a %NULL will cause the node to end with a %NULL.
@@ -4159,10 +4153,7 @@ static inline void mas_wr_modify(struct ma_wr_state *wr_mas)
 
 /*
  * mas_wr_store_entry() - Internal call to store a value
- * @mas: The maple state
- * @entry: The entry to store.
- *
- * Return: The contents that was stored at the index.
+ * @wr_mas: The maple write state
  */
 static inline void mas_wr_store_entry(struct ma_wr_state *wr_mas)
 {
@@ -4401,9 +4392,8 @@ static int mas_prev_node(struct ma_state *mas, unsigned long min)
  * mas_prev_slot() - Get the entry in the previous slot
  *
  * @mas: The maple state
- * @max: The minimum starting range
+ * @min: The minimum starting range
  * @empty: Can be empty
- * @set_underflow: Set the @mas->node to underflow state on limit.
  *
  * Return: The entry in the previous slot which is possibly NULL
  */
@@ -4486,6 +4476,7 @@ static void *mas_prev_slot(struct ma_state *mas, unsigned long min, bool empty)
 /*
  * mas_next_node() - Get the next node at the same level in the tree.
  * @mas: The maple state
+ * @node: The maple node
  * @max: The maximum pivot value to check.
  *
  * The next value will be mas->node[mas->offset] or the status will have
@@ -4576,8 +4567,6 @@ static int mas_next_node(struct ma_state *mas, struct maple_node *node,
  * @mas: The maple state
  * @max: The maximum starting range
  * @empty: Can be empty
- * @set_overflow: Should @mas->node be set to overflow when the limit is
- * reached.
  *
  * Return: The entry in the next slot which is possibly NULL
  */
@@ -5111,9 +5100,9 @@ EXPORT_SYMBOL_GPL(mas_empty_area_rev);
 
 /*
  * mte_dead_leaves() - Mark all leaves of a node as dead.
- * @mas: The maple state
+ * @enode: the encoded node
+ * @mt: the maple tree
  * @slots: Pointer to the slot array
- * @type: The maple node type
  *
  * Must hold the write lock.
  *
-- 
2.34.1

Re: [PATCH v3] maple_tree: cleanup function descriptions

[Liam R. Howlett]

* Wei Yang <richard.weiyang@gmail.com> [240830 18:04]:
> This patch tries to cleanup some function description:
> 
>   * function name mismatch
>   * parameter name mismatch
>   * parameter all end up with ':'
>   * not prefix '*' if parameter is a pointer
> 
> There is still some missing description of parameters, I didn't add them
> since I am not sure the exact meaning.

Thanks.

Reviewed-by: Liam R. Howlett <Liam.Howlett@Oracle.com>

> 
> Signed-off-by: Wei Yang <richard.weiyang@gmail.com>
> ---
> v3:
>   * s/interface/function/ in change log
> v2:
>   * not change them to kernel doc since they are inline functions
> ---
>  lib/maple_tree.c | 105 +++++++++++++++++++++--------------------------
>  1 file changed, 47 insertions(+), 58 deletions(-)
> 
> diff --git a/lib/maple_tree.c b/lib/maple_tree.c
> index b0ccd5539913..dda8e292c25b 100644
> --- a/lib/maple_tree.c
> +++ b/lib/maple_tree.c
> @@ -474,6 +474,7 @@ enum maple_type mas_parent_type(struct ma_state *mas, struct maple_enode *enode)
>  
>  /*
>   * mas_set_parent() - Set the parent node and encode the slot
> + * @mas: The maple state
>   * @enode: The encoded maple node.
>   * @parent: The encoded maple node that is the parent of @enode.
>   * @slot: The slot that @enode resides in @parent.
> @@ -534,7 +535,7 @@ unsigned int mte_parent_slot(const struct maple_enode *enode)
>  
>  /*
>   * mte_parent() - Get the parent of @node.
> - * @node: The encoded maple node.
> + * @enode: The encoded maple node.
>   *
>   * Return: The parent maple node.
>   */
> @@ -641,8 +642,8 @@ static inline unsigned int mas_alloc_req(const struct ma_state *mas)
>  
>  /*
>   * ma_pivots() - Get a pointer to the maple node pivots.
> - * @node - the maple node
> - * @type - the node type
> + * @node: the maple node
> + * @type: the node type
>   *
>   * In the event of a dead node, this array may be %NULL
>   *
> @@ -665,8 +666,8 @@ static inline unsigned long *ma_pivots(struct maple_node *node,
>  
>  /*
>   * ma_gaps() - Get a pointer to the maple node gaps.
> - * @node - the maple node
> - * @type - the node type
> + * @node: the maple node
> + * @type: the node type
>   *
>   * Return: A pointer to the maple node gaps
>   */
> @@ -880,8 +881,6 @@ static inline void ma_set_meta(struct maple_node *mn, enum maple_type mt,
>   * @mt: The maple tree
>   * @mn: The maple node
>   * @type: The maple node type
> - * @offset: The offset of the highest sub-gap in this node.
> - * @end: The end of the data in this node.
>   */
>  static inline void mt_clear_meta(struct maple_tree *mt, struct maple_node *mn,
>  				  enum maple_type type)
> @@ -939,7 +938,7 @@ static inline unsigned char ma_meta_gap(struct maple_node *mn)
>  /*
>   * ma_set_meta_gap() - Set the largest gap location in a nodes metadata
>   * @mn: The maple node
> - * @mn: The maple node type
> + * @mt: The maple node type
>   * @offset: The location of the largest gap.
>   */
>  static inline void ma_set_meta_gap(struct maple_node *mn, enum maple_type mt,
> @@ -953,8 +952,8 @@ static inline void ma_set_meta_gap(struct maple_node *mn, enum maple_type mt,
>  
>  /*
>   * mat_add() - Add a @dead_enode to the ma_topiary of a list of dead nodes.
> - * @mat - the ma_topiary, a linked list of dead nodes.
> - * @dead_enode - the node to be marked as dead and added to the tail of the list
> + * @mat: the ma_topiary, a linked list of dead nodes.
> + * @dead_enode: the node to be marked as dead and added to the tail of the list
>   *
>   * Add the @dead_enode to the linked list in @mat.
>   */
> @@ -977,8 +976,8 @@ static void mt_destroy_walk(struct maple_enode *enode, struct maple_tree *mt,
>  			    bool free);
>  /*
>   * mas_mat_destroy() - Free all nodes and subtrees in a dead list.
> - * @mas - the maple state
> - * @mat - the ma_topiary linked list of dead nodes to free.
> + * @mas: the maple state
> + * @mat: the ma_topiary linked list of dead nodes to free.
>   *
>   * Destroy walk a dead list.
>   */
> @@ -999,7 +998,7 @@ static void mas_mat_destroy(struct ma_state *mas, struct ma_topiary *mat)
>  }
>  /*
>   * mas_descend() - Descend into the slot stored in the ma_state.
> - * @mas - the maple state.
> + * @mas: the maple state.
>   *
>   * Note: Not RCU safe, only use in write side or debug code.
>   */
> @@ -1448,7 +1447,7 @@ static inline unsigned char mas_data_end(struct ma_state *mas)
>  
>  /*
>   * mas_leaf_max_gap() - Returns the largest gap in a leaf node
> - * @mas - the maple state
> + * @mas: the maple state
>   *
>   * Return: The maximum gap in the leaf.
>   */
> @@ -1530,7 +1529,7 @@ static unsigned long mas_leaf_max_gap(struct ma_state *mas)
>   * @node: The maple node
>   * @gaps: The pointer to the gaps
>   * @mt: The maple node type
> - * @*off: Pointer to store the offset location of the gap.
> + * @off: Pointer to store the offset location of the gap.
>   *
>   * Uses the metadata data end to scan backwards across set gaps.
>   *
> @@ -1634,7 +1633,7 @@ static inline void mas_parent_gap(struct ma_state *mas, unsigned long new)
>  
>  /*
>   * mas_update_gap() - Update a nodes gaps and propagate up if necessary.
> - * @mas - the maple state.
> + * @mas: the maple state.
>   */
>  static inline void mas_update_gap(struct ma_state *mas)
>  {
> @@ -1650,8 +1649,8 @@ static inline void mas_update_gap(struct ma_state *mas)
>  /*
>   * mas_adopt_children() - Set the parent pointer of all nodes in @parent to
>   * @parent with the slot encoded.
> - * @mas - the maple state (for the tree)
> - * @parent - the maple encoded node containing the children.
> + * @mas: the maple state (for the tree)
> + * @parent: the maple encoded node containing the children.
>   */
>  static inline void mas_adopt_children(struct ma_state *mas,
>  		struct maple_enode *parent)
> @@ -1673,8 +1672,8 @@ static inline void mas_adopt_children(struct ma_state *mas,
>  /*
>   * mas_put_in_tree() - Put a new node in the tree, smp_wmb(), and mark the old
>   * node as dead.
> - * @mas - the maple state with the new node
> - * @old_enode - The old maple encoded node to replace.
> + * @mas: the maple state with the new node
> + * @old_enode: The old maple encoded node to replace.
>   */
>  static inline void mas_put_in_tree(struct ma_state *mas,
>  		struct maple_enode *old_enode)
> @@ -1702,8 +1701,8 @@ static inline void mas_put_in_tree(struct ma_state *mas,
>   * mas_replace_node() - Replace a node by putting it in the tree, marking it
>   * dead, and freeing it.
>   * the parent encoding to locate the maple node in the tree.
> - * @mas - the ma_state with @mas->node pointing to the new node.
> - * @old_enode - The old maple encoded node.
> + * @mas: the ma_state with @mas->node pointing to the new node.
> + * @old_enode: The old maple encoded node.
>   */
>  static inline void mas_replace_node(struct ma_state *mas,
>  		struct maple_enode *old_enode)
> @@ -1768,7 +1767,6 @@ static inline void mab_shift_right(struct maple_big_node *b_node,
>  /*
>   * mab_middle_node() - Check if a middle node is needed (unlikely)
>   * @b_node: the maple_big_node that contains the data.
> - * @size: the amount of data in the b_node
>   * @split: the potential split location
>   * @slot_count: the size that can be stored in a single node being considered.
>   *
> @@ -1816,6 +1814,7 @@ static inline int mab_no_null_split(struct maple_big_node *b_node,
>  /*
>   * mab_calc_split() - Calculate the split location and if there needs to be two
>   * splits.
> + * @mas: The maple state
>   * @bn: The maple_big_node with the data
>   * @mid_split: The second split, if required.  0 otherwise.
>   *
> @@ -2142,7 +2141,8 @@ static inline bool mas_next_sibling(struct ma_state *mas)
>  }
>  
>  /*
> - * mte_node_or_none() - Set the enode and state.
> + * mas_node_or_none() - Set the enode and state.
> + * @mas: the maple state
>   * @enode: The encoded maple node.
>   *
>   * Set the node to the enode and the status.
> @@ -2193,7 +2193,6 @@ static inline void mas_wr_node_walk(struct ma_wr_state *wr_mas)
>  /*
>   * mast_rebalance_next() - Rebalance against the next node
>   * @mast: The maple subtree state
> - * @old_r: The encoded maple node to the right (next node).
>   */
>  static inline void mast_rebalance_next(struct maple_subtree_state *mast)
>  {
> @@ -2207,7 +2206,6 @@ static inline void mast_rebalance_next(struct maple_subtree_state *mast)
>  /*
>   * mast_rebalance_prev() - Rebalance against the previous node
>   * @mast: The maple subtree state
> - * @old_l: The encoded maple node to the left (previous node)
>   */
>  static inline void mast_rebalance_prev(struct maple_subtree_state *mast)
>  {
> @@ -2358,9 +2356,9 @@ static inline unsigned char mas_mab_to_node(struct ma_state *mas,
>  /*
>   * mab_set_b_end() - Add entry to b_node at b_node->b_end and increment the end
>   * pointer.
> - * @b_node - the big node to add the entry
> - * @mas - the maple state to get the pivot (mas->max)
> - * @entry - the entry to add, if NULL nothing happens.
> + * @b_node: the big node to add the entry
> + * @mas: the maple state to get the pivot (mas->max)
> + * @entry: the entry to add, if NULL nothing happens.
>   */
>  static inline void mab_set_b_end(struct maple_big_node *b_node,
>  				 struct ma_state *mas,
> @@ -2379,11 +2377,11 @@ static inline void mab_set_b_end(struct maple_big_node *b_node,
>   * mas_set_split_parent() - combine_then_separate helper function.  Sets the parent
>   * of @mas->node to either @left or @right, depending on @slot and @split
>   *
> - * @mas - the maple state with the node that needs a parent
> - * @left - possible parent 1
> - * @right - possible parent 2
> - * @slot - the slot the mas->node was placed
> - * @split - the split location between @left and @right
> + * @mas: the maple state with the node that needs a parent
> + * @left: possible parent 1
> + * @right: possible parent 2
> + * @slot: the slot the mas->node was placed
> + * @split: the split location between @left and @right
>   */
>  static inline void mas_set_split_parent(struct ma_state *mas,
>  					struct maple_enode *left,
> @@ -2403,11 +2401,11 @@ static inline void mas_set_split_parent(struct ma_state *mas,
>  
>  /*
>   * mte_mid_split_check() - Check if the next node passes the mid-split
> - * @**l: Pointer to left encoded maple node.
> - * @**m: Pointer to middle encoded maple node.
> - * @**r: Pointer to right encoded maple node.
> + * @l: Pointer to left encoded maple node.
> + * @m: Pointer to middle encoded maple node.
> + * @r: Pointer to right encoded maple node.
>   * @slot: The offset
> - * @*split: The split location.
> + * @split: The split location.
>   * @mid_split: The middle split.
>   */
>  static inline void mte_mid_split_check(struct maple_enode **l,
> @@ -2431,10 +2429,10 @@ static inline void mte_mid_split_check(struct maple_enode **l,
>  /*
>   * mast_set_split_parents() - Helper function to set three nodes parents.  Slot
>   * is taken from @mast->l.
> - * @mast - the maple subtree state
> - * @left - the left node
> - * @right - the right node
> - * @split - the split location.
> + * @mast: the maple subtree state
> + * @left: the left node
> + * @right: the right node
> + * @split: the split location.
>   */
>  static inline void mast_set_split_parents(struct maple_subtree_state *mast,
>  					  struct maple_enode *left,
> @@ -2468,7 +2466,6 @@ static inline void mast_set_split_parents(struct maple_subtree_state *mast,
>  /*
>   * mas_topiary_node() - Dispose of a single node
>   * @mas: The maple state for pushing nodes
> - * @enode: The encoded maple node
>   * @in_rcu: If the tree is in rcu mode
>   *
>   * The node will either be RCU freed or pushed back on the maple state.
> @@ -2600,7 +2597,7 @@ static inline void mas_topiary_replace(struct ma_state *mas,
>  /*
>   * mas_wmb_replace() - Write memory barrier and replace
>   * @mas: The maple state
> - * @old: The old maple encoded node that is being replaced.
> + * @old_enode: The old maple encoded node that is being replaced.
>   *
>   * Updates gap as necessary.
>   */
> @@ -3491,10 +3488,7 @@ static inline void mas_store_root(struct ma_state *mas, void *entry)
>  /*
>   * mas_is_span_wr() - Check if the write needs to be treated as a write that
>   * spans the node.
> - * @mas: The maple state
> - * @piv: The pivot value being written
> - * @type: The maple node type
> - * @entry: The data to write
> + * @wr_mas: The maple write state
>   *
>   * Spanning writes are writes that start in one node and end in another OR if
>   * the write of a %NULL will cause the node to end with a %NULL.
> @@ -4159,10 +4153,7 @@ static inline void mas_wr_modify(struct ma_wr_state *wr_mas)
>  
>  /*
>   * mas_wr_store_entry() - Internal call to store a value
> - * @mas: The maple state
> - * @entry: The entry to store.
> - *
> - * Return: The contents that was stored at the index.
> + * @wr_mas: The maple write state
>   */
>  static inline void mas_wr_store_entry(struct ma_wr_state *wr_mas)
>  {
> @@ -4401,9 +4392,8 @@ static int mas_prev_node(struct ma_state *mas, unsigned long min)
>   * mas_prev_slot() - Get the entry in the previous slot
>   *
>   * @mas: The maple state
> - * @max: The minimum starting range
> + * @min: The minimum starting range
>   * @empty: Can be empty
> - * @set_underflow: Set the @mas->node to underflow state on limit.
>   *
>   * Return: The entry in the previous slot which is possibly NULL
>   */
> @@ -4486,6 +4476,7 @@ static void *mas_prev_slot(struct ma_state *mas, unsigned long min, bool empty)
>  /*
>   * mas_next_node() - Get the next node at the same level in the tree.
>   * @mas: The maple state
> + * @node: The maple node
>   * @max: The maximum pivot value to check.
>   *
>   * The next value will be mas->node[mas->offset] or the status will have
> @@ -4576,8 +4567,6 @@ static int mas_next_node(struct ma_state *mas, struct maple_node *node,
>   * @mas: The maple state
>   * @max: The maximum starting range
>   * @empty: Can be empty
> - * @set_overflow: Should @mas->node be set to overflow when the limit is
> - * reached.
>   *
>   * Return: The entry in the next slot which is possibly NULL
>   */
> @@ -5111,9 +5100,9 @@ EXPORT_SYMBOL_GPL(mas_empty_area_rev);
>  
>  /*
>   * mte_dead_leaves() - Mark all leaves of a node as dead.
> - * @mas: The maple state
> + * @enode: the encoded node
> + * @mt: the maple tree
>   * @slots: Pointer to the slot array
> - * @type: The maple node type
>   *
>   * Must hold the write lock.
>   *
> -- 
> 2.34.1
>