Merge pull request #9334 from yossi2le/yossi_write-a-thon2

Doxygen fixes in block devices

features/storage/blockdevice/BlockDevice.h

@@ -49,12 +49,12 @@ public:
 
     /** Return the default block device
      *
-     * Returns the default BlockDevice base on configuration json.
+     * Returns the default block device based on the configuration JSON.
      * Use the components in target.json or application config to change
      * the default block device.
      *
      * An application can override all target settings by implementing
-     * BlockDevice::get_default_instance() themselves - the default
+     * BlockDevice::get_default_instance() - the default
      * definition is weak, and calls get_target_default_instance().
     */
     static BlockDevice *get_default_instance();
@@ -90,8 +90,8 @@ public:
      *
      *  @param buffer   Buffer to write blocks to
      *  @param addr     Address of block to begin reading from
-     *  @param size     Size to read in bytes, must be a multiple of read block size
+     *  @param size     Size to read in bytes, must be a multiple of the read block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int read(void *buffer, bd_addr_t addr, bd_size_t size) = 0;
 
@@ -103,8 +103,8 @@ public:
      *
      *  @param buffer   Buffer of data to write to blocks
      *  @param addr     Address of block to begin writing to
-     *  @param size     Size to write in bytes, must be a multiple of program block size
+     *  @param size     Size to write in bytes, must be a multiple of the program block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size) = 0;
 
@@ -114,8 +114,8 @@ public:
      *  unless get_erase_value returns a non-negative byte value
      *
      *  @param addr     Address of block to begin erasing
