Merge pull request #9333 from offirko/offir_doxygen

Minor Doxygen fixes for BufferedBlockDevice and iBeacon

Author: Cruz Monrreal

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__
 
@@ -28,8 +28,8 @@
  * number generally used to determine the location of devices or physical objects
  * near a mobile phone user.
  *
- * iOS scans for iBeacon devices in a background task and notifies Apps
- * subscribed to a specific region when the area is entered or left. Apps may
+ * iOS scans for iBeacon devices in a background task and notifies apps
+ * that subscribe to a specific region when a device enters or leaves an area. Apps may
  * use this information to display context-aware content to users.
  *
  * As an example, a museum can deploy an app that informs the user when one of
@@ -48,7 +48,7 @@
  * of iBeacons in relevant touristic locations it operates. The UUID may
  * identify a place managed by the city. The major ID would identify the place;
  * it can be a museum, a historic monument, a metro station and so on. The minor ID
- * would locate a specific spot within a specific city place. It can be a
+ * would identify a specific spot within a specific city place. It can be a
  * piece of art, a ticket dispenser or a relevant point of interest.
  *
  * Each iBeacon device is physically attached to the spot it locates and
@@ -78,7 +78,7 @@
  *
  * @attention If you are interested in manufacturing iBeacons, you must obtain a
  * license from Apple. More information at https://developer.apple.com/ibeacon/.
- * The licence also grant access to the iBeacons technical specification.
+ * The license also grant access to the iBeacons technical specification.
  *
  * @note More information at https://developer.apple.com/ibeacon/Getting-Started-with-iBeacon.pdf
  *
@@ -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.
      */
@@ -116,12 +116,12 @@ class iBeacon
             uint16_t companyID;
 
             /**
-             * Packet ID; Equal to 2 for an iBeacon.
+             * Packet ID; equal to 2 for an iBeacon.
              */
             uint8_t ID;
 
             /**
-             * Length of the remaining data presents in the payload.
+             * Length of the remaining data present in the payload.
              */
             uint8_t len;
 
@@ -131,7 +131,7 @@ class iBeacon
             uint8_t proximityUUID[16];
 
             /**
-             * Beacon Major group ID.
+             * Beacon major group ID.
              */
             uint16_t majorNumber;
 
@@ -150,11 +150,11 @@ class iBeacon
          * Assemble an iBeacon payload.
          *
          * @param[in] uuid Beacon network ID. iBeacon operators use this value
-         * to group their iBeacons into a single network, a single region and
+         * 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
+         * this field to divide the region into subregions, and their network into
          * subnetworks.
          *
          * @param[in] minNum Identifier of the Beacon in its subregion.
@@ -181,25 +181,25 @@ class iBeacon
             memcpy(proximityUUID, uuid, sizeof(LocationUUID_t));
         }
     };
-
+#endif //#if !(DOXYGEN_ONLY)
 public:
     /**
      * Construct an iBeacon::Payload and register it into Gap.
      *
      * @param[in] _ble The BLE interface to configure with the iBeacon payload.
      *
      * @param[in] uuid Beacon network ID. iBeacon operators use this value
-     * to group their iBeacons into a single network, a single region and
+     * 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 fleet operators 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
+    /** Lifetime of 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
+    /** Lifetime of 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