improved documentation of template types

Author: seanngpack

README.md

@@ -107,7 +107,6 @@ int main() {
 
 ## Upcoming features:
 - methods to get status of peripherals, characteristics, etc
-- better error logging
 - Windows support
 
 ## Help & bug reports

docs/demo/demo.rst

@@ -248,20 +248,7 @@ thread-safe, this applies to both member and non-member functions.
 
 .. _supported-template-types:
 
-Supported template types
-========================
-
-Primitive:
-
-- uint8_t
-- int
-- float
-- double
-
-Non Primitive:
-
-- std::string
-- std::vector<std::byte>
+.. include:: ../template_types.rst
 
 
 

docs/index.rst

@@ -23,8 +23,8 @@
     :maxdepth: 4
     :hidden:
 
-    API/API
     API/central
     API/peripheral
     API/service
-    API/characteristic
+    API/characteristic
+    template_types

docs/template_types.rst

@@ -0,0 +1,14 @@
+Supported Template Types
+========================
+
+Primitive:
+
+- uint8_t
+- int
+- float
+- double
+
+Non Primitive:
+
+- std::string
+- std::vector<std::byte>

include/characteristic.h

@@ -33,10 +33,15 @@ namespace bluetooth {
 
         /**
          * Read the characteristic.
+         * Compatible template types are listed at `supported template types` section.
          *
+         * Recommended default usage to return a vector of bytes:
+         * `std::vector<std::byte> bytes = some_char->read<std::vector<std::byte>>();`
+         *
+         * You can also return an int if you know your characteristic value is a 4-byte integer in little-endian order:
+         * `int x = some_char->read<int>();`
          * @tparam T the type your want the data to be read as.
          *
-         * @note blocking.
          * @return a byte vector.
          */
         template<typename T>
@@ -46,6 +51,12 @@ namespace bluetooth {
         /**
          * Write to characteristic using a vector of bytes. Will not print error if write fails.
          * You can transmit more data with this method than write_with_response().
+         * Compatible template types are listed at `supported template types` section.
+         *
+         * examples:
+         * `std::vector<std::byte> data = {...};`
+         * `some_char->write_without_response<std::byte>(data);`
+         * `some_char->write_without_response<int>(1);`
          *
          * @note asynchronous.
          * @param data byte vector of your data.
@@ -60,8 +71,14 @@ namespace bluetooth {
         /**
          * Write to characteristic with response. If the write_without_response fails and verbose mode is on,
          * the console will print an error and the program will continue running.
+         * Compatible template types are listed at `supported template types` section.
          *
-         * @param byte vector of your data.
+         * examples:
+         * `std::vector<std::byte> data = {...};`
+         * `some_char->write_with_response<std::byte>(data);`
+         * `some_char->write_with_response<int>(1);`
+         *
+         * @param data byte vector of your data.
          */
         template<typename T>
         void write_with_response(T data);

macOS/src/model/characteristic_impl.cpp

@@ -67,11 +67,7 @@ namespace bluetooth {
         };
         ///@endcond
 
-        /**
-         * Creates instance of specialized template to return either T or vector<T>.
-         * @tparam T type.
-         * @return T or vector<T>
-         */
+
         template<typename T>
         T read() {
             return Getter<T>(this).get();