[Concept,5/6] fat: Convert fat.h to kernel-doc style

  From: Simon Glass <simon.glass@canonical.com>

Add kernel-doc comments to structs and public functions in fat.h so that
it is easier to understand the code.

Co-developed-by: Claude <noreply@anthropic.com>
Signed-off-by: Simon Glass <simon.glass@canonical.com>
---

 include/fat.h | 349 ++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 284 insertions(+), 65 deletions(-)
  

On 11/13/25 03:56, Simon Glass wrote:
> From: Simon Glass <simon.glass@canonical.com>
> 
> Add kernel-doc comments to structs and public functions in fat.h so that
> it is easier to understand the code.
> 
> Co-developed-by: Claude <noreply@anthropic.com>
> Signed-off-by: Simon Glass <simon.glass@canonical.com>
> ---
> 
>   include/fat.h | 349 ++++++++++++++++++++++++++++++++++++++++----------
>   1 file changed, 284 insertions(+), 65 deletions(-)
> 
> diff --git a/include/fat.h b/include/fat.h
> index 50b528d3cb7..c44f23b0013 100644
> --- a/include/fat.h
> +++ b/include/fat.h
> @@ -84,129 +84,348 @@ struct disk_partition;
>   					((fatsize) != 16 ? 0xff0 : 0xfff0) : \
>   					0xffffff0))
>   
> +/**
> + * struct boot_sector - FAT boot sector structure
> + * @ignored: bootstrap code (first 3 bytes)
> + * @system_id: name of filesystem (8 bytes)
> + * @sector_size: bytes per sector
> + * @cluster_size: sectors per cluster
> + * @reserved: number of reserved sectors
> + * @fats: number of FAT copies
> + * @dir_entries: number of root directory entries
> + * @sectors: number of sectors (for small disks)
> + * @media: media descriptor code
> + * @fat_length: sectors per FAT (for FAT12/16)
> + * @secs_track: sectors per track
> + * @heads: number of heads
> + * @hidden: number of hidden sectors
> + * @total_sect: total number of sectors (for larger disks)
> + * @fat32_length: sectors per FAT (FAT32 only)
> + * @flags: flags (bit 8: fat mirroring, low 4: active fat)
> + * @version: filesystem version (FAT32 only)
> + * @root_cluster: first cluster of root directory (FAT32 only)
> + * @info_sector: filesystem info sector (FAT32 only)
> + * @backup_boot: backup boot sector location (FAT32 only)
> + * @reserved2: unused (FAT32 only)
> + */
>   struct boot_sector {
> -	__u8	ignored[3];	/* Bootstrap code */
> -	char	system_id[8];	/* Name of fs */
> -	__u8	sector_size[2];	/* Bytes/sector */
> -	__u8	cluster_size;	/* Sectors/cluster */
> -	__u16	reserved;	/* Number of reserved sectors */
> -	__u8	fats;		/* Number of FATs */
> -	__u8	dir_entries[2];	/* Number of root directory entries */
> -	__u8	sectors[2];	/* Number of sectors */
> -	__u8	media;		/* Media code */
> -	__u16	fat_length;	/* Sectors/FAT */
> -	__u16	secs_track;	/* Sectors/track */
> -	__u16	heads;		/* Number of heads */
> -	__u32	hidden;		/* Number of hidden sectors */
> -	__u32	total_sect;	/* Number of sectors (if sectors == 0) */
> +	__u8	ignored[3];
> +	char	system_id[8];
> +	__u8	sector_size[2];
> +	__u8	cluster_size;
> +	__u16	reserved;
> +	__u8	fats;
> +	__u8	dir_entries[2];
> +	__u8	sectors[2];
> +	__u8	media;
> +	__u16	fat_length;
> +	__u16	secs_track;
> +	__u16	heads;
> +	__u32	hidden;
> +	__u32	total_sect;
>   
>   	/* FAT32 only */
> -	__u32	fat32_length;	/* Sectors/FAT */
> -	__u16	flags;		/* Bit 8: fat mirroring, low 4: active fat */
> -	__u8	version[2];	/* Filesystem version */
> -	__u32	root_cluster;	/* First cluster in root directory */
> -	__u16	info_sector;	/* Filesystem info sector */
> -	__u16	backup_boot;	/* Backup boot sector */
> -	__u16	reserved2[6];	/* Unused */
> +	__u32	fat32_length;
> +	__u16	flags;
> +	__u8	version[2];
> +	__u32	root_cluster;
> +	__u16	info_sector;
> +	__u16	backup_boot;
> +	__u16	reserved2[6];
>   };
>   
> +/**
> + * struct volume_info - FAT volume information structure
> + * @drive_number: BIOS drive number
> + * @reserved: unused field
> + * @ext_boot_sign: extended boot signature (0x29 if fields below exist)
> + * @volume_id: volume serial number (4 bytes)
> + * @volume_label: volume label (11 bytes, padded with spaces)
> + * @fs_type: filesystem type string (typically "FAT12", "FAT16", or "FAT32")
> + *
> + * This structure is part of the boot sector, located after the common fields.
> + * Boot code follows this structure, with boot signature at the end of sector.
> + */
>   struct volume_info {
> -	__u8 drive_number;	/* BIOS drive number */
> -	__u8 reserved;		/* Unused */
> -	__u8 ext_boot_sign;	/* 0x29 if fields below exist (DOS 3.3+) */
> -	__u8 volume_id[4];	/* Volume ID number */
> -	char volume_label[11];	/* Volume label */
> -	char fs_type[8];	/* Typically FAT12, FAT16, or FAT32 */
> -	/* Boot code comes next, all but 2 bytes to fill up sector */
> -	/* Boot sign comes last, 2 bytes */
> +	__u8 drive_number;
> +	__u8 reserved;
> +	__u8 ext_boot_sign;
> +	__u8 volume_id[4];
> +	char volume_label[11];
> +	char fs_type[8];
>   };
>   
>   /* see dir_entry::lcase: */
>   #define CASE_LOWER_BASE	8	/* base (name) is lower case */
>   #define CASE_LOWER_EXT	16	/* extension is lower case */
>   
> +/**
> + * struct nameext - 8.3 filename components
> + * @name: filename (8 bytes)
> + * @ext: extension (3 bytes)
> + */
>   struct nameext {
>   	char name[8];
>   	char ext[3];
>   };
>   
> +/**
> + * struct dir_entry - FAT directory entry
> + * @nameext: filename and extension (8.3 format)
> + * @attr: file attributes (ATTR_* flags)
> + * @lcase: case flags for name and extension (CASE_LOWER_* flags)
> + * @ctime_ms: creation time (milliseconds)
> + * @ctime: creation time (hours, minutes, seconds)
> + * @cdate: creation date
> + * @adate: last access date
> + * @starthi: high 16 bits of cluster number (FAT32 only)
> + * @time: modification time
> + * @date: modification date
> + * @start: low 16 bits of cluster number
> + * @size: file size in bytes
> + */
>   struct dir_entry {
> -	struct nameext nameext;	/* Name and extension */
> -	__u8	attr;		/* Attribute bits */
> -	__u8	lcase;		/* Case for name and ext (CASE_LOWER_x) */
> -	__u8	ctime_ms;	/* Creation time, milliseconds */
> -	__u16	ctime;		/* Creation time */
> -	__u16	cdate;		/* Creation date */
> -	__u16	adate;		/* Last access date */
> -	__u16	starthi;	/* High 16 bits of cluster in FAT32 */
> -	__u16	time,date,start;/* Time, date and first cluster */
> -	__u32	size;		/* File size in bytes */
> +	struct nameext nameext;
> +	__u8	attr;
> +	__u8	lcase;
> +	__u8	ctime_ms;
> +	__u16	ctime;
> +	__u16	cdate;
> +	__u16	adate;
> +	__u16	starthi;
> +	__u16	time

Missing semicolon.

> +	__u16	date;
> +	__u16	start;
> +	__u32	size;
>   };
>   
> +/**
> + * struct dir_slot - VFAT long filename entry
> + * @id: sequence number (bit 6 = last entry, bits 0-4 = sequence)
> + * @name0_4: characters 0-4 of long filename (UTF-16LE)
> + * @attr: must be ATTR_VFAT (0x0F)
> + * @reserved: unused field
> + * @alias_checksum: checksum of 8.3 alias for this long name
> + * @name5_10: characters 5-10 of long filename (UTF-16LE)
> + * @start: unused (always 0)
> + * @name11_12: characters 11-12 of long filename (UTF-16LE)
> + *
> + * Long filename entries precede the corresponding short entry in directory.
> + * Multiple entries may be used to store names longer than 13 characters.
> + */
>   struct dir_slot {
> -	__u8	id;		/* Sequence number for slot */
> -	__u8	name0_4[10];	/* First 5 characters in name */
> -	__u8	attr;		/* Attribute byte */
> -	__u8	reserved;	/* Unused */
> -	__u8	alias_checksum;/* Checksum for 8.3 alias */
> -	__u8	name5_10[12];	/* 6 more characters in name */
> -	__u16	start;		/* Unused */
> -	__u8	name11_12[4];	/* Last 2 characters in name */
> +	__u8	id;
> +	__u8	name0_4[10];
> +	__u8	attr;
> +	__u8	reserved;
> +	__u8	alias_checksum;
> +	__u8	name5_10[12];
> +	__u16	start;
> +	__u8	name11_12[4];
>   };
>   
> -/*
> - * Private filesystem parameters
> +/**
> + * struct fsdata - FAT filesystem instance data
> + * @fatbuf: buffer for reading/writing FAT (must be 32-bit aligned for FAT32)
> + * @fatsize: size of FAT in bits (12, 16, or 32)
> + * @fatlength: length of FAT in sectors
> + * @fat_sect: starting sector of the FAT
> + * @fat_dirty: flag indicating if fatbuf has been modified
> + * @rootdir_sect: starting sector of root directory
> + * @sect_size: size of sectors in bytes
> + * @clust_size: size of clusters in sectors
> + * @data_begin: sector offset of first data cluster (can be negative)
> + * @fatbufnum: currently buffered FAT sector number (init to -1)
> + * @rootdir_size: size of root directory in entries (for non-FAT32)
> + * @root_cluster: first cluster of root directory (FAT32 only)
> + * @total_sect: total number of sectors
> + * @fats: number of FAT copies
>    *
> - * Note: FAT buffer has to be 32 bit aligned
> - * (see FAT32 accesses)
> + * This structure holds the runtime state of a mounted FAT filesystem.
> + * The fatbuf must be 32-bit aligned due to FAT32 sector access requirements.
>    */
>   struct fsdata {
> -	__u8	*fatbuf;	/* Current FAT buffer */
> -	int	fatsize;	/* Size of FAT in bits */
> -	__u32	fatlength;	/* Length of FAT in sectors */
> -	__u16	fat_sect;	/* Starting sector of the FAT */
> -	__u8	fat_dirty;      /* Set if fatbuf has been modified */
> -	__u32	rootdir_sect;	/* Start sector of root directory */
> -	__u16	sect_size;	/* Size of sectors in bytes */
> -	__u16	clust_size;	/* Size of clusters in sectors */
> -	int	data_begin;	/* The sector of the first cluster, can be negative */
> -	int	fatbufnum;	/* Used by get_fatent, init to -1 */
> -	int	rootdir_size;	/* Size of root dir for non-FAT32 */
> -	__u32	root_cluster;	/* First cluster of root dir for FAT32 */
> -	u32	total_sect;	/* Number of sectors */
> -	int	fats;		/* Number of FATs */
> +	__u8	*fatbuf;
> +	int	fatsize;
> +	__u32	fatlength;
> +	__u16	fat_sect;
> +	__u8	fat_dirty;
> +	__u32	rootdir_sect;
> +	__u16	sect_size;
> +	__u16	clust_size;
> +	int	data_begin;
> +	int	fatbufnum;
> +	int	rootdir_size;
> +	__u32	root_cluster;
> +	u32	total_sect;
> +	int	fats;
>   };
>   
>   struct fat_itr;
>   
> +/**
> + * clust_to_sect() - convert cluster number to sector number
> + * @fsdata: filesystem instance data
> + * @clust: cluster number
> + *
> + * Return: sector number corresponding to the given cluster
> + */
>   static inline u32 clust_to_sect(struct fsdata *fsdata, u32 clust)
>   {
>   	return fsdata->data_begin + clust * fsdata->clust_size;
>   }
>   
> +/**
> + * sect_to_clust() - convert sector number to cluster number
> + * @fsdata: filesystem instance data
> + * @sect: sector number
> + *
> + * Return: cluster number corresponding to the given sector
> + */
>   static inline u32 sect_to_clust(struct fsdata *fsdata, int sect)
>   {
>   	return (sect - fsdata->data_begin) / fsdata->clust_size;
>   }
>   
> +/**
> + * file_fat_detectfs() - detect and initialize the FAT filesystem
> + *
> + * Return: 0 on success, -1 on error
> + */
>   int file_fat_detectfs(void);
> +
> +/**
> + * fat_exists() - check if a file exists
> + * @filename: full path to file
> + *
> + * Return: 0 if file exists, -1 if not found or error
> + */
>   int fat_exists(const char *filename);
> +
> +/**
> + * fat_size() - get the size of a file
> + * @filename: full path to file
> + * @size: pointer to store file size
> + *
> + * Return: 0 on success, -1 on error
> + */
>   int fat_size(const char *filename, loff_t *size);
> +
> +/**
> + * file_fat_read() - read a file from FAT filesystem
> + * @filename: full path to file
> + * @buffer: buffer to read data into
> + * @maxsize: maximum number of bytes to read
> + *
> + * Return: number of bytes read, -1 on error
> + */
>   int file_fat_read(const char *filename, void *buffer, int maxsize);
> +
> +/**
> + * fat_set_blk_dev() - set the block device and partition for FAT operations
> + * @rbdd: block device descriptor
> + * @info: partition information
> + *
> + * Return: 0 on success, -1 on error
> + */
>   int fat_set_blk_dev(struct blk_desc *rbdd, struct disk_partition *info);
> +
> +/**
> + * fat_register_device() - register a FAT filesystem on a block device
> + * @dev_desc: block device descriptor
> + * @part_no: partition number (0 = whole device)
> + *
> + * Return: 0 on success, -1 on error
> + */
>   int fat_register_device(struct blk_desc *dev_desc, int part_no);
>   
> +/**
> + * file_fat_write() - write to a file on FAT filesystem
> + * @filename: full path to file
> + * @buf: buffer containing data to write
> + * @offset: offset in file to start writing
> + * @len: number of bytes to write
> + * @actwrite: pointer to store actual number of bytes written
> + *
> + * Return: 0 on success, -1 on error
> + */
>   int file_fat_write(const char *filename, void *buf, loff_t offset, loff_t len,
>   		   loff_t *actwrite);
> +
> +/**
> + * fat_read_file() - read from a file on FAT filesystem
> + * @filename: full path to file
> + * @buf: buffer to read data into
> + * @offset: offset in file to start reading
> + * @len: number of bytes to read
> + * @actread: pointer to store actual number of bytes read
> + *
> + * Return: 0 on success, -1 on error
> + */
>   int fat_read_file(const char *filename, void *buf, loff_t offset, loff_t len,
>   		  loff_t *actread);
> +
> +/**
> + * fat_opendir() - open a directory for reading
> + * @filename: full path to directory
> + * @dirsp: pointer to store directory stream handle
> + *
> + * Return: 0 on success, -1 on error
> + */
>   int fat_opendir(const char *filename, struct fs_dir_stream **dirsp);
> +
> +/**
> + * fat_readdir() - read next entry from directory
> + * @dirs: directory stream handle
> + * @dentp: pointer to store directory entry
> + *
> + * Return: 0 on success, -1 on error or end of directory
> + */
>   int fat_readdir(struct fs_dir_stream *dirs, struct fs_dirent **dentp);
> +
> +/**
> + * fat_closedir() - close a directory stream
> + * @dirs: directory stream handle
> + */
>   void fat_closedir(struct fs_dir_stream *dirs);
> +
> +/**
> + * fat_unlink() - delete a file or empty directory
> + * @filename: full path to file or directory
> + *
> + * Return: 0 on success, -1 on error
> + */
>   int fat_unlink(const char *filename);
> +
> +/**
> + * fat_rename() - rename a file or directory
> + * @old_path: current full path
> + * @new_path: new full path
> + *
> + * Return: 0 on success, -1 on error
> + */
>   int fat_rename(const char *old_path, const char *new_path);
> +
> +/**
> + * fat_mkdir() - create a directory
> + * @dirname: full path to new directory
> + *
> + * Return: 0 on success, -1 on error
> + */
>   int fat_mkdir(const char *dirname);
> +
> +/**
> + * fat_close() - close FAT filesystem and release resources
> + */
>   void fat_close(void);
> +
> +/**
> + * fat_next_cluster() - get the next cluster in a chain
> + * @itr: directory iterator
> + * @nbytes: pointer to store number of bytes in cluster
> + *
> + * Return: pointer to cluster data buffer
> + */
>   void *fat_next_cluster(struct fat_itr *itr, unsigned int *nbytes);
>   
>   /**