Fix comments for doxygen (#16)

* Fix comments for doxygen

* Add documentation and update readme.

src/NimBLEScan.cpp

@@ -151,7 +151,6 @@ NimBLEScan::NimBLEScan() {
  * @brief Should we perform an active or passive scan?
  * The default is a passive scan.  An active scan means that we will wish a scan response.
  * @param [in] active If true, we perform an active scan otherwise a passive scan.
- * @return N/A.
  */
 void NimBLEScan::setActiveScan(bool active) {
     if (active) {
@@ -187,18 +186,18 @@ void NimBLEScan::setLimitedOnly(bool active) {
 /**
  * @brief Sets the scan filter policy.
  * @param [in] filter Can be one of:
- *  BLE_HCI_SCAN_FILT_NO_WL             (0)
- *      Scanner processes all advertising packets (white list not used) except
+ * * BLE_HCI_SCAN_FILT_NO_WL             (0)
+ *      Scanner processes all advertising packets (white list not used) except\n
  *      directed, connectable advertising packets not sent to the scanner.
- *  BLE_HCI_SCAN_FILT_USE_WL            (1)
- *      Scanner processes advertisements from white list only. A connectable,
+ * * BLE_HCI_SCAN_FILT_USE_WL            (1)
+ *      Scanner processes advertisements from white list only. A connectable,\n
  *      directed advertisment is ignored unless it contains scanners address.
- *  BLE_HCI_SCAN_FILT_NO_WL_INITA       (2)
- *      Scanner process all advertising packets (white list not used). A
+ * * BLE_HCI_SCAN_FILT_NO_WL_INITA       (2)
+ *      Scanner process all advertising packets (white list not used). A\n
  *      connectable, directed advertisement shall not be ignored if the InitA
  *      is a resolvable private address.
- *  BLE_HCI_SCAN_FILT_USE_WL_INITA      (3)
- *      Scanner process advertisements from white list only. A connectable,
+ * * BLE_HCI_SCAN_FILT_USE_WL_INITA      (3)
+ *      Scanner process advertisements from white list only. A connectable,\n
  *      directed advertisement shall not be ignored if the InitA is a
  *      resolvable private address.
  */
@@ -221,7 +220,7 @@ void NimBLEScan::setAdvertisedDeviceCallbacks(NimBLEAdvertisedDeviceCallbacks* p
 
 /**
  * @brief Set the interval to scan.
- * @param [in] The interval in msecs.
+ * @param [in] intervalMSecs The scan interval (how often) in milliseconds.
  */
 void NimBLEScan::setInterval(uint16_t intervalMSecs) {
     m_scan_params.itvl = intervalMSecs / 0.625;
@@ -241,7 +240,7 @@ void NimBLEScan::setWindow(uint16_t windowMSecs) {
  * @brief Start scanning.
  * @param [in] duration The duration in seconds for which to scan.
  * @param [in] scanCompleteCB A function to be called when scanning has completed.
- * @param [in] are we continue scan (true) or we want to clear stored devices (false)
+ * @param [in] is_continue Set to true to save previous scan results, false to clear them.
  * @return True if scan started or false if there was an error.
  */
 bool NimBLEScan::start(uint32_t duration, void (*scanCompleteCB)(NimBLEScanResults), bool is_continue) {
@@ -309,7 +308,8 @@ bool NimBLEScan::start(uint32_t duration, void (*scanCompleteCB)(NimBLEScanResul
 /**
  * @brief Start scanning and block until scanning has been completed.
  * @param [in] duration The duration in seconds for which to scan.
- * @return The BLEScanResults.
+ * @param [in] is_continue Set to true to save previous scan results, false to clear them.
+ * @return The NimBLEScanResults.
  */
 NimBLEScanResults NimBLEScan::start(uint32_t duration, bool is_continue) {
     if(duration == 0) {
@@ -330,7 +330,7 @@ NimBLEScanResults NimBLEScan::start(uint32_t duration, bool is_continue) {
 
 /**
  * @brief Stop an in progress scan.
- * @return N/A.
+ * @return True if successful.
  */
 bool NimBLEScan::stop() {
     NIMBLE_LOGD(LOG_TAG, ">> stop()");
@@ -356,7 +356,11 @@ bool NimBLEScan::stop() {
 } // stop
 
 
-// delete peer device from cache after disconnecting, it is required in case we are connecting to devices with not public address
+/**
+ * @brief Delete peer device from the scan results vector.
+ * @param [in] address The address of the device to delete from the results.
+ * @details After disconnecting, it may be required in the case we were connected to a device without a public address.
+ */
 void NimBLEScan::erase(const NimBLEAddress &address) {
     NIMBLE_LOGI(LOG_TAG, "erase device: %s", address.toString().c_str());
 
@@ -371,8 +375,7 @@ void NimBLEScan::erase(const NimBLEAddress &address) {
 
 
 /**
- * @brief If the host reset the scan will have stopped so we should flag it and release the semaphore.
- * @return N/A.
+ * @brief If the host reset the scan will have stopped so we should set the flag as stopped.
  */
 void NimBLEScan::onHostReset() {
     m_stopped = true;
@@ -411,7 +414,7 @@ void NimBLEScanResults::dump() {
 
 
 /**
- * @brief Return the count of devices found in the last scan.
+ * @brief Get the count of devices found in the last scan.
  * @return The number of devices found in the last scan.
  */
 int NimBLEScanResults::getCount() {
@@ -449,7 +452,7 @@ std::vector<NimBLEAdvertisedDevice*>::iterator NimBLEScanResults::end() {
 
 
 /**
- * @brief Return a pointer to the specified device at the given address.
+ * @brief Get a pointer to the specified device at the given address.
  * If the address is not found a nullptr is returned.
  * @param [in] address The address of the device.
  * @return A pointer to the device at the specified address.