Minor Doxygen fixes for BufferedBlockDevice and iBeacon

Author: offirko

features/FEATURE_BLE/ble/services/iBeacon.h

@@ -1,18 +1,18 @@
 /* mbed Microcontroller Library
- * Copyright (c) 2006-2015 ARM Limited
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+* Copyright (c) 2006-2015 ARM Limited
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
 #ifndef MBED_BLE_IBEACON_H__
 #define MBED_BLE_IBEACON_H__
 
@@ -88,9 +88,9 @@ MBED_DEPRECATED_SINCE(
     "mbed-os-5.11",
     "This service is deprecated, and no replacement is currently available."
 )
-class iBeacon
-{
+class iBeacon {
 public:
+#if !(DOXYGEN_ONLY)
     /**
      * Data buffer of a location UUID.
      */
@@ -176,12 +176,11 @@ class iBeacon
             len(0x15),
             majorNumber(__REV16(majNum)),
             minorNumber(__REV16(minNum)),
-            txPower(transmitPower)
-        {
+            txPower(transmitPower) {
             memcpy(proximityUUID, uuid, sizeof(LocationUUID_t));
         }
     };
-
+#endif //#if !(DOXYGEN_ONLY)
 public:
     /**
      * Construct an iBeacon::Payload and register it into Gap.
@@ -192,14 +191,14 @@ class iBeacon
      * to group their iBeacons into a single network, a single region and
      * identify their organization among others.
      *
-     * @param[in] majNum Beacon major group ID. iBeacon exploitants may use
-     * this field to divide the region into subregions, their network into
+     * @param[in] majNum Beacon major group ID. iBeacon users may use
+     * this field to divide the region into subregions, and their network into
      * subnetworks.
      *
      * @param[in] minNum Identifier of the Beacon in its subregion.
      *
-     * @param[in] txP Measured transmit power of the beacon at 1
-     * meter. Scanners use this parameter to approximate the distance
+     * @param[in] txP Measured transmit power of the beacon at distance of
+     * one meter. Scanners use this parameter to approximate the distance
      * to the beacon.
      *
      * @param[in] compID ID of the beacon manufacturer.

features/storage/blockdevice/BufferedBlockDevice.h

@@ -35,35 +35,36 @@ namespace mbed {
  */
 class BufferedBlockDevice : public BlockDevice {
 public:
-    /** Lifetime of the memory block device
+    /** Create a memory-buffered block device wrapping an underlying block device
      *
      *  @param bd        Block device to back the BufferedBlockDevice
      */
     BufferedBlockDevice(BlockDevice *bd);
 
-    /** Lifetime of a block device
+    /** Destroy the memory-buffered block device
      */
     virtual ~BufferedBlockDevice();
 
-    /** Initialize a block device
+    /** Initialize a buffered-memory block device and its underlying block device
      *
      *  @return         0 on success or a negative error code on failure
      */
     virtual int init();
 
-    /** Deinitialize a block device
+    /** Deinitialize the buffered-memory block device and its underlying block device
      *
      *  @return         0 on success or a negative error code on failure
      */
     virtual int deinit();
 
-    /** Ensure data on storage is in sync with the driver
+    /** Ensure that data on the underlying storage block device is in sync with the
+     *  memory-buffered block device
      *
      *  @return         0 on success or a negative error code on failure
      */
     virtual int sync();
 
-    /** Read blocks from a block device
+    /** Read blocks from the memory-buffered block device
      *
      *  @param buffer   Buffer to read blocks into
      *  @param addr     Address of block to begin reading from
@@ -72,9 +73,9 @@ class BufferedBlockDevice : public BlockDevice {
      */
     virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
 
-    /** Program blocks to a block device
+    /** Program data to the memory-buffered block device
      *
-     *  The blocks must have been erased prior to being programmed
+     *  The write address blocks must be erased prior to being programmed.
      *
      *  @param buffer   Buffer of data to write to blocks
      *  @param addr     Address of block to begin writing to
@@ -83,10 +84,10 @@ class BufferedBlockDevice : public BlockDevice {
      */
     virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
 
-    /** Erase blocks on a block device
+    /** Erase blocks from the memory-buffered block device
      *
      *  The state of an erased block is undefined until it has been programmed,
-     *  unless get_erase_value returns a non-negative byte value
+     *  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
@@ -127,15 +128,15 @@ class BufferedBlockDevice : public BlockDevice {
      */
     virtual bd_size_t get_erase_size() const;
 
-    /** Get the size of an erasable block given address
+    /** Get the size of an erasable block of a given address
      *
      *  @param addr     Address within the erasable block
      *  @return         Size of an erasable block in bytes
      *  @note Must be a multiple of the program size
      */
     virtual bd_size_t get_erase_size(bd_addr_t addr) const;
 
-    /** Get the value of storage when erased
+    /** Get the value of storage data after being erased
      *
      *  If get_erase_value returns a non-negative byte value, the underlying
      *  storage is set to that value when erased, and storage containing
@@ -152,9 +153,9 @@ class BufferedBlockDevice : public BlockDevice {
      */
     virtual bd_size_t size() const;
 
-    /** Get the BlockDevice class type.
+    /** Get the underlying BlockDevice class type
      *
-     *  @return         A string represent the BlockDevice class type.
+     *  @return         A string representing the underlying BlockDevice class type
      */
     virtual const char *get_type() const;
 
@@ -170,6 +171,7 @@ class BufferedBlockDevice : public BlockDevice {
     uint32_t _init_ref_count;
     bool _is_initialized;
 
+#if !(DOXYGEN_ONLY)
     /** Flush data in cache
      *
      *  @return         0 on success or a negative error code on failure
@@ -181,7 +183,7 @@ class BufferedBlockDevice : public BlockDevice {
      *  @return         none
      */
     void invalidate_write_cache();
-
+#endif //#if !(DOXYGEN_ONLY)
 };
 } // namespace mbed