review docu in examples

example/embedded/gap_inquiry.c

@@ -155,6 +155,8 @@ static void packet_handler (uint8_t packet_type, uint8_t *packet, uint16_t size)
                 start_scan();
                 state = ACTIVE;
             }
+            break;
+
         /* @text In ACTIVE, the following events are processed:
          *  - Inquiry result event: the list of discovered devices is processed and the 
          *    Class of Device (CoD), page scan mode, clock offset, and RSSI are stored in a table.
@@ -233,13 +235,20 @@ static void packet_handler (uint8_t packet_type, uint8_t *packet, uint16_t size)
     }
 }
 
-/* @text For more details please check Section DiscoverRemoteDevices in the
- * BTstack manual and the source code.  
+/* @text For more details on discovering remote devices, please see
+ * Section DiscoverRemoteDevices
  */
 
+
+/* @section Main app setup
+ *
+ * @text Listing MainConfiguration shows main application code.
+ * It registers the HCI packet handler and starts the Bluetoth stack
+ */
+
+/* LISTING_START(MainConfiguration): Setup heartbeat timer */
 int btstack_main(int argc, const char * argv[]);
 int btstack_main(int argc, const char * argv[]) {
-    
     hci_register_packet_handler(packet_handler);
 
     // turn on!
@@ -247,4 +256,5 @@ int btstack_main(int argc, const char * argv[]) {
 	    
     return 0;
 }
+/* LISTING_END */
 /* EXAMPLE_END */

example/embedded/led_counter.c

@@ -38,9 +38,8 @@
 // *****************************************************************************
 /* EXAMPLE_START(led_counter): Hello World: blinking LED without Bluetooth
  *
- * @text The example uses the BTstack run loop to blink an LED.
- * The example demonstrates how to provide a periodic timer to toggle an LED
- * and send debug messages to the console as a minimal BTstack test.
+ * @text The example demonstrates how to provide a periodic timer to toggle an
+ * LED and send debug messages to the console as a minimal BTstack test.
  */
 // *****************************************************************************
 
@@ -81,13 +80,10 @@ static void heartbeat_handler(timer_source_t *ts){
 } 
 /* LISTING_END */
 
-/* @section Turn On and Go
+/* @section Main app setup
  *
  * @text Listing MainConfiguration shows main application code.
- * It is called after hardware and BTstack configuration (memory, run loop and
- * transport layer) by the platform main in
- * \path{platforms/PLATFORM/src/main.c}.
- */
+ * It configures the heartbeat tier and adds it to the run loop.
 
 /* LISTING_START(MainConfiguration): Setup heartbeat timer */
 int btstack_main(int argc, const char * argv[]);

example/embedded/sdp_general_query.c

@@ -69,15 +69,13 @@ int attribute_id = -1;
 static uint8_t   attribute_value[1000];
 static const int attribute_value_buffer_size = sizeof(attribute_value);
 
-static bd_addr_t remote = {0x04,0x0C,0xCE,0xE4,0x85,0xD3};
-
 /* @section SDP Client Setup
  *
  * @text SDP is based on L2CAP. To receive SDP query events you must register a
  * callback, i.e. query handler, with the SPD parser, as shown in 
- * Listing SDPClientInit. Via this handler, the SDP client will receive events:
+ * Listing SDPClientInit. Via this handler, the SDP client will receive the following events:
  * - SDP_QUERY_ATTRIBUTE_VALUE containing the results of the query in chunks,
- * - SDP_QUERY_COMPLETE reporting the status and the end of the query. 
+ * - SDP_QUERY_COMPLETE indicating the end of the query and the status
  */
 
 /* LISTING_START(SDPClientInit): SDP client setup */
@@ -96,12 +94,18 @@ static void sdp_client_init(){
 
 /* @section SDP Client Query 
  *
- * @text To get the a list of service records on a remote device, you need to
- * call sdp_general_query_for_uuid() with the remote address and the
+ * @text To trigger an SDP query to get the a list of service records on a remote device,
+ * you need to call sdp_general_query_for_uuid() with the remote address and the
  * UUID of the public browse group, as shown in Listing SDPQueryUUID. 
- * In this example we used fixed address of the remote device.
+ * In this example we used fixed address of the remote device shown in Listing Remote.
+ * Please update it with the address of a device in your vicinity, e.g., one reported
+ * by the GAP Inuiry example in the previous s-e-c-t-i-o-n.
  */ 
 
+/* LISTING_START(Remote): Address of remote device in big-endian order */
+static bd_addr_t remote = {0x04,0x0C,0xCE,0xE4,0x85,0xD3};
+/* LISTING_END */
+
 /* LISTING_START(SDPQueryUUID): Quering a list of service records on a remote device. */
 static void packet_handler (void * connection, uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size){
     // printf("packet_handler type %u, packet[0] %x\n", packet_type, packet[0]);
@@ -127,11 +131,17 @@ static void assertBuffer(int size){
     }
 }
 
-/* @section Handling SDP Client Query Result 
+/* @section Handling SDP Client Query Results 
  *
  * @text The SDP Client returns the results of the query in chunks. Each result
  * packet contains the record ID, the Attribute ID, and a chunk of the Attribute
- * value, see Listing HandleSDPQUeryResult.
+ * value.
+ * In this example, we append new chunks for the same Attribute ID in a large buffer,
+ * see Listing HandleSDPQUeryResult.
+ *
+ * To save memory, it's also possible to process these chunks directly by a custom stream parser,
+ * similar to the way XML files are parsed by a SAX parser. Have a look at \emph{src/sdp_query_rfcomm.c}
+ * which retrieves the RFCOMM channel number and the service name.
  */
 
 /* LISTING_START(HandleSDPQUeryResult): Handling query result chunks. */