ext4: improve dox documentation style

1 files changed, 282 insertions, 200 deletions

diff --git a/include/ext4.h b/include/ext4.h
index 3cfb4d5..f74efb6 100644
--- a/include/ext4.h
+++ b/include/ext4.h
@@ -58,22 +58,22 @@ extern "C" {
 /**@brief   OS dependent lock interface.*/
 struct ext4_lock {
 
-	/**@brief   Lock access to mount point*/
+	/**@brief   Lock access to mount point.*/
 	void (*lock)(void);
 
-	/**@brief   Unlock access to mount point*/
+	/**@brief   Unlock access to mount point.*/
 	void (*unlock)(void);
 };
 
 /********************************FILE DESCRIPTOR*****************************/
 
-/**@brief   File descriptor*/
+/**@brief   File descriptor. */
 typedef struct ext4_file {
 
 	/**@brief   Mount point handle.*/
 	struct ext4_mountpoint *mp;
 
-	/**@brief   File inode id*/
+	/**@brief   File inode id.*/
 	uint32_t inode;
 
 	/**@brief   Open flags.*/
@@ -82,13 +82,13 @@ typedef struct ext4_file {
 	/**@brief   File size.*/
 	uint64_t fsize;
 
-	/**@brief   File position*/
+	/**@brief   Actual file position.*/
 	uint64_t fpos;
 } ext4_file;
 
 /*****************************DIRECTORY DESCRIPTOR***************************/
 
-/**@brief   Directory entry descriptor. Copy from ext4_types.h*/
+/**@brief   Directory entry descriptor. */
 typedef struct ext4_direntry {
 	uint32_t inode;
 	uint16_t entry_length;
@@ -97,12 +97,13 @@ typedef struct ext4_direntry {
 	uint8_t name[255];
 } ext4_direntry;
 
+/**@brief   Directory descriptor. */
 typedef struct ext4_dir {
-	/**@brief   File descriptor*/
+	/**@brief   File descriptor.*/
 	ext4_file f;
 	/**@brief   Current directory entry.*/
 	ext4_direntry de;
-	/**@brief   Next entry offset*/
+	/**@brief   Next entry offset.*/
 	uint64_t next_off;
 } ext4_dir;
 
@@ -131,7 +132,7 @@ int ext4_device_unregister_all(void);
 
 /**@brief   Mount a block device with EXT4 partition to the mount point.
  *
- * @param   dev_name block Device name (@ref ext4_device_register).
+ * @param   dev_name Block device name (@ref ext4_device_register).
  * @param   mount_point Mount point, for example:
  *          -   /
  *          -   /my_partition/
@@ -144,11 +145,13 @@ int ext4_mount(const char *dev_name,
 	       bool read_only);
 
 /**@brief   Umount operation.
- * @param   mount_point mount name
- * @return  standard error code */
+ *
+ * @param   mount_pount Mount point.
+ *
+ * @return  Standard error code */
 int ext4_umount(const char *mount_point);
 
-/**@brief   Start journaling. Journaling start/stop functions are transparent
+/**@brief   Starts journaling. Journaling start/stop functions are transparent
  *          and might be used on filesystems without journaling support.
  * @warning Usage:
  *              ext4_mount("sda1", "/");
@@ -158,23 +161,28 @@ int ext4_umount(const char *mount_point);
  *
  *              ext4_journal_stop("/");
  *              ext4_umount("/");
- * @param   mount_point mount name
- * @return  standard error code */
+ * @param   mount_pount Mount point.
+ *
+ * @return  Standard error code. */
 int ext4_journal_start(const char *mount_point);
 
-/**@brief   Stop journaling. Journaling start/stop functions are transparent
+/**@brief   Stops journaling. Journaling start/stop functions are transparent
  *          and might be used on filesystems without journaling support.
- * @param   mount_point mount name
- * @return  standard error code */
+ *
+ * @param   mount_pount Mount point name.
+ *
+ * @return  Standard error code. */
 int ext4_journal_stop(const char *mount_point);
 
 /**@brief   Journal recovery.
- * @param   mount_point mount point
- * @warning Must be called after @ref ext4_mount
- * @return standard error code */
+ * @warning Must be called after @ref ext4_mount.
+ *
+ * @param   mount_pount Mount point.
+ *
+ * @return Standard error code. */
 int ext4_recover(const char *mount_point);
 
-/**@brief   Some of the filesystem stats.*/
+/**@brief   Some of the filesystem stats. */
 struct ext4_mount_stats {
 	uint32_t inodes_count;
 	uint32_t free_inodes_count;
@@ -189,24 +197,30 @@ struct ext4_mount_stats {
 	char volume_name[16];
 };
 
-/**@brief   Get file system params.
- * @param   mount_point mount path
- * @param   stats ext fs stats
- * @return  standard error code */
+/**@brief   Get file mount point stats.
+ *
+ * @param   mount_pount Mount point.
+ * @param   stats Filesystem stats.
+ *
+ * @return Standard error code. */
 int ext4_mount_point_stats(const char *mount_point,
 			   struct ext4_mount_stats *stats);
 
 /**@brief   Setup OS lock routines.
- * @param   mount_point mount path
- * @param   locks - lock and unlock functions
- * @return  standard error code */
+ *
+ * @param   mount_pount Mount point.
+ * @param   locks  Lock and unlock functions
+ *
+ * @return Standard error code. */
 int ext4_mount_setup_locks(const char *mount_point,
 			   const struct ext4_lock *locks);
 
 /**@brief   Acquire the filesystem superblock pointer of a mp.
- * @param   mount_point mount path
- * @param   superblock pointer
- * @return  standard error code */
+ *
+ * @param   mount_pount Mount point.
+ * @param   sb Superblock handle
+ *
+ * @return Standard error code. */
 int ext4_get_sblock(const char *mount_point, struct ext4_sblock **sb);
 
 /**@brief   Enable/disable write back cache mode.
@@ -240,43 +254,48 @@ 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   path mount point path
- * @param   on enable/disable
+ * @param   mount_pount Mount point.
+ * @param   on Enable/disable cache writeback mode.
  *
- * @return  standard error code */
+ * @return Standard error code. */
 int ext4_cache_write_back(const char *path, bool on);
 
 
 /**@brief   Force cache flush.
  *
- * @param   path mount point path
+ * @param   mount_pount Mount point.
  *
- * @return  standard error code */
+ * @return  Standard error code. */
 int ext4_cache_flush(const char *path);
 
 /********************************FILE OPERATIONS*****************************/
 
 /**@brief   Remove file by path.
- * @param   path path to file
- * @return  standard error code */
+ *
+ * @param   path Path to file.
+ *
+ * @return  Standard error code. */
 int ext4_fremove(const char *path);
 
-/**@brief   create a hardlink for a file.
- * @param   path path to file
- * @param   hardlink_path path of hardlink
- * @return  standard error code */
+/**@brief   Create a hardlink for a file.
+ *
+ * @param   path Path to file.
+ * @param   hardlink_path Path of hardlink.
+ *
+ * @return  Standard error code. */
 int ext4_flink(const char *path, const char *hardlink_path);
 
-/**@brief Rename file
- * @param path source
- * @param new_path destination
- * @return  standard error code */
+/**@brief Rename file.
+ * @param path Source.
+ * @param new_path Destination.
+ * @return  Standard error code. */
 int ext4_frename(const char *path, const char *new_path);
 
 /**@brief   File open function.
- * @param   path filename (has to start from mount point)
- *          /my_partition/my_file
- * @param   flags open file flags
+ *
+ * @param   file  File handle.
+ * @param   path  File path, has to start from mount point:/my_partition/file.
+ * @param   flags File open flags.
  *  |---------------------------------------------------------------|
  *  |   r or rb                 O_RDONLY                            |
  *  |---------------------------------------------------------------|
@@ -291,232 +310,295 @@ int ext4_frename(const char *path, const char *new_path);
  *  |   a+ or ab+ or a+b        O_RDWR|O_CREAT|O_APPEND             |
  *  |---------------------------------------------------------------|
  *
- * @return  standard error code*/
-int ext4_fopen(ext4_file *f, const char *path, const char *flags);
+ * @return  Standard error code.*/
+int ext4_fopen(ext4_file *file, const char *path, const char *flags);
 
 /**@brief   Alternate file open function.
- * @param   filename, (has to start from mount point)
- *          /my_partition/my_file
- * @param   flags open file flags
- * @return  standard error code*/
-int ext4_fopen2(ext4_file *f, const char *path, int flags);
+ *
+ * @param   file  File handle.
+ * @param   path  File path, has to start from mount point:/my_partition/file.
+ * @param   flags File open flags.
+ *
+ * @return  Standard error code.*/
+int ext4_fopen2(ext4_file *file, const char *path, int flags);
 
 /**@brief   File close function.
- * @param   f file handle
- * @return  standard error code*/
-int ext4_fclose(ext4_file *f);
+ *
+ * @param   file File handle.
+ *
+ * @return  Standard error code.*/
+int ext4_fclose(ext4_file *file);
 
-/**@brief   Fill in the ext4_inode buffer.
- * @param   path fetch inode data of the path
- * @param   ret_ino the inode id of the path
- * @param   ext4_inode buffer
- * @return  standard error code*/
-int ext4_fill_raw_inode(const char *path, uint32_t *ret_ino,
-			struct ext4_inode *inode);
 
 /**@brief   File truncate function.
- * @param   f file handle
- * @param   new file size
- * @return  standard error code*/
-int ext4_ftruncate(ext4_file *f, uint64_t size);
+ *
+ * @param   file File handle.
+ * @param   size New file size.
+ *
+ * @return  Standard error code.*/
+int ext4_ftruncate(ext4_file *file, uint64_t size);
 
 /**@brief   Read data from file.
- * @param   f file handle
- * @param   buf output buffer
- * @param   size bytes to read
- * @param   rcnt bytes read (may be NULL)
- * @return  standard error code*/
-int ext4_fread(ext4_file *f, void *buf, size_t size, size_t *rcnt);
+ *
+ * @param   file File handle.
+ * @param   buf  Output buffer.
+ * @param   size Bytes to read.
+ * @param   rcnt Bytes read (NULL allowed).
+ *
+ * @return  Standard error code.*/
+int ext4_fread(ext4_file *file, void *buf, size_t size, size_t *rcnt);
 
 /**@brief   Write data to file.
- * @param   f file handle
- * @param   buf data to write
- * @param   size write length
- * @param   wcnt bytes written (may be NULL)
- * @return  standard error code*/
-int ext4_fwrite(ext4_file *f, const void *buf, size_t size, size_t *wcnt);
+ *
+ * @param   file File handle.
+ * @param   buf  Data to write
+ * @param   size Write length..
+ * @param   wcnt Bytes written (NULL allowed).
+ *
+ * @return  Standard error code.*/
+int ext4_fwrite(ext4_file *file, const void *buf, size_t size, size_t *wcnt);
 
 /**@brief   File seek operation.
- * @param   f file handle
- * @param   offset offset to seek
- * @param   origin seek type:
+ *
+ * @param   file File handle.
+ * @param   offset Offset to seek.
+ * @param   origin Seek type:
  *              @ref SEEK_SET
  *              @ref SEEK_CUR
  *              @ref SEEK_END
- * @return  standard error code*/
-int ext4_fseek(ext4_file *f, uint64_t offset, uint32_t origin);
+ *
+ * @return  Standard error code.*/
+int ext4_fseek(ext4_file *file, uint64_t offset, uint32_t origin);
 
 /**@brief   Get file position.
- * @param   f file handle
- * @return  actual file position */
-uint64_t ext4_ftell(ext4_file *f);
+ *
+ * @param   file File handle.
+ *
+ * @return  Actual file position */
+uint64_t ext4_ftell(ext4_file *file);
 
 /**@brief   Get file size.
- * @param   f file handle
- * @return  file size */
-uint64_t ext4_fsize(ext4_file *f);
+ *
+ * @param   file File handle.
+ *
+ * @return  File size. */
+uint64_t ext4_fsize(ext4_file *file);
 
-/**@brief Change file/directory/link mode bits
- * @param path to file/dir/link
- * @param mode new mode bits (for example 0777)
- * @return  standard error code*/
+
+/**@brief Get inode of file/directory/link.
+ *
+ * @param path    Parh to file/dir/link.
+ * @param ret_ino Inode number.
+ * @param inode   Inode internals.
+ *
+ * @return  Standard error code.*/
+int ext4_raw_inode_fill(const char *path, uint32_t *ret_ino,
+			struct ext4_inode *inode);
+
+/**@brief Change file/directory/link mode bits.
+ *
+ * @param path Path to file/dir/link.
+ * @param mode New mode bits (for example 0777).
+ *
+ * @return  Standard error code.*/
 int ext4_mode_set(const char *path, uint32_t mode);
 
 
-/**@brief Get file/directory/link mode bits
- * @param path to file/dir/link
- * @param mode new mode bits (for example 0777)
- * @return  standard error code*/
+/**@brief Get file/directory/link mode bits.
+ *
+ * @param path Path to file/dir/link.
+ * @param mode New mode bits (for example 0777).
+ *
+ * @return  Standard error code.*/
 int ext4_mode_get(const char *path, uint32_t *mode);
 
-/**@brief Change file owner and group
- * @param path to file/dir/link
- * @param uid user id
- * @param gid group id
- * @return  standard error code*/
+/**@brief Change file owner and group.
+ *
+ * @param path Path to file/dir/link.
+ * @param uid  User id.
+ * @param gid  Group id.
+ *
+ * @return  Standard error code.*/
 int ext4_owner_set(const char *path, uint32_t uid, uint32_t gid);
 
-/**@brief Get file/directory/link owner and group
- * @param path to file/dir/link
- * @param uid user id
- * @param gid group id
- * @return  standard error code*/
+/**@brief Get file/directory/link owner and group.
+ *
+ * @param path Path to file/dir/link.
+ * @param uid  User id.
+ * @param gid  Group id.
+ *
+ * @return  Standard error code.*/
 int ext4_owner_get(const char *path, uint32_t *uid, uint32_t *gid);
 
-/**@brief Set file/directory/link access time
- * @param path to file/dir/link
- * @param atime access timestamp
- * @return  standard error code*/
+/**@brief Set file/directory/link access time.
+ *
+ * @param path  Path to file/dir/link.
+ * @param atime Access timestamp.
+ *
+ * @return  Standard error code.*/
 int ext4_atime_set(const char *path, uint32_t atime);
 
-/**@brief Set file/directory/link modify time
- * @param path to file/dir/link
- * @param mtime modify timestamp
- * @return  standard error code*/
+/**@brief Set file/directory/link modify time.
+ *
+ * @param path  Path to file/dir/link.
+ * @param mtime Modify timestamp.
+ *
+ * @return  Standard error code.*/
 int ext4_mtime_set(const char *path, uint32_t mtime);
 
-/**@brief Set file/directory/link change time
- * @param path to file/dir/link
- * @param ctime change timestamp
- * @return  standard error code*/
+/**@brief Set file/directory/link change time.
+ *
+ * @param path  Path to file/dir/link.
+ * @param ctime Change timestamp.
+ *
+ * @return  Standard error code.*/
 int ext4_ctime_set(const char *path, uint32_t ctime);
 
-/**@brief Get file/directory/link access time
- * @param path to file/dir/link
- * @param atime access timestamp
- * @return  standard error code*/
+/**@brief Get file/directory/link access time.
+ *
+ * @param path  Path to file/dir/link.
+ * @param atime Access timestamp.
+ *
+ * @return  Standard error code.*/
 int ext4_atime_get(const char *path, uint32_t *atime);
 
-/**@brief Get file/directory/link modify time
- * @param path to file/dir/link
- * @param mtime modify timestamp
- * @return  standard error code*/
+/**@brief Get file/directory/link modify time.
+ *
+ * @param path  Path to file/dir/link.
+ * @param mtime Modify timestamp.
+ *
+ * @return  Standard error code.*/
 int ext4_mtime_get(const char *path, uint32_t *mtime);
 
-/**@brief Get file/directory/link change time
- * @param path to file/dir/link
- * @param ctime change timestamp
+/**@brief Get file/directory/link change time.
+ *
+ * @param path  Pathto file/dir/link.
+ * @param ctime Change timestamp.
+ *
  * @return  standard error code*/
 int ext4_ctime_get(const char *path, uint32_t *ctime);
 
-/**@brief Create symbolic link
- * @param target destination path
- * @param path source entry
- * @return standard error code*/
+/**@brief Create symbolic link.
+ *
+ * @param target Destination entry path.
+ * @param path   Source entry path.
+ *
+ * @return  Standard error code.*/
 int ext4_fsymlink(const char *target, const char *path);
 
-/**@brief Create special file
- * @param path path to new file
- * @param filetype The filetype of the new special file
- * 	  (that must not be regular file, directory, or unknown type)
- * @param dev if filetype is char device or block device,
- * 	  the device number will become the payload in the inode
- * @return standard error code*/
+/**@brief Create special file.
+ * @param path     Path to new special file.
+ * @param filetype Filetype of the new special file.
+ * 	           (that must not be regular file, directory, or unknown type)
+ * @param dev      If filetype is char device or block device,
+ * 	           the device number will become the payload in the inode.
+ * @return  Standard error code.*/
 int ext4_mknod(const char *path, int filetype, uint32_t dev);
 
-/**@brief Read symbolic link payload
- * @param path to symlink
- * @param buf output buffer
- * @param bufsize output buffer max size
- * @param rcnt bytes read
- * @return standard error code*/
+/**@brief Read symbolic link payload.
+ *
+ * @param path    Path to symlink.
+ * @param buf     Output buffer.
+ * @param bufsize Output buffer max size.
+ * @param rcnt    Bytes read.
+ *
+ * @return  Standard error code.*/
 int ext4_readlink(const char *path, char *buf, size_t bufsize, size_t *rcnt);
 
-/**@brief Set extended attribute
- * @param path to file/directory
- * @param name name of the entry to add
- * @param name_len length of @name in bytes
- * @param data data of the entry to add
- * @param data_size size of data to add
- * @param replace this boolean is deprecated.
- * @return standard error code*/
+/**@brief Set extended attribute.
+ *
+ * @param path      Path to file/directory
+ * @param name      Name of the entry to add.
+ * @param name_len  Length of @name in bytes.
+ * @param data      Data of the entry to add.
+ * @param data_size Size of data to add.
+ *
+ * @return  Standard error code.*/
 int ext4_setxattr(const char *path, const char *name, size_t name_len,
-		  const void *data, size_t data_size, bool replace);
-
-/**@brief Get extended attribute
- * @param 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
- * @return standard error code*/
+		  const void *data, size_t data_size);
+
+/**@brief Get extended attribute.
+ *
+ * @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.
+ *
+ * @return  Standard error code.*/
 int ext4_getxattr(const char *path, const char *name, size_t name_len,
 		  void *buf, size_t buf_size, size_t *data_size);
 
-/**@brief List extended attributes
- * @param path to file/directory
- * @param list list to hold the name of entries
- * @param size size of @list in bytes
- * @param ret_size used bytes of @list
- * @return standard error code*/
+/**@brief List extended attributes.
+ *
+ * @param path     Path to file/directory.
+ * @param list     List to hold the name of entries.
+ * @param size     Size of @list in bytes.
+ * @param ret_size Used bytes of @list.
+ *
+ * @return  Standard error code.*/
 int ext4_listxattr(const char *path, char *list, size_t size, size_t *ret_size);
 
-/**@brief Remove extended attribute
- * @param path to file/directory
- * @param name name of the entry to remove
- * @param name_len length of @name in bytes
- * @return standard error code*/
+/**@brief Remove extended attribute.
+ *
+ * @param path     Path to file/directory.
+ * @param name     Name of the entry to remove.
+ * @param name_len Length of @name in bytes.
+ *
+ * @return  Standard error code.*/
 int ext4_removexattr(const char *path, const char *name, size_t name_len);
 
 
 /*********************************DIRECTORY OPERATION***********************/
 
 /**@brief   Recursive directory remove.
- * @param   path directory path to remove
- * @return  standard error code*/
+ *
+ * @param   path Directory path to remove
+ *
+ * @return  Standard error code.*/
 int ext4_dir_rm(const char *path);
 
-/**@brief Rename/move directory
- * @param path source
- * @param new_path destination
- * @return  standard error code */
+/**@brief Rename/move directory.
+ *
+ * @param path     Source path.
+ * @param new_path Destination path.
+ *
+ * @return  Standard error code. */
 int ext4_dir_mv(const char *path, const char *new_path);
 
 /**@brief   Create new directory.
- * @param   name new directory name
- * @return  standard error code*/
+ *
+ * @param   path Directory name.
+ *
+ * @return  Standard error code.*/
 int ext4_dir_mk(const char *path);
 
 /**@brief   Directory open.
- * @param   d directory handle
- * @param   path directory path
- * @return  standard error code*/
-int ext4_dir_open(ext4_dir *d, const char *path);
+ *
+ * @param   dir  Directory handle.
+ * @param   path Directory path.
+ *
+ * @return  Standard error code.*/
+int ext4_dir_open(ext4_dir *dir, const char *path);
 
 /**@brief   Directory close.
- * @param   d directory handle
- * @return  standard error code*/
-int ext4_dir_close(ext4_dir *d);
+ *
+ * @param   dir directory handle.
+ *
+ * @return  Standard error code.*/
+int ext4_dir_close(ext4_dir *dir);
 
 /**@brief   Return next directory entry.
- * @param   d directory handle
- * @param   id entry id
- * @return  directory entry id (NULL if no entry)*/
-const ext4_direntry *ext4_dir_entry_next(ext4_dir *d);
+ *
+ * @param   dir Directory handle.
+ *
+ * @return  Directory entry id (NULL if no entry)*/
+const ext4_direntry *ext4_dir_entry_next(ext4_dir *dir);
 
 /**@brief   Rewine directory entry offset.
- * @param   d directory handle*/
-void ext4_dir_entry_rewind(ext4_dir *d);
+ *
+ * @param   dir Directory handle.*/
+void ext4_dir_entry_rewind(ext4_dir *dir);
 
 
 #ifdef __cplusplus