-     *  @param size     Size to erase in bytes, must be a multiple of erase block size
+     *  @param size     Size to erase in bytes, must be a multiple of the erase block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int erase(bd_addr_t addr, bd_size_t size)
     {
@@ -130,8 +130,8 @@ public:
      *  the device is not busy.
      *
      *  @param addr     Address of block to mark as unused
-     *  @param size     Size to mark as unused in bytes, must be a multiple of erase block size
+     *  @param size     Size to mark as unused in bytes, must be a multiple of the erase block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int trim(bd_addr_t addr, bd_size_t size)
     {
@@ -179,7 +179,7 @@ public:
      *  that value can be programmed without another erase.
      *
      *  @return         The value of storage when erased, or -1 if you can't
-     *                  rely on the value of erased storage
+     *                  rely on the value of the erased storage
      */
     virtual int get_erase_value() const
     {

features/storage/blockdevice/MBRBlockDevice.h

@@ -41,52 +41,6 @@ enum {
 /** Block device for managing a Master Boot Record
  *  https://en.wikipedia.org/wiki/Master_boot_record
  *
- *  Here is an example of partitioning a heap backed block device
- *  @code
- *  #include "mbed.h"
- *  #include "HeapBlockDevice.h"
- *  #include "MBRBlockDevice.h"
- *
- *  // Create a block device with 64 blocks of size 512
- *  HeapBlockDevice mem(64*512, 512);
- *
- *  // Partition into two partitions with ~half the blocks
- *  MBRBlockDevice::partition(&mem, 1, 0x83, 0*512, 32*512);
- *  MBRBlockDevice::partition(&mem, 2, 0x83, 32*512);
- *
- *  // Create a block device that maps to the first 32 blocks (excluding MBR block)
- *  MBRBlockDevice part1(&mem, 1);
- *
- *  // Create a block device that maps to the last 32 blocks
- *  MBRBlockDevice part2(&mem, 2);
- *  @endcode
- *
- *  Here is a more realistic example where the MBRBlockDevice is used
- *  to partition a region of space on an SD card. When plugged into a computer,
- *  the partitions will be recognized appropriately.
- *  @code
- *  #include "mbed.h"
- *  #include "SDBlockDevice.h"
- *  #include "MBRBlockDevice.h"
- *  #include "FATFileSystem.h"
- *
- *  // Create an SD card
- *  SDBlockDevice sd(s0, s1, s2, s3);
- *
- *  // Create a partition with 1 GB of space
- *  MBRBlockDevice::partition(&sd, 1, 0x83, 0, 1024*1024);
- *
- *  // Create the block device that represents the partition
- *  MBRBlockDevice part1(&sd, 1);
- *
- *  // Format the partition with a FAT filesystem
- *  FATFileSystem::format(&part1);
- *
- *  // Create the FAT filesystem instance, files can now be written to
- *  // the FAT filesystem in partition 1
- *  FATFileSystem fat("fat", &part1);
- *  @endcode
- *
  *  @note
  *  The MBR partition table is relatively limited:
  *  - At most 4 partitions are supported
@@ -98,12 +52,12 @@ public:
      *
      *  @param bd       Block device to partition
      *  @param part     Partition to use, 1-4
-     *  @param type     8-bit partition type to identitfy partition's contents
+     *  @param type     8-bit partition type to identify partition contents
-     *  @param start    Start block address to map to block 0 of partition,
+     *  @param start    Start block address to map to block 0 of partition.
-     *                  negative addresses are calculated from the end of the
+     *                  Negative addresses are calculated from the end of the
      *                  underlying block devices. Block 0 is implicitly ignored
      *                  from the range to store the MBR.
-     *  @return         0 on success or a negative error code on failure
+     *  @return         0 on success or a negative error code on failure.
      *  @note This is the same as partition(bd, part, type, start, bd->size())
      */
     static int partition(BlockDevice *bd, int part, uint8_t type, bd_addr_t start);
@@ -112,15 +66,15 @@ public:
      *
      *  @param bd       Block device to partition
      *  @param part     Partition to use, 1-4
-     *  @param type     8-bit partition type to identitfy partition's contents
+     *  @param type     8-bit partition type to identify partition contents
      *  @param start    Start block address to map to block 0 of partition,
      *                  negative addresses are calculated from the end of the
      *                  underlying block devices. Block 0 is implicitly ignored
      *                  from the range to store the MBR.
-     *  @param stop     End block address to mark the end of the partition,
+     *  @param stop     End block address to mark the end of the partition.
-     *                  this block is not mapped, negative addresses are calculated
+     *                  This block is not mapped: negative addresses are calculated
      *                  from the end of the underlying block device.
-     *  @return         0 on success or a negative error code on failure
+     *  @return         0 on success or a negative error code on failure.
      */
     static int partition(BlockDevice *bd, int part, uint8_t type, bd_addr_t start, bd_addr_t stop);
 
@@ -158,7 +112,7 @@ public:
      *  @param buffer   Buffer to read blocks into
      *  @param addr     Address of block to begin reading from
      *  @param size     Size to read in bytes, must be a multiple of read block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
 
@@ -169,7 +123,7 @@ public:
      *  @param buffer   Buffer of data to write to blocks
      *  @param addr     Address of block to begin writing to
      *  @param size     Size to write in bytes, must be a multiple of program block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
 
@@ -180,7 +134,7 @@ public:
      *
      *  @param addr     Address of block to begin erasing
      *  @param size     Size to erase in bytes, must be a multiple of erase block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int erase(bd_addr_t addr, bd_size_t size);
 

features/storage/blockdevice/ProfilingBlockDevice.h

@@ -32,22 +32,6 @@ namespace mbed {
 
 
 /** Block device for measuring storage operations of another block device
- *
- *  @code
- *  #include "mbed.h"
- *  #include "HeapBlockDevice.h"
- *  #include "ProfilingBlockDevice.h"
- *
- *  // Create a heap block device and profiling block device
- *  HeapBlockDevice mem(64*512, 512);
- *  ProfilingBlockDevice profiler(&mem);
- *
- *  // do block device work....
- *
- *  printf("read count: %lld\n", profiler.get_read_count());
- *  printf("program count: %lld\n", profiler.get_program_count());
- *  printf("erase count: %lld\n", profiler.get_erase_count());
- *  @endcode
  */
 class ProfilingBlockDevice : public BlockDevice {
 public:
@@ -86,7 +70,7 @@ public:
      *  @param buffer   Buffer to read blocks into
      *  @param addr     Address of block to begin reading from
      *  @param size     Size to read in bytes, must be a multiple of read block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
 
@@ -97,7 +81,7 @@ public:
      *  @param buffer   Buffer of data to write to blocks
      *  @param addr     Address of block to begin writing to
      *  @param size     Size to write in bytes, must be a multiple of program block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
 
@@ -108,7 +92,7 @@ public:
      *
      *  @param addr     Address of block to begin erasing
      *  @param size     Size to erase in bytes, must be a multiple of erase block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int erase(bd_addr_t addr, bd_size_t size);
 

features/storage/blockdevice/SlicingBlockDevice.h

@@ -32,24 +32,6 @@
 namespace mbed {
 
 /** Block device for mapping to a slice of another block device
- *
- *  @code
- *  #include "mbed.h"
- *  #include "HeapBlockDevice.h"
- *  #include "SlicingBlockDevice.h"
- *
- *  // Create a block device with 64 blocks of size 512
- *  HeapBlockDevice mem(64*512, 512);
- *
- *  // Create a block device that maps to the first 32 blocks
- *  SlicingBlockDevice slice1(&mem, 0*512, 32*512);
- *
- *  // Create a block device that maps to the last 32 blocks
- *  SlicingBlockDevice slice2(&mem, 32*512);
- *
- *  // Create a block device that maps to the middle 32 blocks
- *  SlicingBlockDevice slice3(&mem, 16*512, -16*512);
- * @endcode
  */
 class SlicingBlockDevice : public BlockDevice {
 public:
@@ -92,7 +74,7 @@ public:
      *  @param buffer   Buffer to read blocks into
      *  @param addr     Address of block to begin reading from
      *  @param size     Size to read in bytes, must be a multiple of read block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
 
@@ -103,7 +85,7 @@ public:
      *  @param buffer   Buffer of data to write to blocks
      *  @param addr     Address of block to begin writing to
      *  @param size     Size to write in bytes, must be a multiple of program block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
 
@@ -114,7 +96,7 @@ public:
      *
      *  @param addr     Address of block to begin erasing
      *  @param size     Size to erase in bytes, must be a multiple of erase block size
-     *  @return         0 on success, negative error code on failure
+     *  @return         0 on success or a negative error code on failure
      */
     virtual int erase(bd_addr_t addr, bd_size_t size);