Documentation improvements (#65)

Co-authored-by: Richard Huveneers <richard@huveneers.com>

include/ext4.h

@@ -146,7 +146,7 @@ int ext4_mount(const char *dev_name,
 
 /**@brief   Umount operation.
  *
- * @param   mount_pount Mount point.
+ * @param   mount_point Mount point.
  *
  * @return  Standard error code */
 int ext4_umount(const char *mount_point);
@@ -161,7 +161,7 @@ int ext4_umount(const char *mount_point);
  *
  *              ext4_journal_stop("/");
  *              ext4_umount("/");
- * @param   mount_pount Mount point.
+ * @param   mount_point Mount point.
  *
  * @return  Standard error code. */
 int ext4_journal_start(const char *mount_point);
@@ -169,7 +169,7 @@ int ext4_journal_start(const char *mount_point);
 /**@brief   Stops journaling. Journaling start/stop functions are transparent
  *          and might be used on filesystems without journaling support.
  *
- * @param   mount_pount Mount point name.
+ * @param   mount_point Mount point name.
  *
  * @return  Standard error code. */
 int ext4_journal_stop(const char *mount_point);
@@ -177,7 +177,7 @@ int ext4_journal_stop(const char *mount_point);
 /**@brief   Journal recovery.
  * @warning Must be called after @ref ext4_mount.
  *
- * @param   mount_pount Mount point.
+ * @param   mount_point Mount point.
  *
  * @return Standard error code. */
 int ext4_recover(const char *mount_point);
@@ -199,7 +199,7 @@ struct ext4_mount_stats {
 
 /**@brief   Get file mount point stats.
  *
- * @param   mount_pount Mount point.
+ * @param   mount_point Mount point.
  * @param   stats Filesystem stats.
  *
  * @return Standard error code. */
@@ -208,7 +208,7 @@ int ext4_mount_point_stats(const char *mount_point,
 
 /**@brief   Setup OS lock routines.
  *
- * @param   mount_pount Mount point.
+ * @param   mount_point Mount point.
  * @param   locks  Lock and unlock functions
  *
  * @return Standard error code. */
@@ -217,7 +217,7 @@ int ext4_mount_setup_locks(const char *mount_point,
 
 /**@brief   Acquire the filesystem superblock pointer of a mp.
  *
- * @param   mount_pount Mount point.
+ * @param   mount_point Mount point.
  * @param   sb Superblock handle
  *
  * @return Standard error code. */
@@ -254,7 +254,7 @@ int ext4_get_sblock(const char *mount_point, struct ext4_sblock **sb);
  * Write back mode is useful when you want to create a lot of empty
  * files/directories.
  *
- * @param   mount_pount Mount point.
+ * @param   path Mount point.
  * @param   on Enable/disable cache writeback mode.
  *
  * @return Standard error code. */
@@ -263,7 +263,7 @@ int ext4_cache_write_back(const char *path, bool on);
 
 /**@brief   Force cache flush.
  *
- * @param   mount_pount Mount point.
+ * @param   path Mount point.
  *
  * @return  Standard error code. */
 int ext4_cache_flush(const char *path);
@@ -538,8 +538,8 @@ int ext4_setxattr(const char *path, const char *name, size_t name_len,
  * @param path      Path to file/directory.
  * @param name      Name of the entry to get.
  * @param name_len  Length of @name in bytes.
- * @param data      Data of the entry to get.
- * @param data_size Size of data to get.
+ * @param buf      Data of the entry to get.
+ * @param buf_size Size of data to get.
  *
  * @return  Standard error code.*/
 int ext4_getxattr(const char *path, const char *name, size_t name_len,

include/ext4_balloc.h

@@ -54,7 +54,7 @@ extern "C" {
 #include <stdbool.h>
 
 /**@brief Compute number of block group from block address.
- * @param sb superblock pointer.
+ * @param s superblock pointer.
  * @param baddr Absolute address of block.
  * @return Block group index
  */
@@ -62,7 +62,7 @@ uint32_t ext4_balloc_get_bgid_of_block(struct ext4_sblock *s,
 				       ext4_fsblk_t baddr);
 
 /**@brief Compute the starting block address of a block group
- * @param sb   superblock pointer.
+ * @param s   superblock pointer.
  * @param bgid block group index
  * @return Block address
  */
@@ -95,7 +95,6 @@ int ext4_balloc_free_blocks(struct ext4_inode_ref *inode_ref,
 
 /**@brief   Allocate block procedure.
  * @param   inode_ref inode reference
- * @param   goal
  * @param   baddr allocated block address
  * @return  standard error code*/
 int ext4_balloc_alloc_block(struct ext4_inode_ref *inode_ref,

include/ext4_bcache.h

@@ -248,8 +248,7 @@ void ext4_bcache_invalidate_buf(struct ext4_bcache *bc,
 /**@brief   Invalidate a range of buffers.
  * @param   bc block cache descriptor
  * @param   from starting lba
- * @param   cnt block counts
- * @param   buf buffer*/
+ * @param   cnt block counts*/
 void ext4_bcache_invalidate_lba(struct ext4_bcache *bc,
 				uint64_t from,
 				uint32_t cnt);

include/ext4_block_group.h

@@ -73,7 +73,6 @@ static inline uint64_t ext4_bg_get_block_bitmap(struct ext4_bgroup *bg,
  * @param bg pointer to block group
  * @param s pointer to superblock
  * @param blk block to set
- * @return Address of block with block bitmap
  */
 static inline void ext4_bg_set_block_bitmap(struct ext4_bgroup *bg,
 					    struct ext4_sblock *s, uint64_t blk)
@@ -106,7 +105,6 @@ static inline uint64_t ext4_bg_get_inode_bitmap(struct ext4_bgroup *bg,
  * @param bg Pointer to block group
  * @param s Pointer to superblock
  * @param blk block to set
- * @return Address of block with i-node bitmap
  */
 static inline void ext4_bg_set_inode_bitmap(struct ext4_bgroup *bg,
 					    struct ext4_sblock *s, uint64_t blk)
@@ -139,7 +137,6 @@ ext4_bg_get_inode_table_first_block(struct ext4_bgroup *bg,
  * @param bg Pointer to block group
  * @param s Pointer to superblock
  * @param blk block to set
- * @return Address of first block of i-node table
  */
 static inline void
 ext4_bg_set_inode_table_first_block(struct ext4_bgroup *bg,
@@ -152,7 +149,7 @@ ext4_bg_set_inode_table_first_block(struct ext4_bgroup *bg,
 
 /**@brief Get number of free blocks in block group.
  * @param bg Pointer to block group
- * @param sb Pointer to superblock
+ * @param s Pointer to superblock
  * @return Number of free blocks in block group
  */
 static inline uint32_t ext4_bg_get_free_blocks_count(struct ext4_bgroup *bg,
@@ -282,7 +279,7 @@ static inline void ext4_bg_set_checksum(struct ext4_bgroup *bg, uint16_t crc)
 
 /**@brief Check if block group has a flag.
  * @param bg Pointer to block group
- * @param flag Flag to be checked
+ * @param f Flag to be checked
  * @return True if flag is set to 1
  */
 static inline bool ext4_bg_has_flag(struct ext4_bgroup *bg, uint32_t f)
@@ -292,7 +289,7 @@ static inline bool ext4_bg_has_flag(struct ext4_bgroup *bg, uint32_t f)
 
 /**@brief Set flag of block group.
  * @param bg Pointer to block group
- * @param flag Flag to be set
+ * @param f Flag to be set
  */
 static inline void ext4_bg_set_flag(struct ext4_bgroup *bg, uint32_t f)
 {
@@ -303,7 +300,7 @@ static inline void ext4_bg_set_flag(struct ext4_bgroup *bg, uint32_t f)
 
 /**@brief Clear flag of block group.
  * @param bg Pointer to block group
- * @param flag Flag to be cleared
+ * @param f Flag to be cleared
  */
 static inline void ext4_bg_clear_flag(struct ext4_bgroup *bg, uint32_t f)
 {

include/ext4_blockdev.h

@@ -153,8 +153,6 @@ struct ext4_blockdev {
 	}
 
 /**@brief   Block device initialization.
- * @param   bdev block device descriptor
- * @param   bg_bsize logical block size
  * @param   bdev block device descriptor
  * @return  standard error code*/
 int ext4_block_init(struct ext4_blockdev *bdev);
@@ -185,8 +183,7 @@ int ext4_block_flush_lba(struct ext4_blockdev *bdev, uint64_t lba);
 
 /**@brief   Set logical block size in block device.
  * @param   bdev block device descriptor
- * @param   lb_size logical block size (in bytes)
- * @return  standard error code*/
+ * @param   lb_bsize logical block size (in bytes)*/
 void ext4_block_set_lb_size(struct ext4_blockdev *bdev, uint32_t lb_bsize);
 
 /**@brief   Block get function (through cache, don't read).

include/ext4_crc32.h

@@ -57,7 +57,7 @@ uint32_t ext4_crc32(uint32_t crc, const void *buf, uint32_t size);
 /**@brief	CRC32C algorithm.
  * @param	crc input feed
  * @param 	buf input buffer
- * @param	length input buffer length (bytes)
+ * @param	size input buffer length (bytes)
  * @return	updated crc32c value*/
 uint32_t ext4_crc32c(uint32_t crc, const void *buf, uint32_t size);
 

include/ext4_debug.h

@@ -130,11 +130,11 @@ static inline const char *ext4_dmask_id2str(uint32_t m)
 #define DBG_ERROR "[error] "
 
 /**@brief   Global mask debug set.
- * @brief   m new debug mask.*/
+ * @param   m new debug mask.*/
 void ext4_dmask_set(uint32_t m);
 
 /**@brief   Global mask debug clear.
- * @brief   m new debug mask.*/
+ * @param   m new debug mask.*/
 void ext4_dmask_clr(uint32_t m);
 
 /**@brief   Global debug mask get.

include/ext4_dir.h

@@ -108,7 +108,7 @@ static inline uint16_t ext4_dir_en_get_entry_len(struct ext4_dir_en *de)
 
 /**@brief Set directory entry length.
  * @param de     Directory entry
- * @param length Entry length
+ * @param l Entry length
  */
 static inline void ext4_dir_en_set_entry_len(struct ext4_dir_en *de, uint16_t l)
 {
@@ -135,7 +135,7 @@ static inline uint16_t ext4_dir_en_get_name_len(struct ext4_sblock *sb,
 /**@brief Set directory entry name length.
  * @param sb     Superblock
  * @param de     Directory entry
- * @param length Entry name length
+ * @param len Entry name length
  */
 static inline void ext4_dir_en_set_name_len(struct ext4_sblock *sb,
 					    struct ext4_dir_en *de,
@@ -165,7 +165,7 @@ static inline uint8_t ext4_dir_en_get_inode_type(struct ext4_sblock *sb,
 /**@brief Set i-node type of directory entry.
  * @param sb   Superblock
  * @param de   Directory entry
- * @param type I-node type (file, dir, etc.)
+ * @param t I-node type (file, dir, etc.)
  */
 
 static inline void ext4_dir_en_set_inode_type(struct ext4_sblock *sb,

include/ext4_dir_idx.h

@@ -66,7 +66,7 @@ struct ext4_dir_idx_block {
 
 /**@brief Initialize index structure of new directory.
  * @param dir Pointer to directory i-node
- * @param dir Pointer to parent directory i-node
+ * @param parent Pointer to parent directory i-node
  * @return Error code
  */
 int ext4_dir_dx_init(struct ext4_inode_ref *dir,

include/ext4_fs.h

@@ -87,7 +87,7 @@ struct ext4_inode_ref {
 
 
 /**@brief Convert block address to relative index in block group.
- * @param sb Superblock pointer
+ * @param s Superblock pointer
  * @param baddr Block number to convert
  * @return Relative number of block
  */
@@ -187,7 +187,7 @@ void ext4_fs_inode_blocks_init(struct ext4_fs *fs,
 int ext4_fs_put_inode_ref(struct ext4_inode_ref *ref);
 
 /**@brief Convert filetype to inode mode.
- * @param filetype
+ * @param filetype File type
  * @return inode mode
  */
 uint32_t ext4_fs_correspond_inode_mode(int filetype);
@@ -222,7 +222,6 @@ ext4_fsblk_t ext4_fs_inode_to_goal_block(struct ext4_inode_ref *inode_ref);
 
 /**@brief Compute 'goal' for allocation algorithm (For blockmap).
  * @param inode_ref Reference to inode, to allocate block for
- * @param goal
  * @return error code
  */
 int ext4_fs_indirect_find_goal(struct ext4_inode_ref *inode_ref,
@@ -260,12 +259,12 @@ int ext4_fs_append_inode_dblk(struct ext4_inode_ref *inode_ref,
 			      ext4_fsblk_t *fblock, ext4_lblk_t *iblock);
 
 /**@brief   Increment inode link count.
- * @param   inode none handle
+ * @param   inode_ref none handle
  */
 void ext4_fs_inode_links_count_inc(struct ext4_inode_ref *inode_ref);
 
 /**@brief   Decrement inode link count.
- * @param   inode none handle
+ * @param   inode_ref none handle
  */
 void ext4_fs_inode_links_count_dec(struct ext4_inode_ref *inode_ref);
 

include/ext4_hash.h

@@ -57,7 +57,7 @@ struct ext4_hash_info {
  * @param   name entry name
  * @param   len entry name length
  * @param   hash_seed (from superblock)
- * @param   hash version (from superblock)
+ * @param   hash_version version (from superblock)
  * @param   hash_minor output value
  * @param   hash_major output value
  * @return  standard error code*/

include/ext4_inode.h

@@ -159,7 +159,7 @@ uint16_t ext4_inode_get_links_cnt(struct ext4_inode *inode);
 
 /**@brief Set number of links to i-node.
  * @param inode I-node to set number of links to
- * @param count Number of links to i-node
+ * @param cnt Number of links to i-node
  */
 void ext4_inode_set_links_cnt(struct ext4_inode *inode, uint16_t cnt);
 
@@ -174,7 +174,7 @@ uint64_t ext4_inode_get_blocks_count(struct ext4_sblock *sb,
 /**@brief Set number of 512-bytes blocks used for i-node.
  * @param sb    Superblock
  * @param inode I-node
- * @param count Number of 512-bytes blocks
+ * @param cnt Number of 512-bytes blocks
  * @return Error code
  */
 int ext4_inode_set_blocks_count(struct ext4_sblock *sb,
@@ -200,7 +200,7 @@ uint32_t ext4_inode_get_generation(struct ext4_inode *inode);
 
 /**@brief Set file generation (used by NFS).
  * @param inode      I-node
- * @param generation File generation
+ * @param gen File generation
  */
 void ext4_inode_set_generation(struct ext4_inode *inode, uint32_t gen);
 
@@ -232,7 +232,7 @@ uint64_t ext4_inode_get_file_acl(struct ext4_inode *inode,
 /**@brief Set address of block, where are extended attributes located.
  * @param inode    I-node
  * @param sb       Superblock
- * @param file_acl Block address
+ * @param acl Block address
  */
 void ext4_inode_set_file_acl(struct ext4_inode *inode, struct ext4_sblock *sb,
 			     uint64_t acl);
@@ -247,7 +247,7 @@ uint32_t ext4_inode_get_direct_block(struct ext4_inode *inode, uint32_t idx);
 /**@brief Set block address of specified direct block.
  * @param inode  I-node to set block address to
  * @param idx    Index of logical block
- * @param fblock Physical block address
+ * @param block Physical block address
  */
 void ext4_inode_set_direct_block(struct ext4_inode *inode, uint32_t idx,
 				 uint32_t block);
@@ -262,7 +262,7 @@ uint32_t ext4_inode_get_indirect_block(struct ext4_inode *inode, uint32_t idx);
 /**@brief Set block address of specified indirect block.
  * @param inode  I-node to set block address to
  * @param idx    Index of indirect block
- * @param fblock Physical block address
+ * @param block Physical block address
  */
 void ext4_inode_set_indirect_block(struct ext4_inode *inode, uint32_t idx,
 				   uint32_t block);
@@ -297,20 +297,20 @@ bool ext4_inode_is_type(struct ext4_sblock *sb, struct ext4_inode *inode,
 
 /**@brief Check if i-node has specified flag.
  * @param inode I-node to check flags of
- * @param flag  Flag to check
+ * @param f  Flag to check
  * @return Result of check operation
  */
 bool ext4_inode_has_flag(struct ext4_inode *inode, uint32_t f);
 
 /**@brief Remove specified flag from i-node.
  * @param inode      I-node to clear flag on
- * @param clear_flag Flag to be cleared
+ * @param f Flag to be cleared
  */
 void ext4_inode_clear_flag(struct ext4_inode *inode, uint32_t f);
 
 /**@brief Set specified flag to i-node.
  * @param inode    I-node to set flag on
- * @param set_flag Flag to be set
+ * @param f Flag to be set
  */
 void ext4_inode_set_flag(struct ext4_inode *inode, uint32_t f);
 

include/ext4_super.h

@@ -61,7 +61,7 @@ static inline uint64_t ext4_sb_get_blocks_cnt(struct ext4_sblock *s)
 
 /**@brief   Blocks count set  in superblock.
  * @param   s superblock descriptor
- * @return  count of blocks*/
+ * @param   cnt count of blocks*/
 static inline void ext4_sb_set_blocks_cnt(struct ext4_sblock *s, uint64_t cnt)
 {
 	s->blocks_count_lo = to_le32((cnt << 32) >> 32);

src/ext4_balloc.c

@@ -54,7 +54,7 @@
 #include <ext4_inode.h>
 
 /**@brief Compute number of block group from block address.
- * @param sb superblock pointer.
+ * @param s superblock pointer.
  * @param baddr Absolute address of block.
  * @return Block group index
  */
@@ -68,7 +68,7 @@ uint32_t ext4_balloc_get_bgid_of_block(struct ext4_sblock *s,
 }
 
 /**@brief Compute the starting block address of a block group
- * @param sb   superblock pointer.
+ * @param s   superblock pointer.
  * @param bgid block group index
  * @return Block address
  */

src/ext4_dir_idx.c

@@ -54,7 +54,7 @@
 #include <stdlib.h>
 
 /**@brief Get hash version used in directory index.
- * @param root_info Pointer to root info structure of index
+ * @param ri Pointer to root info structure of index
  * @return Hash algorithm version
  */
 static inline uint8_t
@@ -64,7 +64,7 @@ ext4_dir_dx_rinfo_get_hash_version(struct ext4_dir_idx_rinfo *ri)
 }
 
 /**@brief Set hash version, that will be used in directory index.
- * @param root_info Pointer to root info structure of index
+ * @param ri Pointer to root info structure of index
  * @param v Hash algorithm version
  */
 static inline void
@@ -74,7 +74,7 @@ ext4_dir_dx_rinfo_set_hash_version(struct ext4_dir_idx_rinfo *ri, uint8_t v)
 }
 
 /**@brief Get length of root_info structure in bytes.
- * @param root_info Pointer to root info structure of index
+ * @param ri Pointer to root info structure of index
  * @return Length of the structure
  */
 static inline uint8_t
@@ -84,8 +84,8 @@ ext4_dir_dx_rinfo_get_info_length(struct ext4_dir_idx_rinfo *ri)
 }
 
 /**@brief Set length of root_info structure in bytes.
- * @param root_info   Pointer to root info structure of index
- * @param info_length Length of the structure
+ * @param ri   Pointer to root info structure of index
+ * @param len Length of the structure
  */
 static inline void
 ext4_dir_dx_root_info_set_info_length(struct ext4_dir_idx_rinfo *ri,
@@ -95,7 +95,7 @@ ext4_dir_dx_root_info_set_info_length(struct ext4_dir_idx_rinfo *ri,
 }
 
 /**@brief Get number of indirect levels of HTree.
- * @param root_info Pointer to root info structure of index
+ * @param ri Pointer to root info structure of index
  * @return Height of HTree (actually only 0 or 1)
  */
 static inline uint8_t
@@ -105,8 +105,8 @@ ext4_dir_dx_rinfo_get_indirect_levels(struct ext4_dir_idx_rinfo *ri)
 }
 
 /**@brief Set number of indirect levels of HTree.
- * @param root_info Pointer to root info structure of index
- * @param lvl Height of HTree (actually only 0 or 1)
+ * @param ri Pointer to root info structure of index
+ * @param l Height of HTree (actually only 0 or 1)
  */
 static inline void
 ext4_dir_dx_rinfo_set_indirect_levels(struct ext4_dir_idx_rinfo *ri, uint8_t l)
@@ -834,7 +834,6 @@ cleanup:
  *         It can compare two entries by hash value.
  * @param arg1  First entry
  * @param arg2  Second entry
- * @param dummy Unused parameter, can be NULL
  *
  * @return Classic compare result
  *         (0: equal, -1: arg1 < arg2, 1: arg1 > arg2)
@@ -1067,9 +1066,9 @@ static int ext4_dir_dx_split_data(struct ext4_inode_ref *inode_ref,
 }
 
 /**@brief  Split index node and maybe some parent nodes in the tree hierarchy.
- * @param inode_ref Directory i-node
- * @param dx_blocks Array with path from root to leaf node
- * @param dx_block  Leaf block to be split if needed
+ * @param ino_ref Directory i-node
+ * @param dx_blks Array with path from root to leaf node
+ * @param dxb  Leaf block to be split if needed
  * @return Error code
  */
 static int

src/ext4_fs.c

@@ -1270,7 +1270,6 @@ ext4_fsblk_t ext4_fs_inode_to_goal_block(struct ext4_inode_ref *inode_ref)
 
 /**@brief Compute 'goal' for allocation algorithm (For blockmap).
  * @param inode_ref Reference to inode, to allocate block for
- * @param goal
  * @return error code
  */
 int ext4_fs_indirect_find_goal(struct ext4_inode_ref *inode_ref,

src/ext4_journal.c

@@ -640,7 +640,7 @@ struct tag_info {
 /**@brief  Extract information from a block tag.
  * @param  __tag pointer to the block tag
  * @param  tag_bytes block tag size of this jbd filesystem
- * @param  remaining size in buffer containing the block tag
+ * @param  remain_buf_size size in buffer containing the block tag
  * @param  tag_info information of this tag.
  * @return  EOK when succeed, otherwise return EINVAL.*/
 static int
@@ -717,7 +717,7 @@ jbd_extract_block_tag(struct jbd_fs *jbd_fs,
 
 /**@brief  Write information to a block tag.
  * @param  __tag pointer to the block tag
- * @param  remaining size in buffer containing the block tag
+ * @param  remain_buf_size size in buffer containing the block tag
  * @param  tag_info information of this tag.
  * @return  EOK when succeed, otherwise return EINVAL.*/
 static int
@@ -994,7 +994,7 @@ static void jbd_destroy_revoke_tree(struct recover_info *info)
 /**@brief  Add entries in a revoke block to revoke tree.
  * @param  jbd_fs jbd filesystem
  * @param  header revoke block header
- * @param  recover_info  journal replay info*/
+ * @param  info  journal replay info*/
 static void jbd_build_revoke_tree(struct jbd_fs *jbd_fs,
 				  struct jbd_bhdr *header,
 				  struct recover_info *info)
@@ -1055,7 +1055,7 @@ static void jbd_replay_descriptor_block(struct jbd_fs *jbd_fs,
 
 /**@brief  The core routine of journal replay.
  * @param  jbd_fs jbd filesystem
- * @param  recover_info  journal replay info
+ * @param  info  journal replay info
  * @param  action action needed to be taken
  * @return standard error code*/
 static int jbd_iterate_log(struct jbd_fs *jbd_fs,
@@ -1720,8 +1720,7 @@ int jbd_trans_try_revoke_block(struct jbd_trans *trans,
 /**@brief  Free a transaction
  * @param  journal current journal session
  * @param  trans transaction
- * @param  abort discard all the modifications on the block?
- * @return standard error code*/
+ * @param  abort discard all the modifications on the block?*/
 void jbd_journal_free_trans(struct jbd_journal *journal,
 			    struct jbd_trans *trans,
 			    bool abort)