Add storage contributing overview doc

docs/reference/api/storage/storage.md

@@ -7,15 +7,25 @@ The storage APIs present in Arm Mbed OS are:
 
 #### Declaring a file system
 
-The <a href="https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/FileSystem.h" target="_blank">FileSystem</a> class provides the core API for file system operations. You must provide a block device to back the file system. When you declare a file system with a name, you can open files on the file system through standard POSIX functions (see <a href="http://pubs.opengroup.org/onlinepubs/009695399/functions/open.html" target="_blank">open</a> or <a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fopen.html" target="_blank">fopen</a>).
+The <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/classmbed_1_1_file_system.html" target="_blank">FileSystem</a> class provides the core API for file system operations. You must provide a block device to back the file system. When you declare a file system with a name, you can open files on the file system through the `open` and `fopen` functions.
+
+##### Open
+
+The `open` function creates a connection between a file and a file descriptor. Using a string path argument, you can open a file with a set of option flags. Other functions in Mbed OS can use the file descriptor to track the current position in a file, read and write content and so on.
+
+##### Fopen
+
+The `fopen` function is similar to the open function above but associates a stream with the opened file. This can be helpful when performing mainly sequential read and write operations. However, it is important to flush and close the stream to update the file. This option is weaker when trying to seek through a file often.
+
+The IEEE C standard specifications for both `open` and `fopen` can provide additional information.
 
 Existing file systems:
 
-The <a href="https://github.com/ARMmbed/mbed-os/tree/master/features/filesystem/fat" target="_blank">FAT file system</a> is a standard file system.
+The <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_f_a_t_file_system.html" target="_blank">FAT file system</a> is a standard file system.
 
-The <a href="https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/bd/BlockDevice.h" target="_blank">BlockDevice</a> class provides the underlying API for representing block-based storage that can be used to back a file system. Mbed OS provides standard interfaces for the more common storage media, and you can extend the BlockDevice class to provide support for unsupported storage.
+The <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_block_device.html" target="_blank">BlockDevice</a> class provides the underlying API for representing block-based storage that you can use to back a file system. Mbed OS provides standard interfaces for the more common storage media, and you can extend the BlockDevice class to provide support for unsupported storage.
 
-Additionally, two utility block devices give you better control over how storage is allocated. The <a href="https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/bd/SlicingBlockDevice.h" target="_blank">slicing block device</a> allows you to partition storage into smaller block devices that you can use independently, and the <a href="https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/bd/ChainingBlockDevice.h" target="_blank">chaining block device</a> allows you to chain multiple block devices together and extend the usable amount of storage.
+Additionally, two utility block devices give you better control over how storage is allocated. The <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_slicing_block_device.html" target="_blank">slicing block device</a> allows you to partition storage into smaller block devices that you can use independently, and the <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_chaining_block_device.html" target="_blank">chaining block device</a> allows you to chain multiple block devices together and extend the usable amount of storage.
 
 <span class="notes">**Note:** Some file systems may provide a format function for cleanly initializing a file system on an underlying block device or require external tools to set up the file system before the first use.</span>
 
@@ -27,21 +37,7 @@ Partitioning allows you to split a block device among multiple storage users suc
 
 #### C++ classes
 
-The <a href="https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/FileSystem.h" target="_blank">FileSystem</a> class provides the core user interface with general functions that map to their global POSIX counterparts. Mbed OS provides <a href="https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/File.h" target="_blank">File</a> and <a href="https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/Dir.h" target="_blank">Dir</a> classes that represent files and directories in a C++ API that uses object-oriented features in C++.
-
-To implement a new file system in Mbed OS, an implementor just needs to provide the abstract functions in the file system interface. The <a href="https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/fat/FATFileSystem.cpp" target="_blank">FAT file system</a> provides an excellent example. You can see <a href="https://github.com/ARMmbed/sd-driver/tree/master/features/TESTS/filesystem" target="_blank">tests of the POSIX API</a>.
-
-A minimal file system needs to provide the following functions:
-
-- `file_open`.
-- `file_close`.
-- `file_read`.
-- `file_write`.
-- `file_seek`.
-
-Here is the full API that a filesystem may implement:
-
-[![View code](https://www.mbed.com/embed/?type=library)](https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/FileSystem.h#L205)
+The FileSystem class provides the core user C++ API. Mbed OS provides <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/classmbed_1_1_file.html" target="_blank">File</a> and <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/classmbed_1_1_dir.html" target="_blank">Dir</a> classes that represent files and directories in a C++ API.
 
 #### Block device operations
 
@@ -65,6 +61,6 @@ As a rule of thumb, you can use the erase size for applications that use a singl
 
 Arm Mbed OS contains several utility block devices to give you better control over the allocation of storage.
 
-- With the <a href="https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/bd/SlicingBlockDevice.h" target="_blank">slicing block device</a>, you can partition storage into smaller block devices that you can use independently.
-- With the <a href="https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/bd/ChainingBlockDevice.h" target="_blank">chaining block device</a>, you can chain multiple block devices together and extend the usable amount of storage.
-- Mbed OS comes with support for storing partitions on disk with a Master Boot Record (MBR). The <a href="https://os.mbed.com/docs/v5.6/reference/mbrblockdevice.html" target="_blank">MBRBlockDevice</a> provides this functionality and supports creating partitions at runtime or using pre-formatted partitions configured separately from outside the application.
+- With the <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_slicing_block_device.html" target="_blank">slicing block device</a>, you can partition storage into smaller block devices that you can use independently.
+- With the <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_chaining_block_device.html" target="_blank">chaining block device</a>, you can chain multiple block devices together and extend the usable amount of storage.
+- Mbed OS comes with support for storing partitions on disk with a Master Boot Record (MBR). The <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_m_b_r_block_device.html" target="_blank">MBRBlockDevice</a> provides this functionality and supports creating partitions at runtime or using preformatted partitions configured separately from outside the application.

docs/reference/contributing/storage/storage.md

@@ -1,3 +1,32 @@
 <h2 id="contributing-storage">Storage</h2>
 
-The two storage APIs are BlockDevice and FileSystem. These APIs provide filesystem and file operations on a block device, as well as an interface for access to block-based storage.
+Storage support is split between filesystems and their underlying block device support. The <a href="/docs/v5.6/reference/storage-overview.html" target="_blank">storage API page</a> has more information on existing APIs in Mbed OS for both interfaces.
+
+#### Block Device
+
+Adding a block device implementation is required for backing filesystems on new hardware. You can extend the <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_heap_block_device.html" target="_blank">BlockDevice</a> class to provide support for unsupported storage. 
+
+If you want to port a new filesystem to Mbed OS on existing storage options you can skip to the following section.
+
+#### Filesystems
+
+To implement a new file system in Mbed OS, an implementor needs to provide the abstract functions in the file system interface. The <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_f_a_t_file_system.html" target="_blank">FAT file system</a> provides an excellent example.
+
+A minimal file system needs to provide the following functions:
+
+- `file_open`.
+- `file_close`.
+- `file_read`.
+- `file_write`.
+- `file_seek`.
+
+Here is the full API that a filesystem may implement:
+
+[![View code](https://www.mbed.com/embed/?type=library)](https://github.com/ARMmbed/mbed-os/blob/master/features/filesystem/FileSystem.h#L205)
+
+Filesystems must be backed by a block device in Mbed OS. If you are using supported hardware then you can use the Mbed OS block device classes, otherwise view the block device porting section earlier in this guide.
+
+#### Related content
+
+- <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_heap_block_device.html" target="_blank">BlockDevice</a>.
+- <a href="https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_f_a_t_file_system.html" target="_blank">FAT file system</a>.