* Liam R. Howlett <Liam.Howlett@xxxxxxxxxx> [240830 00:12]:
> * Wei Yang <richard.weiyang@xxxxxxxxx> [240829 22:57]:
> > This patch tries to cleanup some interface description:
> >
> > * function name mismatch
> > * parameter name mismatch
> > * parameter all end up with ':'
> > * not prefix '*' if parameter is a pointer
>
> Why not use * if the 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@xxxxxxxxx>
> > ---
> > v2:
> > * not change them to kernel doc since they are internal interface
>
> Thanks, since they are not internal interfaces, could you also change
> the patch description to state that?
Sorry, the description says "interface description" but these are
inline functions; so not an interface.
>
> > ---
> > 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 43e184f91461..a2367564f627 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.
> > */
> > @@ -1462,7 +1461,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.
> > */
> > @@ -1544,7 +1543,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.
> > *
> > @@ -1648,7 +1647,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)
> > {
> > @@ -1664,8 +1663,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)
> > @@ -1687,8 +1686,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)
> > @@ -1716,8 +1715,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)
> > @@ -1782,7 +1781,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.
> > *
> > @@ -1830,6 +1828,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.
> > *
> > @@ -2156,7 +2155,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.
> > @@ -2207,7 +2207,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)
> > {
> > @@ -2221,7 +2220,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)
> > {
> > @@ -2372,9 +2370,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,
> > @@ -2393,11 +2391,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,
> > @@ -2417,11 +2415,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,
> > @@ -2445,10 +2443,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,
> > @@ -2482,7 +2480,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.
> > @@ -2614,7 +2611,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.
> > */
> > @@ -3505,10 +3502,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.
> > @@ -4173,10 +4167,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)
> > {
> > @@ -4415,9 +4406,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
> > */
> > @@ -4500,6 +4490,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
> > @@ -4590,8 +4581,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
> > */
> > @@ -5125,9 +5114,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
> >
>
> --
> maple-tree mailing list
> maple-tree@xxxxxxxxxxxxxxxxxxx
> https://lists.infradead.org/mailman/listinfo/maple-tree
