Update documentation.

Author: h2zero

README.md

@@ -42,7 +42,10 @@ Tested and working with esp32-arduino in Arduino IDE and platform IO.
 
 # Using
 This library is intended to be compatible with the original ESP32 BLE functions and types with minor changes.  
-See: [The migration guide](docs/Migration_guide.md) for details. 
+
+If you have not used the original Bluedroid library please refer to the [New user guide](docs/New_user_guide.md).  
+
+If you are familiar with the original library, see: [The migration guide](docs/Migration_guide.md) for details about breaking changes and migration.  
 
 Also see [Improvements_and_updates](docs/Improvements_and_updates.md) for information about non-breaking changes.
 
@@ -54,7 +57,7 @@ More advanced examples highlighting many available features are in examples/ Nim
 
 Beacon examples provided by @beegee-tokyo are in examples/ BLE_Beacon_Scanner, BLE_EddystoneTLM_Beacon, BLE_EddystoneURL_Beacon.   
 
-Change the settings in the `nimconfig.h` file to customize NimBLE to your project, such as increasing max connections, default is 3.  
+Change the settings in the `src/nimconfig.h` file to customize NimBLE to your project, such as increasing max connections, default is 3.  
 
 **Note To increase max connections in Arduino it is also required to change the controller max connections defined in sdkconfig.h.**  
 

docs/BREAKING_API_CHANGES.md

@@ -1,9 +1,18 @@
 # Improvements and updates
 
+Many improvements have been made to this library vs the original, this is a brief overview of the most significant changes.  
+Refer to the [class documentation](https://h2zero.github.io/esp-nimble-cpp/annotated.html) for futher information on class specifics.  
+
+* [Server](#server)
+* [Client](#client)
+* [General](#general)  
+<br/>
+
+<a name="server"></a>
 # Server  
 
-NimBLECharacteristic::setValue(const T &s)  
-NimBLEDescriptor::setValue(const T &s)  
+`NimBLECharacteristic::setValue(const T &s)`  
+`NimBLEDescriptor::setValue(const T &s)`  
 
 Now use a template to accomodate standard and custom types/values.  
 
@@ -27,7 +36,7 @@ struct my_struct{
  ```
 This will send the struct to the recieving client when read or a notification sent.  
 
-NimBLECharacteristic::getValue now takes an optional timestamp parameter which will update it's value with  
+`NimBLECharacteristic::getValue` now takes an optional timestamp parameter which will update it's value with  
 the time the last value was recieved. In addition an overloaded template has been added to retrieve the value  
 as a type specified by the user.  
 
@@ -51,10 +60,11 @@ it's characteristics / descriptors will remain valid and the service can be re-a
 using `NimBLEServer::addService`.  
 <br/>
 
+<a name="client"></a>
 # Client  
 
-NimBLERemoteCharacteristic::readValue(time_t\*, bool)  
-NimBLERemoteDescriptor::readValue(bool)  
+`NimBLERemoteCharacteristic::readValue(time_t\*, bool)`   
+`NimBLERemoteDescriptor::readValue(bool)`  
 
 Have been added as templates to allow reading the values as any specified type.   
 
@@ -73,14 +83,14 @@ struct my_struct{
 ```  
 <br/>
 
-NimBLERemoteCharacteristic::registerForNotify  
+`NimBLERemoteCharacteristic::registerForNotify`  
 Has been **deprecated** as now the internally stored characteristic value is updated when notification/indication is recieved.  
 
-NimBLERemoteCharacteristic::subscribe and NimBLERemoteCharacteristic::unsubscribe have been implemented to replace it.  
-A callback is no longer requred to get the most recent value unless timing is important. Instead, the application can call NimBLERemoteCharacteristic::getValue to  
+`NimBLERemoteCharacteristic::subscribe` and `NimBLERemoteCharacteristic::unsubscribe` have been implemented to replace it.  
+A callback is no longer requred to get the most recent value unless timing is important. Instead, the application can call `NimBLERemoteCharacteristic::getValue` to  
 get the last updated value any time.  
 
-In addition NimBLERemoteCharacteristic::readValue and NimBLERemoteCharacteristic::getValue take an optional timestamp parameter which will update it's value with  
+In addition `NimBLERemoteCharacteristic::readValue` and `NimBLERemoteCharacteristic::getValue` take an optional timestamp parameter which will update it's value with  
 the time the last value was recieved.  
 
 > NimBLEClient::getService  
@@ -93,24 +103,23 @@ the specified attribute from the peripheral.
 These changes allow more control for the user to manage the resources used for the attributes.    
 <br/>
 
-NimBLEClient::connect() can now be called without an address or advertised device parameter. This will connect to the  
-device with the address previously set when last connected or set with NimBLEDevice::setPeerAddress(). 
+`NimBLEClient::connect()` can now be called without an address or advertised device parameter. This will connect to the  
+device with the address previously set when last connected or set with `NimBLEDevice::setPeerAddress()`. 
 
+<a name="general"></a>
 # General  
-To reduce resource use all instances of std::map have been replaced with std::vector.  
+To reduce resource use all instances of `std::map` have been replaced with `std::vector`.  
 
-Use of FreeRTOS::Semaphore has been removed as it was consuming too much ram, the related files have been left in place to accomodate application use.  
+Use of `FreeRTOS::Semaphore` has been removed as it was consuming too much ram, the related files have been left in place to accomodate application use.  
 
-Operators `==`, `!=` and `std::string` have been added to NimBLEAddress and NimBLEUUID for easier comparison and logging.  
+Operators `==`, `!=` and `std::string` have been added to `NimBLEAddress` and `NimBLEUUID` for easier comparison and logging.  
 
-New constructor for NimBLEUUID(uint32_t, uint16_t, uint16_t, uint64_t) added to lower memory use vs string construction. See: [#21](https://github.com/h2zero/NimBLE-Arduino/pull/21).   
+New constructor for `NimBLEUUID(uint32_t, uint16_t, uint16_t, uint64_t)` added to lower memory use vs string construction. See: [#21](https://github.com/h2zero/NimBLE-Arduino/pull/21).   
 
-Security/pairing operations are now handled in the respective NimBLEClientCallbacks and NimBLEServerCallbacks classes, NimBLESecurity(deprecated) remains for backward compatibility.  
+Security/pairing operations are now handled in the respective `NimBLEClientCallbacks` and `NimBLEServerCallbacks` classes, `NimBLESecurity`(deprecated) remains for backward compatibility.  
 
 Configuration options have been added to add or remove debugging information, when disabled (default) significatly reduces binary size.  
 In ESP-IDF the options are in menuconfig: `Main menu -> ESP-NimBLE-cpp configuration`.  
 For Arduino the options must be commented / uncommented in nimconfig.h.   
-
-Many more internal improvements have been made as well, this is a brief overview. Refer to the class docs for futher information on class specifics.  
 <br/>