From ec9f37436d1858a93e731700af2ef21ad916cb92 Mon Sep 17 00:00:00 2001
From: Vincent Dupont <vincent@otakeys.com>
Date: Thu, 6 Jul 2017 09:43:08 +0200
Subject: [PATCH] fs/spiffs: improve documentation

---
 pkg/spiffs/doc.txt         |  2 +-
 sys/include/fs/spiffs_fs.h | 31 ++++++++++++++++++++++++++++---
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/pkg/spiffs/doc.txt b/pkg/spiffs/doc.txt
index 5da63d7e8f..10a562c88c 100644
--- a/pkg/spiffs/doc.txt
+++ b/pkg/spiffs/doc.txt
@@ -4,4 +4,4 @@
  * @ingroup  sys_fs
  * @brief    Provides a file system for SPI NOR flash devices
  * @see      https://github.com/pellepl/spiffs
- */
\ No newline at end of file
+ */
diff --git a/sys/include/fs/spiffs_fs.h b/sys/include/fs/spiffs_fs.h
index c9e7d24187..ccb1348c5b 100644
--- a/sys/include/fs/spiffs_fs.h
+++ b/sys/include/fs/spiffs_fs.h
@@ -8,7 +8,12 @@
 
 /**
  * @defgroup    sys_spiffs  SPIFFS integration
- * @ingroup     sys_fs
+ * @ingroup     pkg_spiffs
+ * @brief       RIOT integration of SPIFFS
+ *
+ * The RIOT integration of SPIFFS follows the SPIFFS wiki:
+ * https://github.com/pellepl/spiffs/wiki/Integrate-spiffs#integrating-spiffs
+ *
  * @{
  *
  * @file
@@ -42,17 +47,37 @@ extern "C" {
  * @{
  */
 #ifndef SPIFFS_FS_CACHE_SIZE
-#if SPIFFS_CACHE
+#if SPIFFS_CACHE || defined(DOXYGEN)
+/**
+ * @brief the size of the cache buffer
+ *
+ * Ignored if cache is disabled in build config. One cache page will be slightly
+ * larger than the logical page size. The more ram, the more cache pages,
+ * the quicker the system.
+ */
 #define SPIFFS_FS_CACHE_SIZE (512)
 #else
 #define SPIFFS_FS_CACHE_SIZE (0)
 #endif /* SPIFFS_CACHE */
 #endif /* SPIFFS_FS_CACHE_SIZE */
 #ifndef SPIFFS_FS_WORK_SIZE
+/**
+ * @brief The size of the work buffer
+ *
+ * A ram memory buffer being double the size of the logical page size
+ * This buffer is used extensively by the spiffs stack.
+ * If logical page size is 256, this buffer must be 512 bytes.
+ */
 #define SPIFFS_FS_WORK_SIZE  (512)
 #endif
 #ifndef SPIFFS_FS_FD_SPACE_SIZE
-#define SPIFFS_FS_FD_SPACE_SIZE (125)
+/**
+ * @brief the size of the file descriptor buffer
+ *
+ * A file descriptor normally is around 32 bytes depending on the build config -
+ * the bigger the buffer, the more file descriptors are available.
+ */
+#define SPIFFS_FS_FD_SPACE_SIZE (4 * 32)
 #endif
 /** @} */