Re: [PATCH v3 03/15] interval-tree: Add a utility to iterate over spans in an interval tree

[Matthew Wilcox <willy@xxxxxxxxxxxxx>]

On Fri, Nov 04, 2022 at 04:38:19PM -0300, Jason Gunthorpe wrote:
> On Thu, Nov 03, 2022 at 05:31:17AM +0000, Tian, Kevin wrote:
> > > From: Jason Gunthorpe <jgg@xxxxxxxxxx>
> > > Sent: Wednesday, October 26, 2022 2:12 AM
> > > +/*
> > > + * This iterator travels over spans in an interval tree. It does not return
> > > + * nodes but classifies each span as either a hole, where no nodes intersect,
> > > or
> > > + * a used, which is fully covered by nodes. Each iteration step toggles
> > > between
> > > + * hole and used until the entire range is covered. The returned spans
> > > always
> > > + * fully cover the requested range.
> > > + *
> > > + * The iterator is greedy, it always returns the largest hole or used possible,
> > > + * consolidating all consecutive nodes.
> > > + *
> > > + * Only is_hole, start_hole/used and last_hole/used are part of the external
> > > + * interface.
> > 
> > slightly better readability if moving this sentence into the structure as
> > the break line
> 
> Do you mean like this?
> 
> @@ -37,13 +37,16 @@ interval_tree_iter_next(struct interval_tree_node *node,
>   * The iterator is greedy, it always returns the largest hole or used possible,
>   * consolidating all consecutive nodes.
> - *
> - * Only is_hole, start_hole/used and last_hole/used are part of the external
> - * interface.
>   */
>  struct interval_tree_span_iter {
>  	struct interval_tree_node *nodes[2];
>  	unsigned long first_index;
>  	unsigned long last_index;
> +
> +	/*
> +	 * Only is_hole, start_hole/used and last_hole/used are part of the
> +	 * external interface.
> +	 */
>  	union {
>  		unsigned long start_hole;
>  		unsigned long start_used;

Or you could kernel-doc it ...

/**
 * struct interval_tree_span_iter - Find used and unused spans.
 * @start_hole: ...
 * @start_used: ...
 ...
 *
 * This iterator travels over spans in an interval tree. It does not return
 * nodes but classifies each span as either a hole, where no nodes intersect,
 * or as used, which is fully covered by nodes. Each iteration step
 * alternates between hole and used until the entire range is covered. The
 * returned spans always fully cover the requested range.
 *
 * The iterator is greedy, it always returns the largest span possible,
 * consolidating all consecutive nodes.
 */
struct interval_tree_span_iter {
	/* private: not for use by the caller */
 	struct interval_tree_node *nodes[2];
 	unsigned long first_index;
 	unsigned long last_index;
	/* public: */
	union {
		unsigned long start_hole;
		unsigned long start_used;
...
};