[OOB 5.10] FATFileSystem examples uses LittleFileSystem

[coisme]

The example program in FATFileSystem reference page uses LittleFileSystem.

[ashok-rao]

@yossi2le @geky .. can you please check this? Thanks. [Mirrored to Jira]

[geky]

Hi @coisme, this repo is used by both FileSystem, LittleFS, and FAT as the filesystem example, and there is instructions on how to change the filesystem: https://github.com/ARMmbed/mbed-os-example-filesystem#changing-the-file-system

Note this is also true for the block device example, which is used as the example for the BlockDevice, SPIFBlockDevice, SDBlockDevice, DataFlashBlockDevice, and FlashIAPBlockDevice.

The current state is confusing because this is really the "FileSystem example", and for it to make sense for a specific implementation (FATFileSystem), it needs the instructions found in the readme. We can't link to GitHub, so the readme needs to be duplicated into the doc site, but AFAIK there's no place for this sort of documented example in the current organization of the doc site.

If we didn't want instructions, we could split these examples into custom examples for each class, but that would add at least 6 new repositories to manage. I looked into making this split automatic, but there were issues with hosting the examples and the idea was dropped.

Another option is creating smaller examples for the implementation classes LittleFS/FAT/SPIFBlockDevice/SDBlockDevice/DataFlashBlockDevice/FlashIAPBlockDevice. It seems these examples don't undergo OOB? (ChainingBlockDevice for example).

Either way, I can't manage 8 examples if it means updating them manually every release. @dannybenor, @yossi2le, and team may be able to in the future (or get automated example splitting working). But I don't think this can be fixed for 5.10. [Mirrored to Jira]

[JojoS62]

I got also confused by LittleFS in FATFS example. Another solution would be a common code with a define as selector, something like this:

//
// select filesystem for this example:
// 0: LittleFS, 1: FATFS
//
#define USE_FS=0   
#if (USE_FS == 0)
LittleFileSystem fs;
#elif (USE_FS == 1)
FATFileSystem fs;
#else
#error "specify filesystem by setting USE_FS"
#endif

[Mirrored to Jira]

[geky]

Although that unfortunately makes the example quite a bit harder to read.

Another option would be to embed the documentation about changing filesystems into a big code comment:

// In Mbed OS, a C++ classes that inherits from the FileSystem interface
// represents each file system. You can change the file system in the
// example by changing the class declared here.
// 
// - LittleFileSystem fs("fs");
// + FATFileSystem fs("fs");
// 
// Note: Different file systems require different minimum numbers of storage
// blocks to function. For the FATFileSystem, this example requires a minimum
// of 256 blocks, and for the LittleFileSystem, this example requires a
// minimum of 6 blocks. You can find the number of blocks on a block device
// by dividing the block device's size by its erase size.
//
// FileSystem declaration
LittleFileSystem fs("fs");

[Mirrored to Jira]

[coisme]

Hi geky, sorry for my slow response, I was on vacation. I prefer the last option, embed the documentation into code. [Mirrored to Jira]