diff --git a/src/spiffs.h b/src/spiffs.h
index 84b26f4..3de176e 100644
--- a/src/spiffs.h
+++ b/src/spiffs.h
@@ -38,20 +38,21 @@
 #define SPIFFS_ERR_INTERNAL             -10050
 
 
-// spi read call type
+/* spi read call function type */
 typedef s32_t (*spiffs_read)(u32_t addr, u32_t size, u8_t *dst);
-// spi write call type
+/* spi write call function type */
 typedef s32_t (*spiffs_write)(u32_t addr, u32_t size, u8_t *src);
-// spi erase call type
+/* spi erase call function type */
 typedef s32_t (*spiffs_erase)(u32_t addr, u32_t size);
 
-
+/* file system check callback report operation */
 typedef enum {
   SPIFFS_CHECK_LOOKUP = 0,
   SPIFFS_CHECK_INDEX,
   SPIFFS_CHECK_PAGE
 } spiffs_check_type;
 
+/* file system check callback report type */
 typedef enum {
   SPIFFS_CHECK_PROGRESS = 0,
   SPIFFS_CHECK_ERROR,
@@ -61,12 +62,10 @@ typedef enum {
   SPIFFS_CHECK_DELETE_BAD_FILE,
 } spiffs_check_report;
 
+/* file system check callback function */
 typedef void (*spiffs_check_callback)(spiffs_check_type type, spiffs_check_report report,
     u32_t arg1, u32_t arg2);
 
-// size of buffer on stack used when copying data
-#define SPIFFS_COPY_BUFFER_STACK        (64)
-
 #ifndef SPIFFS_DBG
 #define SPIFFS_DBG(...) \
     print(__VA_ARGS__)
@@ -81,12 +80,19 @@ typedef void (*spiffs_check_callback)(spiffs_check_type type, spiffs_check_repor
 #define SPIFFS_CHECK_DBG(...) printf(__VA_ARGS__)
 #endif
 
+/* Any write to the filehandle is appended to end of the file */
 #define SPIFFS_APPEND                   (1<<0)
+/* If the opened file exists, it will be truncated to zero length before opened */
 #define SPIFFS_TRUNC                    (1<<1)
+/* If the opened file does not exist, it will be created before opened */
 #define SPIFFS_CREAT                    (1<<2)
+/* The opened file may only be read */
 #define SPIFFS_RDONLY                   (1<<3)
+/* The opened file may only be writted */
 #define SPIFFS_WRONLY                   (1<<4)
+/* The opened file may be both read and writted */
 #define SPIFFS_RDWR                     (SPIFFS_RDONLY | SPIFFS_WRONLY)
+/* Any writes to the filehandle will never be cached */
 #define SPIFFS_DIRECT                   (1<<5)
 
 #define SPIFFS_SEEK_SET                 (0)
@@ -192,6 +198,7 @@ typedef struct {
   spiffs_check_callback check_cb_f;
 } spiffs;
 
+/* spiffs file status struct */
 typedef struct {
   spiffs_obj_id obj_id;
   u32_t size;
@@ -231,28 +238,128 @@ s32_t SPIFFS_mount(spiffs *fs, spiffs_config *config, u8_t *work,
     void *cache, u32_t cache_size,
     spiffs_check_callback check_cb_f);
 
+/**
+ * Unmounts the file system. All file handles will be flushed of any
+ * cached writes and closed.
+ * @param fs            the file system struct
+ */
 void SPIFFS_unmount(spiffs *fs);
 
+/**
+ * Creates a new file.
+ * @param fs            the file system struct
+ * @param path          the path of the new file
+ * @param attr          ignored, for posix compliance
+ */
 s32_t SPIFFS_creat(spiffs *fs, const char *path, spiffs_attr attr);
+
+/**
+ * Opens/creates a file.
+ * @param fs            the file system struct
+ * @param path          the path of the new file
+ * @param attr          ignored, for posix compliance
+ * @param mode          the mode for the open command, can be combinations of
+ *                      SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY,
+ *                      SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT
+ */
 spiffs_file SPIFFS_open(spiffs *fs, const char *path, spiffs_attr attr, spiffs_mode mode);
+
+/**
+ * Reads from given filehandle.
+ * @param fs            the file system struct
+ * @param fh            the filehandle
+ * @param buf           where to put read data
+ * @param len           how much to read
+ * @returns number of bytes read, or -1 if error
+ */
 s32_t SPIFFS_read(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
+
+/**
+ * Writes to given filehandle.
+ * @param fs            the file system struct
+ * @param fh            the filehandle
+ * @param buf           the data to write
+ * @param len           how much to write
+ * @returns number of bytes written, or -1 if error
+ */
 s32_t SPIFFS_write(spiffs *fs, spiffs_file fh, void *buf, s32_t len);
+
+/**
+ * Moves the read/write file offset
+ * @param fs            the file system struct
+ * @param fh            the filehandle
+ * @param offs          how much/where to move the offset
+ * @param whence        if SPIFFS_SEEK_SET, the file offset shall be set to offset bytes
+ *                      if SPIFFS_SEEK_CUR, the file offset shall be set to its current location plus offset
+ *                      if SPIFFS_SEEK_END, the file offset shall be set to the size of the file plus offset
+ */
 s32_t SPIFFS_lseek(spiffs *fs, spiffs_file fh, s32_t offs, int whence);
+
+/**
+ * Removes a file by path
+ * @param fs            the file system struct
+ * @param path          the path of the file to remove
+ */
 s32_t SPIFFS_remove(spiffs *fs, const char *path);
+
+/**
+ * Removes a file by filehandle
+ * @param fs            the file system struct
+ * @param fh            the filehandle of the file to remove
+ */
 s32_t SPIFFS_fremove(spiffs *fs, spiffs_file fh);
+
+/**
+ * Gets file status by path
+ * @param fs            the file system struct
+ * @param path          the path of the file to stat
+ * @param s             the stat struct to populate
+ */
 s32_t SPIFFS_stat(spiffs *fs, const char *path, spiffs_stat *s);
+
+/**
+ * Gets file status by filehandle
+ * @param fs            the file system struct
+ * @param fh            the filehandle of the file to stat
+ * @param s             the stat struct to populate
+ */
 s32_t SPIFFS_fstat(spiffs *fs, spiffs_file fh, spiffs_stat *s);
+
+/**
+ * Flushes all pending write operations from cache for given file
+ * @param fs            the file system struct
+ * @param fh            the filehandle of the file to flush
+ */
 s32_t SPIFFS_fflush(spiffs *fs, spiffs_file fh);
+
+/**
+ * Closes a filehandle. If there are pending write operations, these are finalized before closing.
+ * @param fs            the file system struct
+ * @param fh            the filehandle of the file to close
+ */
 void SPIFFS_close(spiffs *fs, spiffs_file fh);
+
+/**
+ * Returns last error of last file operation.
+ * @param fs            the file system struct
+ */
 s32_t SPIFFS_errno(spiffs *fs);
 
 spiffs_DIR *SPIFFS_opendir(spiffs *fs, const char *name, spiffs_DIR *d);
 s32_t SPIFFS_closedir(spiffs_DIR *d);
 struct spiffs_dirent *SPIFFS_readdir(spiffs_DIR *d, struct spiffs_dirent *e);
 
+/**
+ * Runs a consistency check on given filesystem.
+ * @param fs            the file system struct
+ */
 s32_t SPIFFS_check(spiffs *fs);
 
 #if SPIFFS_TEST_VISUALISATION
+/**
+ * Prints out a visualization of the filesystem.
+ * @param fs            the file system struct
+ */
 s32_t SPIFFS_vis(spiffs *fs);
 #endif
 
diff --git a/src/spiffs_cache.c b/src/spiffs_cache.c
index c5f7ca6..37aff0d 100644
--- a/src/spiffs_cache.c
+++ b/src/spiffs_cache.c
@@ -10,6 +10,7 @@
 
 #if SPIFFS_CACHE
 
+// returns cached page for give page index, or null if no such cached page
 static spiffs_cache_page *spiffs_cache_page_get(spiffs *fs, spiffs_page_ix pix) {
   spiffs_cache *cache = spiffs_get_cache(fs);
   if ((cache->cpage_use_map & cache->cpage_use_mask) == 0) return 0;
@@ -28,6 +29,7 @@ static spiffs_cache_page *spiffs_cache_page_get(spiffs *fs, spiffs_page_ix pix)
   return 0;
 }
 
+// frees cached page
 static s32_t spiffs_cache_page_free(spiffs *fs, int ix, u8_t write_back) {
   s32_t res = SPIFFS_OK;
   spiffs_cache *cache = spiffs_get_cache(fs);
@@ -53,6 +55,7 @@ static s32_t spiffs_cache_page_free(spiffs *fs, int ix, u8_t write_back) {
   return res;
 }
 
+// removes the oldest accessed cached page
 static s32_t spiffs_cache_page_remove_oldest(spiffs *fs, u8_t flag_mask, u8_t flags) {
   s32_t res = SPIFFS_OK;
   spiffs_cache *cache = spiffs_get_cache(fs);
@@ -82,6 +85,7 @@ static s32_t spiffs_cache_page_remove_oldest(spiffs *fs, u8_t flag_mask, u8_t fl
   return res;
 }
 
+// allocates a new cached page and returns it, or null if all cache pages are busy
 static spiffs_cache_page *spiffs_cache_page_allocate(spiffs *fs) {
   spiffs_cache *cache = spiffs_get_cache(fs);
   if (cache->cpage_use_map == 0xffffffff) {
@@ -102,8 +106,7 @@ static spiffs_cache_page *spiffs_cache_page_allocate(spiffs *fs) {
   return 0;
 }
 
-// ------------------------------
-
+// drops the cache page for give page index
 void spiffs_cache_drop_page(spiffs *fs, spiffs_page_ix pix) {
   spiffs_cache_page *cp =  spiffs_cache_page_get(fs, pix);
   if (cp) {
@@ -111,6 +114,9 @@ void spiffs_cache_drop_page(spiffs *fs, spiffs_page_ix pix) {
   }
 }
 
+// ------------------------------
+
+// reads from spi flash or the cache
 s32_t spiffs_phys_rd(
     spiffs *fs,
     u8_t op,
@@ -158,6 +164,7 @@ s32_t spiffs_phys_rd(
   return res;
 }
 
+// writes to spi flash and/or the cache
 s32_t spiffs_phys_wr(
     spiffs *fs,
     u8_t op,
@@ -199,6 +206,7 @@ s32_t spiffs_phys_wr(
 }
 
 #if SPIFFS_CACHE_WR
+// returns the cache page that this fd refers, or null if no cache page
 spiffs_cache_page *spiffs_cache_page_get_by_fd(spiffs *fs, spiffs_fd *fd) {
   spiffs_cache *cache = spiffs_get_cache(fs);
 
@@ -220,6 +228,8 @@ spiffs_cache_page *spiffs_cache_page_get_by_fd(spiffs *fs, spiffs_fd *fd) {
   return 0;
 }
 
+// allocates a new cache page and refers this to given fd - flushes an old cache
+// page if all cache is busy
 spiffs_cache_page *spiffs_cache_page_allocate_by_fd(spiffs *fs, spiffs_fd *fd) {
   // before this function is called, it is ensured that there is no already existing
   // cache page with same object id
@@ -236,6 +246,7 @@ spiffs_cache_page *spiffs_cache_page_allocate_by_fd(spiffs *fs, spiffs_fd *fd) {
   return cp;
 }
 
+// unrefers all fds that this cache page refers to and releases the cache page
 void spiffs_cache_fd_release(spiffs *fs, spiffs_cache_page *cp) {
   if (cp == 0) return;
   int i;
@@ -253,6 +264,7 @@ void spiffs_cache_fd_release(spiffs *fs, spiffs_cache_page *cp) {
 
 #endif
 
+// initializes the cache
 void spiffs_cache_init(spiffs *fs) {
   if (fs->cache == 0) return;
   u32_t sz = fs->cache_size;
diff --git a/src/spiffs_check.c b/src/spiffs_check.c
index 608e3c7..2cb1df6 100644
--- a/src/spiffs_check.c
+++ b/src/spiffs_check.c
@@ -25,7 +25,8 @@
 //---------------------------------------
 // Look up consistency
 
-
+// searches in the object indices and returns the referenced page index given
+// the object id and the data span index
 // destroys fs->lu_work
 static s32_t spiffs_object_get_data_page_index_reference(
   spiffs *fs,
@@ -57,6 +58,7 @@ static s32_t spiffs_object_get_data_page_index_reference(
   return res;
 }
 
+// copies page contents to a new page
 static s32_t spiffs_rewrite_page(spiffs *fs, spiffs_page_ix cur_pix, spiffs_page_header *p_hdr, spiffs_page_ix *new_pix) {
   s32_t res;
   res = spiffs_page_allocate_data(fs, p_hdr->obj_id, p_hdr, 0,0,0,0, new_pix);
@@ -69,6 +71,8 @@ static s32_t spiffs_rewrite_page(spiffs *fs, spiffs_page_ix cur_pix, spiffs_page
   return res;
 }
 
+// rewrites the object index for given object id and replaces the
+// data page index to a new page index
 static s32_t spiffs_rewrite_index(spiffs *fs, spiffs_obj_id obj_id, spiffs_span_ix data_spix, spiffs_page_ix new_data_pix, spiffs_page_ix objix_pix) {
   s32_t res;
   spiffs_block_ix bix;
@@ -132,6 +136,7 @@ static s32_t spiffs_rewrite_index(spiffs *fs, spiffs_obj_id obj_id, spiffs_span_
   return res;
 }
 
+// deletes an object just by marking object index header as deleted
 static s32_t spiffs_delete_obj_lazy(spiffs *fs, spiffs_obj_id obj_id) {
   spiffs_page_ix objix_hdr_pix;
   s32_t res;
@@ -148,6 +153,7 @@ static s32_t spiffs_delete_obj_lazy(spiffs *fs, spiffs_obj_id obj_id) {
   return res;
 }
 
+// validates the given look up entry
 static s32_t spiffs_lookup_check_validate(spiffs *fs, spiffs_obj_id lu_obj_id, spiffs_page_header *p_hdr,
     spiffs_page_ix cur_pix, spiffs_block_ix cur_block, int cur_entry, int *reload_lu) {
   u8_t delete_page = 0;
@@ -195,7 +201,8 @@ static s32_t spiffs_lookup_check_validate(spiffs *fs, spiffs_obj_id lu_obj_id, s
       // index page can be removed if other index with same obj_id and spanix is found
       res = spiffs_obj_lu_find_id_and_span(fs, p_hdr->obj_id | SPIFFS_OBJ_ID_IX_FLAG, p_hdr->span_ix, cur_pix, 0);
       if (res == SPIFFS_ERR_NOT_FOUND) {
-        // no such index page found, check for a data page
+        // no such index page found, check for a data page amongst page headers
+        // lu cannot be trusted
         res = spiffs_obj_lu_find_id_and_span_by_phdr(fs, p_hdr->obj_id | SPIFFS_OBJ_ID_IX_FLAG, 0, 0, 0);
         if (res == SPIFFS_OK) { // ignore other errors
           // got a data page also, assume lu corruption only, rewrite to new page
@@ -433,7 +440,7 @@ static s32_t spiffs_lookup_check_v(spiffs *fs, spiffs_obj_id obj_id, spiffs_bloc
 
 
 // Scans all object look up. For each entry, corresponding page header is checked for validity.
-// If an object index header page is found, this is checked
+// If an object index header page is found, this is also checked
 s32_t spiffs_lookup_consistency_check(spiffs *fs, u8_t check_all_objects) {
   s32_t res = SPIFFS_OK;
 
@@ -791,6 +798,7 @@ static s32_t spiffs_page_consistency_check_i(spiffs *fs) {
   return res;
 }
 
+// Checks consistency amongst all pages and fixes irregularities
 s32_t spiffs_page_consistency_check(spiffs *fs) {
   if (fs->check_cb_f) fs->check_cb_f(SPIFFS_CHECK_PAGE, SPIFFS_CHECK_PROGRESS, 0, 0);
   s32_t res = spiffs_page_consistency_check_i(fs);
@@ -804,6 +812,8 @@ s32_t spiffs_page_consistency_check(spiffs *fs) {
 //---------------------------------------
 // Object index consistency
 
+// searches for given object id in temporary object id index,
+// returns the index or -1
 static int spiffs_object_index_search(spiffs *fs, spiffs_obj_id obj_id) {
   int i;
   spiffs_obj_id *obj_table = (spiffs_obj_id *)fs->work;
diff --git a/src/spiffs_gc.c b/src/spiffs_gc.c
index 0540308..3f75d33 100644
--- a/src/spiffs_gc.c
+++ b/src/spiffs_gc.c
@@ -1,6 +1,9 @@
 #include "spiffs.h"
 #include "spiffs_nucleus.h"
 
+// Erases a logical block and updates the erase counter.
+// If cache is enabled, all pages that might be cached in this block
+// is dropped.
 static s32_t spiffs_gc_erase_block(
     spiffs *fs,
     spiffs_block_ix bix) {
@@ -41,6 +44,8 @@ static s32_t spiffs_gc_erase_block(
   return res;
 }
 
+// Searches for blocks where all entries are deleted - if one is found,
+// the block is erased.
 s32_t spiffs_gc_quick(
     spiffs *fs) {
   s32_t res = SPIFFS_OK;
@@ -103,6 +108,8 @@ s32_t spiffs_gc_quick(
   return res;
 }
 
+// Checks if garbaga collecting is necessary. If so a candidate block is found,
+// cleansed and erased
 s32_t spiffs_gc_check(
     spiffs *fs,
     u32_t len) {
@@ -170,6 +177,7 @@ s32_t spiffs_gc_check(
   return res;
 }
 
+// Updates page statistics for a block that is about to be erased
 s32_t spiffs_gc_erase_page_stats(
     spiffs *fs,
     spiffs_block_ix bix) {
@@ -206,6 +214,7 @@ s32_t spiffs_gc_erase_page_stats(
   return res;
 }
 
+// Finds block candidates to erase
 s32_t spiffs_gc_find_candidate(
     spiffs *fs,
     spiffs_block_ix **block_candidates,
diff --git a/src/spiffs_hydrogen.c b/src/spiffs_hydrogen.c
index 5854c70..287fafc 100644
--- a/src/spiffs_hydrogen.c
+++ b/src/spiffs_hydrogen.c
@@ -495,6 +495,8 @@ s32_t SPIFFS_fstat(spiffs *fs, spiffs_file fh, spiffs_stat *s) {
   return res;
 }
 
+// Checks if there are any cached writes for the object id associated with
+// given filehandle. If so, these writes are flushed.
 static s32_t spiffs_fflush_cache(spiffs *fs, spiffs_file fh) {
   s32_t res = SPIFFS_OK;
 #if SPIFFS_CACHE_WR
diff --git a/src/spiffs_nucleus.c b/src/spiffs_nucleus.c
index 7390dae..82aa11b 100644
--- a/src/spiffs_nucleus.c
+++ b/src/spiffs_nucleus.c
@@ -101,28 +101,39 @@ s32_t spiffs_phys_cpy(
 // Find object lookup entry containing given id with visitor.
 // Iterate over object lookup pages in each block until a given object id entry is found.
 // When found, the visitor function is called with block index, entry index and user_data.
-// If visitor returns SPIFFS_CONTINUE, the search goes on. Otherwise, the search will be
+// If visitor returns SPIFFS_VIS_CONTINUE, the search goes on. Otherwise, the search will be
 // ended and visitor's return code is returned to caller.
-// If no visitor is given (0) the search returns on first entry with matching object id, or
-// when whole area is searched without finding object id.
+// If no visitor is given (0) the search returns on first entry with matching object id.
+// If no match is found in all look up, SPIFFS_VIS_END is returned.
+// @param fs                    the file system
+// @param starting_block        the starting block to start search in
+// @param starting_lu_entry     the look up index entry to start search in
+// @param flags                 ored combination of SPIFFS_VIS_CHECK_ID, SPIFFS_VIS_CHECK_PH,
+//                              SPIFFS_VIS_NO_WRAP
+// @param obj_id                argument object id
+// @param v                     visitor callback function
+// @param user_data             any data, passed to the callback visitor function
+// @param user_p                any pointer, passed to the callback visitor function
+// @param block_ix              reported block index where match was found
+// @param lu_entry              reported look up index where match was found
 s32_t spiffs_obj_lu_find_entry_visitor(
     spiffs *fs,
     spiffs_block_ix starting_block,
-    int starting_index_entry,
+    int starting_lu_entry,
     u8_t flags,
     spiffs_obj_id obj_id,
     spiffs_visitor_f v,
     u32_t user_data,
     void *user_p,
     spiffs_block_ix *block_ix,
-    int *index_entry) {
+    int *lu_entry) {
   s32_t res = SPIFFS_OK;
   s32_t entry_count = fs->block_count * SPIFFS_OBJ_LOOKUP_MAX_ENTRIES(fs);
   spiffs_block_ix cur_block = starting_block;
   u32_t cur_block_addr = SPIFFS_BLOCK_TO_PADDR(fs, starting_block);
 
   spiffs_obj_id *obj_lu_buf = (spiffs_obj_id *)fs->lu_work;
-  int cur_entry = starting_index_entry;
+  int cur_entry = starting_lu_entry;
   u32_t entries_per_page = (SPIFFS_CFG_LOG_PAGE_SZ(fs) / sizeof(spiffs_obj_id));
 
   // wrap initial
@@ -152,7 +163,7 @@ s32_t spiffs_obj_lu_find_entry_visitor(
       {
         if ((flags & SPIFFS_VIS_CHECK_ID) == 0 || obj_lu_buf[cur_entry-entry_offset] == obj_id) {
           if (block_ix) *block_ix = cur_block;
-          if (index_entry) *index_entry = cur_entry;
+          if (lu_entry) *lu_entry = cur_entry;
           if (v) {
             res = v(
                 fs,
@@ -291,9 +302,9 @@ s32_t spiffs_obj_lu_scan(
 s32_t spiffs_obj_lu_find_free(
     spiffs *fs,
     spiffs_block_ix starting_block,
-    int starting_index_entry,
+    int starting_lu_entry,
     spiffs_block_ix *block_ix,
-    int *index_entry) {
+    int *lu_entry) {
   s32_t res;
   if (!fs->cleaning && fs->free_blocks < 2) {
     res = spiffs_gc_quick(fs);
@@ -302,12 +313,12 @@ s32_t spiffs_obj_lu_find_free(
       return SPIFFS_ERR_FULL;
     }
   }
-  res = spiffs_obj_lu_find_id(fs, starting_block, starting_index_entry,
-      SPIFFS_OBJ_ID_FREE, block_ix, index_entry);
+  res = spiffs_obj_lu_find_id(fs, starting_block, starting_lu_entry,
+      SPIFFS_OBJ_ID_FREE, block_ix, lu_entry);
   if (res == SPIFFS_OK) {
     fs->free_cursor_block_ix = *block_ix;
-    fs->free_cursor_obj_lu_entry = *index_entry;
-    if (*index_entry == 0) {
+    fs->free_cursor_obj_lu_entry = *lu_entry;
+    if (*lu_entry == 0) {
       fs->free_blocks--;
     }
   }
@@ -323,12 +334,12 @@ s32_t spiffs_obj_lu_find_free(
 s32_t spiffs_obj_lu_find_id(
     spiffs *fs,
     spiffs_block_ix starting_block,
-    int starting_index_entry,
+    int starting_lu_entry,
     spiffs_obj_id obj_id,
     spiffs_block_ix *block_ix,
-    int *index_entry) {
+    int *lu_entry) {
   s32_t res = spiffs_obj_lu_find_entry_visitor(
-      fs, starting_block, starting_index_entry, SPIFFS_VIS_CHECK_ID, obj_id, 0, 0, 0, block_ix, index_entry);
+      fs, starting_block, starting_lu_entry, SPIFFS_VIS_CHECK_ID, obj_id, 0, 0, 0, block_ix, lu_entry);
   if (res == SPIFFS_VIS_END) {
     res = SPIFFS_ERR_NOT_FOUND;
   }
@@ -912,16 +923,16 @@ s32_t spiffs_object_append(spiffs_fd *fd, u32_t offset, u8_t *data, u32_t len) {
     }
 
     // write data
-    u32_t to_spiffs_wr = MIN(len-written, SPIFFS_DATA_PAGE_SIZE(fs) - page_offs);
+    u32_t to_write = MIN(len-written, SPIFFS_DATA_PAGE_SIZE(fs) - page_offs);
     if (page_offs == 0) {
       // at beginning of a page, allocate and write a new page of data
       p_hdr.obj_id = fd->obj_id & ~SPIFFS_OBJ_ID_IX_FLAG;
       p_hdr.span_ix = data_spix;
       p_hdr.flags = 0xff & ~(SPIFFS_PH_FLAG_FINAL);  // finalize immediately
       res = spiffs_page_allocate_data(fs, fd->obj_id & ~SPIFFS_OBJ_ID_IX_FLAG,
-          &p_hdr, &data[written], to_spiffs_wr, page_offs, 1, &data_page);
+          &p_hdr, &data[written], to_write, page_offs, 1, &data_page);
       SPIFFS_DBG("append: %04x store new data page, %04x:%04x offset:%i, len %i, written %i\n", fd->obj_id,
-          data_page, data_spix, page_offs, to_spiffs_wr, written);
+          data_page, data_spix, page_offs, to_write, written);
     } else {
       // append to existing page, fill out free data in existing page
       if (cur_objix_spix == 0) {
@@ -936,9 +947,9 @@ s32_t spiffs_object_append(spiffs_fd *fd, u32_t offset, u8_t *data, u32_t len) {
       SPIFFS_CHECK_RES(res);
 
       res = _spiffs_wr(fs, SPIFFS_OP_T_OBJ_DA | SPIFFS_OP_C_UPDT,
-          fd->file_nbr, SPIFFS_PAGE_TO_PADDR(fs, data_page) + sizeof(spiffs_page_header) + page_offs, to_spiffs_wr, &data[written]);
+          fd->file_nbr, SPIFFS_PAGE_TO_PADDR(fs, data_page) + sizeof(spiffs_page_header) + page_offs, to_write, &data[written]);
       SPIFFS_DBG("append: %04x store to existing data page, %04x:%04x offset:%i, len %i, written %i\n", fd->obj_id
-          , data_page, data_spix, page_offs, to_spiffs_wr, written);
+          , data_page, data_spix, page_offs, to_write, written);
     }
 
     if (res != SPIFFS_OK) break;
@@ -960,7 +971,7 @@ s32_t spiffs_object_append(spiffs_fd *fd, u32_t offset, u8_t *data, u32_t len) {
     // update internals
     page_offs = 0;
     data_spix++;
-    written += to_spiffs_wr;
+    written += to_write;
   } // while all data
 
   fd->size = offset+written;
diff --git a/src/spiffs_nucleus.h b/src/spiffs_nucleus.h
index b32c5fc..b5d5403 100644
--- a/src/spiffs_nucleus.h
+++ b/src/spiffs_nucleus.h
@@ -282,8 +282,11 @@
     if ((ph).span_ix != (spix)) return SPIFFS_ERR_DATA_SPAN_MISMATCH;
 
 
+// check id
 #define SPIFFS_VIS_CHECK_ID     (1<<0)
+// report argument object id to visitor - else object lookup id is reported
 #define SPIFFS_VIS_CHECK_PH     (1<<1)
+// stop searching at end of all look up pages
 #define SPIFFS_VIS_NO_WRAP      (1<<2)
 
 #if SPIFFS_CACHE
@@ -307,27 +310,35 @@
 #define spiffs_get_cache_page(fs, c, ix) \
   ((u8_t *)(&((c)->cpages[(ix) * SPIFFS_CACHE_PAGE_SIZE(fs)])) + sizeof(spiffs_cache_page))
 
+// cache page struct
 typedef struct {
+  // cache flags
   u8_t flags;
+  // cache page index
   u8_t ix;
+  // last access of this cache page
   u32_t last_access;
   union {
+    // type read cache
     struct {
-      // type read cache
+      // read cache page index
       spiffs_page_ix pix;
     };
 #if SPIFFS_CACHE_WR
+    // type write cache
     struct {
-      // type write cache
+      // write cache
       spiffs_obj_id obj_id;
-      u8_t refs;
+      // offset in cache page
       u32_t offset;
+      // size of cache page
       u16_t size;
     };
 #endif
   };
 } spiffs_cache_page;
 
+// cache struct
 typedef struct {
   u8_t cpage_count;
   u32_t last_access;
@@ -400,7 +411,6 @@ typedef struct __attribute(( packed )) {
 } spiffs_page_object_ix;
 
 // callback func for object lookup visitor
-
 typedef s32_t (*spiffs_visitor_f)(spiffs *fs, spiffs_obj_id id, spiffs_block_ix bix, int ix_entry,
     u32_t user_data, void *user_p);
 
@@ -451,14 +461,14 @@ s32_t spiffs_phys_count_free_blocks(
 s32_t spiffs_obj_lu_find_entry_visitor(
     spiffs *fs,
     spiffs_block_ix starting_block,
-    int starting_index_entry,
+    int starting_lu_entry,
     u8_t flags,
     spiffs_obj_id obj_id,
     spiffs_visitor_f v,
     u32_t user_data,
     void *user_p,
     spiffs_block_ix *block_ix,
-    int *index_entry);
+    int *lu_entry);
 
 // ---------------
 
@@ -472,17 +482,17 @@ s32_t spiffs_obj_lu_find_free_obj_id(
 s32_t spiffs_obj_lu_find_free(
     spiffs *fs,
     spiffs_block_ix starting_block,
-    int starting_index_entry,
+    int starting_lu_entry,
     spiffs_block_ix *block_ix,
-    int *index_entry);
+    int *lu_entry);
 
 s32_t spiffs_obj_lu_find_id(
     spiffs *fs,
     spiffs_block_ix starting_block,
-    int starting_index_entry,
+    int starting_lu_entry,
     spiffs_obj_id obj_id,
     spiffs_block_ix *block_ix,
-    int *index_entry);
+    int *lu_entry);
 
 s32_t spiffs_obj_lu_find_id_and_span(
     spiffs *fs,
diff --git a/src/test/params_test.h b/src/test/params_test.h
index 5a9ac36..93e4b87 100644
--- a/src/test/params_test.h
+++ b/src/test/params_test.h
@@ -8,10 +8,13 @@
 #ifndef PARAMS_TEST_H_
 #define PARAMS_TEST_H_
 
-#define FLASH_SIZE    2*1024*1024
-#define SECTOR_SIZE   65536
-#define LOG_BLOCK     65536
-#define LOG_PAGE      256
+#define FLASH_SIZE      2*1024*1024
+#define SECTOR_SIZE     65536
+#define LOG_BLOCK       65536
+#define LOG_PAGE        256
+
+#define FD_BUF_SIZE     32*6
+#define CACHE_BUF_SIZE  (LOG_PAGE + 32)*8
 
 #define ASSERT(c, m) real_assert((c),(m), __FILE__, __LINE__);
 
diff --git a/src/test/test_spiffs.c b/src/test/test_spiffs.c
index cbfac27..6189446 100644
--- a/src/test/test_spiffs.c
+++ b/src/test/test_spiffs.c
@@ -31,8 +31,8 @@ static char _path[256];
 
 spiffs __fs;
 static u8_t _work[LOG_PAGE*2];
-static u8_t _fds[256+256/2];
-static u8_t _cache[(LOG_PAGE+32)*4];
+static u8_t _fds[FD_BUF_SIZE];
+static u8_t _cache[CACHE_BUF_SIZE];
 
 static int check_valid_flash = 1;