Re: [PATCH] fiemap: use kernel-doc includes in fiemap docbook

[Matthew Wilcox <willy@infradead.org>]

On Tue, Nov 19, 2024 at 10:55:07AM -0800, Randy Dunlap wrote:
> Add some kernel-doc notation to structs in fiemap header files
> then pull that into Documentation/filesystems/fiemap.rst
> instead of duplicating the header file structs in fiemap.rst.
> This helps to future-proof fiemap.rst against struct changes.

Thanks!  This is great.  Feels free to ignore every suggestion I'm about
to make.

> +/**
> + * struct fiemap_extent - description of one fiemap extent
> + * @fe_logical: logical offset in bytes for the start of the extent
> + *	from the beginning of the file

 * @fe_logical: Byte offset of extent in the file.

> + * @fe_physical: physical offset in bytes for the start of the extent
> + *	from the beginning of the disk

 * @fe_physical: Byte offset of extent on disk.

> +/**
> + * struct fiemap - file extent mappings
> + * @fm_start: logical offset (inclusive) at
> + *	which to start mapping (in)

Do we want to say "Byte offset"?

>  
> +/* flags used in fm_flags: */
>  #define FIEMAP_FLAG_SYNC	0x00000001 /* sync file data before map */
>  #define FIEMAP_FLAG_XATTR	0x00000002 /* map extended attribute tree */
>  #define FIEMAP_FLAG_CACHE	0x00000004 /* request caching of the extents */
>  
>  #define FIEMAP_FLAGS_COMPAT	(FIEMAP_FLAG_SYNC | FIEMAP_FLAG_XATTR)

Do we want to turn this into an enum so it can be kernel-doc?

> +/* flags used in fe_flags: */
>  #define FIEMAP_EXTENT_LAST		0x00000001 /* Last extent in file. */
>  #define FIEMAP_EXTENT_UNKNOWN		0x00000002 /* Data location unknown. */
>  #define FIEMAP_EXTENT_DELALLOC		0x00000004 /* Location still pending.

Likewise