From 0e4396917fdcb2b30f6c5367d2bdc218f17de4a7 Mon Sep 17 00:00:00 2001
From: Ramesh Thomas <ramesh.thomas@intel.com>
Date: Thu, 4 Aug 2016 20:42:46 -0700
Subject: [PATCH] doc: Add file system documentation

Adds documentation of file system APIs

Jira: ZEP-643
Change-Id: Ieac14a3dcf4913aeba6da2d3dc718eaa09b6cd88
Signed-off-by: Ramesh Thomas <ramesh.thomas@intel.com>
---
 doc/api/api.rst         |  1 +
 doc/api/file_system.rst | 18 +++++++++++++
 include/fs.h            | 58 +++++++++++++++++++++++++++++++++++------
 3 files changed, 69 insertions(+), 8 deletions(-)
 create mode 100644 doc/api/file_system.rst

diff --git a/doc/api/api.rst b/doc/api/api.rst
index 9a2aa0f8ec076c..a68dab558a2a72 100644
--- a/doc/api/api.rst
+++ b/doc/api/api.rst
@@ -25,4 +25,5 @@ The use of the Zephyr APIs is the same for all platforms and boards.
    event_logger.rst
    system_log.rst
    power_management_api
+   file_system
 
diff --git a/doc/api/file_system.rst b/doc/api/file_system.rst
new file mode 100644
index 00000000000000..ab84fb24e12b82
--- /dev/null
+++ b/doc/api/file_system.rst
@@ -0,0 +1,18 @@
+.. _file_system:
+
+File System APIs
+#####################
+
+File System Functions
+*******************************
+
+.. doxygengroup:: file_system_api
+   :project: Zephyr
+   :content-only:
+
+File System Data Structures
+*******************************
+
+.. doxygengroup:: data_structures
+   :project: Zephyr
+   :content-only:
diff --git a/include/fs.h b/include/fs.h
index 25fb9426221cc1..0fe934aa1195f3 100644
--- a/include/fs.h
+++ b/include/fs.h
@@ -24,10 +24,10 @@
 extern "C" {
 #endif
 
-/** Create a ZFILE type similar to FILE for familiarity */
+/* Create a ZFILE type similar to FILE for familiarity */
 typedef struct _zfile_object ZFILE;
 
-/** Create a ZDIR type similar to DIR for familiarity */
+/* Create a ZDIR type similar to DIR for familiarity */
 typedef struct _zdir_object ZDIR;
 
 enum dir_entry_type {
@@ -35,12 +35,43 @@ enum dir_entry_type {
 	DIR_ENTRY_DIR
 };
 
+/**
+ * @brief File System Functions
+ * @defgroup data_structures File System Data Structures
+ * @ingroup file_system
+ * @{
+ */
+
+/** @var ZFILE
+ * @brief File object representing an open file
+ */
+
+/** @var ZDIR
+ * @brief Directory object representing an open directory
+ */
+
+/**
+ * @brief Structure to receive file or directory information
+ *
+ * Used in functions that reads the directory entries to get
+ * file or directory information.
+ *
+ * @param dir_entry_type Whether file or directory
+ * - DIR_ENTRY_FILE
+ * - DIR_ENTRY_DIR
+ * @param name Name of directory or file
+ * @param size Size of file. 0 if directory
+ */
 struct zfs_dirent {
-	enum dir_entry_type type;	/* Whether file or directory */
-	char name[MAX_FILE_NAME + 1];	/* Name of directory or file */
-	size_t size;			/* Size of file. 0 if directory */
+	enum dir_entry_type type;
+	char name[MAX_FILE_NAME + 1];
+	size_t size;
 };
 
+/**
+ * @}
+ */
+
 #ifndef SEEK_SET
 #define SEEK_SET	0	/* Seek from beginning of file. */
 #endif
@@ -51,6 +82,13 @@ struct zfs_dirent {
 #define SEEK_END	2	/* Seek from end of file.  */
 #endif
 
+/**
+ * @brief File System APIs
+ * @defgroup file_system_api File System APIs
+ * @ingroup file_system
+ * @{
+ */
+
 /**
  * @brief File open
  *
@@ -136,9 +174,9 @@ ssize_t fs_write(ZFILE *zfp, const void *ptr, size_t size);
  * @param zfp Pointer to the file object
  * @param offset Relative location to move the file pointer to
  * @param whence Relative location from where offset is to be calculated.
- * SEEK_SET = from beginning of file
- * SEE_CUR = from current position,
- * SEEK_END = from end of file.
+ * - SEEK_SET = from beginning of file
+ * - SEE_CUR = from current position,
+ * - SEEK_END = from end of file.
  *
  * @retval 0 Success
  * @retval -ERRNO errno code if error.
@@ -223,6 +261,10 @@ int fs_closedir(ZDIR *zdp);
  */
 int fs_stat(const char *path, struct zfs_dirent *entry);
 
+/**
+ * @}
+ */
+
 #ifdef __cplusplus
 }
 #endif