Re: [PATCH 1/2] Documentation: iomap: Add missing flags description

["Darrick J. Wong" <djwong@kernel.org>]

On Mon, Apr 07, 2025 at 01:50:00AM -0700, Christoph Hellwig wrote:
> On Fri, Apr 04, 2025 at 10:36:32AM +0100, John Garry wrote:
> > > @@ -243,6 +243,11 @@ The fields are as follows:
> > >        regular file data.
> > >        This is only useful for FIEMAP.
> > > +   * **IOMAP_F_BOUNDARY**: This indicates that I/O and I/O completions
> > > +     for this iomap must never be merged with the mapping before it.
> > 
> > This is just effectively the same comment as in the code - what's the use in
> > this?
> 
> Darrick asked for this file to have full comments.  I'm more on your
> side here as a lot of this seem redundant.

Yes, some of it duplicates iomap.h's more terse comments.  I'm willing
to be flexible about some of this, so long as the documentation helps
the /next/ person to understand iomap and how to use it.

> > > +     Currently XFS uses this to prevent merging of ioends across RTG
> > > +     (realtime group) boundaries.
> > > +
> > >      * **IOMAP_F_PRIVATE**: Starting with this value, the upper bits can
> > >        be set by the filesystem for its own purposes.
> > 
> > Is this comment now out of date according to your change in 923936efeb74?
> 
> Also we probably should not detail file system behavior here, but a
> high level description of what it is useful.

Agreed (now).

--D