API doc: DBT/Main refine and add lifecycle + listener; Enhance listener java/c++ doc

5 files changed, 73 insertions, 15 deletions

diff --git a/api/direct_bt/ATTPDUTypes.hpp b/api/direct_bt/ATTPDUTypes.hpp
index a4bf71c7..8024736e 100644
--- a/api/direct_bt/ATTPDUTypes.hpp
+++ b/api/direct_bt/ATTPDUTypes.hpp
@@ -48,9 +48,9 @@
  * Direct-BT shall be suitable for embedded device configurations besides others.
  *
  * Direct-BT implements the following layers
- * - *Basic HCI* via HCIComm for basic connection
- * - *BlueZ Kernel Manager Control Channel* via DBTManager for efficient adapter management
- * - *ATT PDU* AttPDUMsg via L2CAP for low level GATT communication
+ * - *BlueZ Kernel Manager Control Channel* via DBTManager for efficient adapter management and device discovery
+ * - *Basic HCI* via HCIComm for connection
+ * - *ATT PDU* AttPDUMsg via L2CAP for low level packet communication
  * - *GATT Support* via GATTHandler using AttPDUMsg over L2CAPComm, providing
  *   -  GATTService
  *   -  GATTCharacteristic
@@ -63,14 +63,39 @@
  *
  * - - - - - - - - - - - - - - -
  *
- * Form a user perspective the following hierarchy is provided
- * - DBTAdapter has multiple or no
- *   - DBTDevice has multiple or no
- *     -  GATTService has multiple or no
- *       -  GATTService has multiple or no
- *         -  GATTCharacteristic has multiple or no
- *           -  GATTDescriptor
+ * From a user perspective the following hierarchy is provided
+ * - DBTAdapter has no or more
+ *   - DBTDevice has no or more
+ *     - GATTService has no or more
+ *       - GATTCharacteristic has no or more
+ *         - GATTDescriptor
  *
+ * - - - - - - - - - - - - - - -
+ *
+ * Object lifecycle with all instances having a back-references to their owner
+ * - DBTManager singleton instance for all
+ * - DBTAdapter ownership by user
+ *   - DBTDevice ownership by DBTAdapter
+ *     - GATTHandler optional ownership by DBTDevice
+ *
+ * - GATTHandler with DBTDevice reference
+ *   - GATTService ownership by GATTHandler
+ *     - GATTCharacteristic ownership by GATTService
+ *       - GATTDescriptor ownership by GATTCharacteristic
+ *
+ * - - - - - - - - - - - - - - -
+ *
+ * Main event listener can be attached to these objects
+ * which maintain a set of unique listener instances without duplicates.
+ *
+ * - DBTAdapter
+ *   - AdapterStatusListener
+ *
+ * - GATTHandler
+ *   - GATTCharacteristicListener
+ *
+ * Other API attachment method exists for GATTCharacteristicListener,
+ * however, they only exists for convenience and end up to be attached to GATTHandler.
  *
  * - - - - - - - - - - - - - - -
  *
