Add a FS::check() optional method (#6340)

* Add a FS::check() optional method

Fixes #2634

Expose any low-level filesystem check operations for users, and add
documentation on this and the gc() methods.

* Update doc w/more gc() info and link

Author: earlephilhower

cores/esp8266/FS.cpp

@@ -272,6 +272,13 @@ bool FS::gc() {
     return _impl->gc();
 }
 
+bool FS::check() {
+    if (!_impl) {
+        return false;
+    }
+    return _impl->check();
+}
+
 bool FS::format() {
     if (!_impl) {
         return false;

cores/esp8266/FS.h

@@ -221,7 +221,9 @@ class FS
     bool rmdir(const char* path);
     bool rmdir(const String& path);
 
+    // Low-level FS routines, not needed by most applications
     bool gc();
+    bool check();
 
     friend class ::SDClass; // More of a frenemy, but SD needs internal implementation to get private FAT bits
 protected:

cores/esp8266/FSImpl.h

@@ -85,6 +85,7 @@ class FSImpl {
     virtual bool mkdir(const char* path) = 0;
     virtual bool rmdir(const char* path) = 0;
     virtual bool gc() { return true; } // May not be implemented in all file systems.
+    virtual bool check() { return true; } // May not be implemented in all file systems.
 };
 
 } // namespace fs

cores/esp8266/spiffs_api.h

@@ -219,6 +219,11 @@ class SPIFFSImpl : public FSImpl
         return SPIFFS_gc_quick( &_fs, 0 ) == SPIFFS_OK;
     }
 
+    bool check() override
+    {
+        return SPIFFS_check(&_fs) == SPIFFS_OK;
+    }
+
 protected:
     friend class SPIFFSFileImpl;
     friend class SPIFFSDirImpl;

doc/filesystem.rst

@@ -402,6 +402,31 @@ block size - ``pageSize`` — filesystem logical page size - ``maxOpenFiles``
 ``maxPathLength`` — max file name length (including one byte for zero
 termination)
 
+gc
+~~
+
+.. code:: cpp
+
+    SPIFFS.gc()
+
+Only implemented in SPIFFS.  Performs a quick garbage collection operation on SPIFFS,
+possibly making writes perform faster/better in the future.  On very full or very fragmented
+filesystems, using this call can avoid or reduce issues where SPIFFS reports free space
+but is unable to write additional data to a file.  See `this discussion
+<https://github.com/esp8266/Arduino/pull/6340#discussion_r307042268>` for more info.
+
+check
+~~~~~
+
+.. code:: cpp
+
+    SPIFFS.begin();
+    SPIFFS.check();
+
+Only implemented in SPIFFS.  Performs an in-depth check of the filesystem metadata and
+correct what is repairable.  Not normally needed, and not guaranteed to actually fix
+anything should there be corruption.
+
 Directory object (Dir)
 ----------------------