fs/spiffs: improve documentation

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
- */
+ */

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
 /** @} */