diff --git a/api/direct_bt/DBTAdapter.hpp b/api/direct_bt/DBTAdapter.hpp
index 622bef9a..5b787a7d 100644
--- a/api/direct_bt/DBTAdapter.hpp
+++ b/api/direct_bt/DBTAdapter.hpp
@@ -138,6 +138,17 @@ namespace direct_bt {
     // *************************************************
     // *************************************************
 
+    /**
+     * {@link DBTAdapter} status listener for {@link DBTDevice} discovery events: Added, updated and removed;
+     * as well as for certain {@link DBTAdapter} events.
+     * <p>
+     * A listener instance may be attached to a {@link DBTAdapter} via
+     * {@link DBTAdapter::addStatusListener(std::shared_ptr<AdapterStatusListener>)}.
+     * </p>
+     * <p>
+     * The listener receiver maintains a unique set of listener instances without duplicates.
+     * </p>
+     */
     class AdapterStatusListener {
         public:
             /**
diff --git a/api/direct_bt/GATTCharacteristic.hpp b/api/direct_bt/GATTCharacteristic.hpp
index 74141478..2c41f4f9 100644
--- a/api/direct_bt/GATTCharacteristic.hpp
+++ b/api/direct_bt/GATTCharacteristic.hpp
@@ -304,6 +304,22 @@ namespace direct_bt {
     inline bool operator!=(const GATTCharacteristic& lhs, const GATTCharacteristic& rhs)
     { return !(lhs == rhs); }
 
+    /**
+     * {@link GATTCharacteristic} event listener for notification and indication events.
+     * <p>
+     * A listener instance may be attached to a {@link BluetoothGattCharacteristic} via
+     * {@link GATTCharacteristic::addCharacteristicListener(std::shared_ptr<GATTCharacteristicListener>)} to listen to events,
+     * see method's API doc for {@link GATTCharacteristic} filtering.
+     * </p>
+     * <p>
+     * A listener instance may be attached to a {@link GATTHandler} via
+     * {@link GATTHandler::addCharacteristicListener(std::shared_ptr<GATTCharacteristicListener>)}
+     * to listen to all events of the device or the matching filtered events.
+     * </p>
+     * <p>
+     * The listener receiver maintains a unique set of listener instances without duplicates.
+     * </p>
+     */
     class GATTCharacteristicListener {
         public:
             /**
diff --git a/java/org/tinyb/AdapterStatusListener.java b/java/org/tinyb/AdapterStatusListener.java
index 3101d0df..9d74cc41 100644
--- a/java/org/tinyb/AdapterStatusListener.java
+++ b/java/org/tinyb/AdapterStatusListener.java
@@ -30,18 +30,21 @@ package org.tinyb;
  * as well as for certain {@link BluetoothAdapter} events.
  * <p>
  * A listener instance may be attached to a {@link BluetoothAdapter} via
- * {@link BluetoothAdapter#addStatusListener(BluetoothDeviceDiscoveryListener, BluetoothDevice)}.
+ * {@link BluetoothAdapter#addStatusListener(AdapterStatusListener, BluetoothDevice)}.
  * </p>
  * <p>
- * You can only attach one {@link AdapterStatusListener} instance at a time,
+ * One {@link AdapterStatusListener} instance can only be attached to a listener receiver once at a time,
  * i.e. you cannot attach the same instance more than once to a {@link BluetoothAdapter}.
  * <br>
- * To attach multiple instances, you need to create one instance per attachment.
+ * To attach multiple listener, one instance per attachment must be created.
  * <br>
  * This restriction is due to implementation semantics of strictly associating
  * one Java {@link AdapterStatusListener} instance to one C++ {@code AdapterStatusListener} instance.
  * The latter will be added to the native list of listeners.
  * This class's {@code nativeInstance} field links the Java instance to mentioned C++ listener.
+ * <br>
+ * Since the listener receiver maintains a unique set of listener instances without duplicates,
+ * this restriction is more esoteric.
  * </p>
  */
 public abstract class AdapterStatusListener {
diff --git a/java/org/tinyb/GATTCharacteristicListener.java b/java/org/tinyb/GATTCharacteristicListener.java
index 0c2cae1a..693b5532 100644
--- a/java/org/tinyb/GATTCharacteristicListener.java
+++ b/java/org/tinyb/GATTCharacteristicListener.java
@@ -37,16 +37,19 @@ package org.tinyb;
  * to listen to all events of the device or the matching filtered events.
  * </p>
  * <p>
- * You can only attach one {@link GATTCharacteristicListener} instance at a time,
+ * One {@link GATTCharacteristicListener} instance can only be attached to a listener receiver once at a time,
  * i.e. you cannot attach the same instance more than once to a {@link BluetoothDevice}
  * or {@link BluetoothGattCharacteristic}.
  * <br>
- * To attach multiple instances, you need to create one instance per attachment.
+ * To attach multiple listener, one instance per attachment must be created.
  * <br>
  * This restriction is due to implementation semantics of strictly associating
  * one Java {@link GATTCharacteristicListener} instance to one C++ {@code GATTCharacteristicListener} instance.
  * The latter will be added to the native list of listeners.
  * This class's {@code nativeInstance} field links the Java instance to mentioned C++ listener.
+ * <br>
+ * Since the listener receiver maintains a unique set of listener instances without duplicates,
+ * this restriction is more esoteric.
  * </p>
  */
 public abstract class GATTCharacteristicListener {