| Message ID | 20240830025648.22224-1-richard.weiyang@gmail.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | [v2] maple_tree: cleanup interface descriptions | expand |
* Wei Yang <richard.weiyang@gmail.com> [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@gmail.com> > --- > 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? > --- > 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 >
* Liam R. Howlett <Liam.Howlett@oracle.com> [240830 00:12]: > * Wei Yang <richard.weiyang@gmail.com> [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@gmail.com> > > --- > > 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@lists.infradead.org > https://lists.infradead.org/mailman/listinfo/maple-tree
On Fri, Aug 30, 2024 at 12:12:14AM -0400, Liam R. Howlett wrote: >* Wei Yang <richard.weiyang@gmail.com> [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? This tries to comply with kernel doc format. If you prefix a '*' in kenrel doc, ./scripts/kernel-doc would report a warning. > >> >> 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> >> --- >> 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 for the un-precise change log. s/interface/function/ looks good?
* Wei Yang <richard.weiyang@gmail.com> [240830 04:47]: > On Fri, Aug 30, 2024 at 12:12:14AM -0400, Liam R. Howlett wrote: > >* Wei Yang <richard.weiyang@gmail.com> [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? > > This tries to comply with kernel doc format. > > If you prefix a '*' in kenrel doc, ./scripts/kernel-doc would report a > warning. Thanks. I wanted those so that it was overly obvious when they were used wrong but I guess they have to go. > > > > >> > >> 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> > >> --- > >> 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 for the un-precise change log. > > s/interface/function/ looks good? Yes. Thanks, Liam
On Fri, Aug 30, 2024 at 09:30:37AM -0400, Liam R. Howlett wrote: >* Wei Yang <richard.weiyang@gmail.com> [240830 04:47]: >> On Fri, Aug 30, 2024 at 12:12:14AM -0400, Liam R. Howlett wrote: >> >* Wei Yang <richard.weiyang@gmail.com> [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? >> >> This tries to comply with kernel doc format. >> >> If you prefix a '*' in kenrel doc, ./scripts/kernel-doc would report a >> warning. > >Thanks. I wanted those so that it was overly obvious when they were >used wrong but I guess they have to go. > Not fully get your point. You are fine to keep this change, or prefer me to drop it in next version?
* Wei Yang <richard.weiyang@gmail.com> [240830 10:36]: > On Fri, Aug 30, 2024 at 09:30:37AM -0400, Liam R. Howlett wrote: > >* Wei Yang <richard.weiyang@gmail.com> [240830 04:47]: > >> On Fri, Aug 30, 2024 at 12:12:14AM -0400, Liam R. Howlett wrote: > >> >* Wei Yang <richard.weiyang@gmail.com> [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? > >> > >> This tries to comply with kernel doc format. > >> > >> If you prefix a '*' in kenrel doc, ./scripts/kernel-doc would report a > >> warning. > > > >Thanks. I wanted those so that it was overly obvious when they were > >used wrong but I guess they have to go. > > > > Not fully get your point. > > You are fine to keep this change, or prefer me to drop it in next version? I am fine with the changes. Apologies for not being clear. Thanks, Liam
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. *
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 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> --- v2: * not change them to kernel doc since they are internal interface --- lib/maple_tree.c | 105 +++++++++++++++++++++-------------------------- 1 file changed, 47 insertions(+), 58 deletions(-)