Cleaning up/adding missing comments within examples. (#58)

aentinger · web-flow · commit 33fb1ce20977 · 2021-12-06T15:18:18.000+01:00
This is done in order to put clearer into context what actually is happening.
diff --git a/examples/Breaks_6/Breaks_6.ino b/examples/Breaks_6/Breaks_6.ino
@@ -1,3 +1,7 @@
+/* This example is in fact expected to break, since we try
+ * to access a thread-private variable.
+ */
+
 #include <Arduino_Threads.h>
 
 void setup()
diff --git a/examples/Threading_Basics/Shared_Counter/Consumer.inot b/examples/Threading_Basics/Shared_Counter/Consumer.inot
@@ -6,5 +6,11 @@ void setup()
 
 void loop()
 {
+  /* If a value is available for reading within the internal
+   * queue then the value is removed from the queue and made
+   * available to the calling function. Should no data be
+   * available, then this thread is suspended until new data
+   * is available for reading.
+   */
   Serial.println(counter);
 }
diff --git a/examples/Threading_Basics/Shared_Counter/Producer.inot b/examples/Threading_Basics/Shared_Counter/Producer.inot
@@ -6,6 +6,10 @@ void setup()
 void loop()
 {
   static int i = 0;
+  /* Every 100 ms a new value is inserted into the shared variable
+   * 'counter'. Internally this is stored within a queue in a FIFO
+   * (First-In/First-Out) manner.
+   */
   counter = i;
   i++;
   delay(100);
diff --git a/examples/Threading_Basics/Shared_Counter/SharedVariables.h b/examples/Threading_Basics/Shared_Counter/SharedVariables.h
@@ -1 +1,2 @@
+/* Define a shared variable named 'counter' of type 'int'. */
 SHARED(counter, int);
diff --git a/examples/Threading_Basics/Shared_Counter/Shared_Counter.ino b/examples/Threading_Basics/Shared_Counter/Shared_Counter.ino
@@ -1,3 +1,8 @@
+/* This example demonstrates data exchange between
+ * threads using a shared counter variable defined
+ * within 'SharedVariables.h'.
+ */
+
 void setup()
 {
   Producer.start();
diff --git a/examples/Threading_Basics/Source_Sink_Counter/Consumer.inot b/examples/Threading_Basics/Source_Sink_Counter/Consumer.inot
@@ -1,3 +1,4 @@
+/* Define a data sink named 'counter' of type 'int' with a internal queue size of 10. */
 SINK(counter, int, 10);
 
 void setup()
diff --git a/examples/Threading_Basics/Source_Sink_Counter/Producer.inot b/examples/Threading_Basics/Source_Sink_Counter/Producer.inot
@@ -1,3 +1,4 @@
+/* Define a data source named 'counter' of type 'int'. */
 SOURCE(counter, int);
 
 void setup()
diff --git a/examples/Threading_Basics/Source_Sink_Counter/Source_Sink_Counter.ino b/examples/Threading_Basics/Source_Sink_Counter/Source_Sink_Counter.ino
@@ -1,7 +1,6 @@
-/*
- * This examples demonstrates the SOURCE/SINK abstraction.
- * Each thread may have any number of SOURCES and SINKS that can be connected
- * together using the "connectTo" method.
+/* This examples demonstrates the SOURCE/SINK abstraction. Each thread
+ * may have any number of SOURCES and SINKS that can be connected
+ * together using the 'connectTo' method.
  */
 
 void setup()
diff --git a/examples/Threading_Basics/Source_Sink_LED/Sink_Thread.inot b/examples/Threading_Basics/Source_Sink_LED/Sink_Thread.inot
@@ -1,8 +1,4 @@
-
-/*
- * An 'bool' SINK with a size of '0'. This kind of SINK has no buffer so the reading thread
- * will block until the writing thread has written something, or vice versa.
- */
+/* Define a data sink named 'led' of type 'bool' with a internal queue size of 1. */
 SINK(led, bool);
 
 void setup()
@@ -12,9 +8,9 @@ void setup()
 
 void loop()
 {
-  /* Read a 'bool' from the SINK and discard it. Since there is basically no delay in the loop
-   * this call will surely block until something comes from the connected SOURCE. In this case
-   * the pace is dictated by the SOURCE that sends data every 100 ms.
+  /* Read a 'bool' value from the SINK and discard it. Since there is no delay in the loop
+   * this call will block until new data is inserted from the connected SOURCE. This means
+   * that the pace is dictated by the SOURCE that sends data every 100 ms.
    */
   digitalWrite(LED_BUILTIN, led);
 }
diff --git a/examples/Threading_Basics/Source_Sink_LED/Source_Sink_LED.ino b/examples/Threading_Basics/Source_Sink_LED/Source_Sink_LED.ino
@@ -1,7 +1,6 @@
-/*
- * This examples demonstrates the SOURCE/SINK abstraction.
- * Each thread may have any number of SOURCES and SINKS that can be connected
- * together using the "connectTo" method.
+/* This examples demonstrates the SOURCE/SINK abstraction. Each thread
+ * may have any number of SOURCES and SINKS that can be connected
+ * together using the 'connectTo' method.
  */
 
 void setup()
diff --git a/examples/Threading_Basics/Source_Sink_LED/Source_Thread.inot b/examples/Threading_Basics/Source_Sink_LED/Source_Thread.inot
@@ -1,4 +1,4 @@
-/* The output SOURCE, it sends 'bool' values. */
+/* Define a data source named 'led' of type 'bool'. */
 SOURCE(led, bool);
 
 void setup()
diff --git a/examples/Threadsafe_IO/SPI/SPI.ino b/examples/Threadsafe_IO/SPI/SPI.ino
@@ -1,3 +1,9 @@
+/* This example demonstrates how multiple threads can communicate
+ * with a single SPI client device using the BusDevice abstraction
+ * for SPI. In a similar way multiple threads can interface
+ * with different client devices on the same SPI bus.
+ */
+
 /**************************************************************************************
  * INCLUDE
  **************************************************************************************/
diff --git a/examples/Threadsafe_IO/SPI_BusIO/SPI_BusIO.ino b/examples/Threadsafe_IO/SPI_BusIO/SPI_BusIO.ino
@@ -1,3 +1,12 @@
+/* This example demonstrates how multiple threads can communicate
+ * with a single SPI client device using the BusDevice abstraction
+ * for SPI. In a similar way multiple threads can interface
+ * with different client devices on the same SPI bus.
+ *
+ * This example uses Adafruit_BusIO style read(), write(),
+ * write_then_read() APIs.
+ */
+
 /**************************************************************************************
  * INCLUDE
  **************************************************************************************/
diff --git a/examples/Threadsafe_IO/Serial_GlobalPrefixSuffix/Serial_GlobalPrefixSuffix.ino b/examples/Threadsafe_IO/Serial_GlobalPrefixSuffix/Serial_GlobalPrefixSuffix.ino
@@ -1,3 +1,10 @@
+/* This example demonstrates how every Serial message can be prefixed
+ * as well as suffixed by a user-configurable message. In this example
+ * this functionality is used for appending the current timestamp and
+ * prepending a line feed. Other uses might be to prepend the thread
+ * from which a given serial message is originating.
+ */
+
 /**************************************************************************************
  * INCLUDE
  **************************************************************************************/
diff --git a/examples/Threadsafe_IO/Serial_ProtocolWrapping/Serial_ProtocolWrapping.ino b/examples/Threadsafe_IO/Serial_ProtocolWrapping/Serial_ProtocolWrapping.ino
@@ -1,3 +1,10 @@
+/* This example demonstrates how every Serial message can be prefixed
+ * as well as suffixed by a user-configurable message. In this example
+ * this functionality is used for prepending the right header for a
+ * pseudo NMEA-encoded (think GPS) message as well as for calculating
+ * and appending the checksum at the end.
+ */
+
 /**************************************************************************************
  * INCLUDE
  **************************************************************************************/
diff --git a/examples/Threadsafe_IO/Serial_Reader/Serial_Reader.ino b/examples/Threadsafe_IO/Serial_Reader/Serial_Reader.ino
@@ -1,3 +1,9 @@
+/* This example demonstrates how multiple threads can subscribe to
+ * reading from the same physical Serial interface. Incoming data
+ * is copied into per-thread receive buffers so that no thread
+ * can "steal" data from another thread by reading it first.
+ */
+
 /**************************************************************************************
  * INCLUDE
  **************************************************************************************/
diff --git a/examples/Threadsafe_IO/Serial_Writer/Serial_Writer.ino b/examples/Threadsafe_IO/Serial_Writer/Serial_Writer.ino
@@ -1,3 +1,8 @@
+/* This example demonstrates how multiple threads can write to
+ * the same physical Serial interface without interfering with
+ * one another.
+ */
+
 /**************************************************************************************
  * INCLUDE
  **************************************************************************************/
diff --git a/examples/Threadsafe_IO/Wire/Wire.ino b/examples/Threadsafe_IO/Wire/Wire.ino
@@ -1,3 +1,9 @@
+/* This example demonstrates how multiple threads can communicate
+ * with a single Wire client device using the BusDevice abstraction
+ * for Wire. In a similar way multiple threads can interface
+ * with different client devices on the same Wire bus.
+ */
+
 /**************************************************************************************
  * INCLUDE
  **************************************************************************************/
diff --git a/examples/Threadsafe_IO/Wire_BusIO/Wire_BusIO.ino b/examples/Threadsafe_IO/Wire_BusIO/Wire_BusIO.ino
@@ -1,4 +1,13 @@
- /**************************************************************************************
+/* This example demonstrates how multiple threads can communicate
+ * with a single Wire client device using the BusDevice abstraction
+ * for Wire. In a similar way multiple threads can interface
+ * with different client devices on the same Wire bus.
+ *
+ * This example uses Adafruit_BusIO style read(), write(),
+ * write_then_read() APIs.
+ */
+
+/**************************************************************************************
  * INCLUDE
  **************************************************************************************/
 

Original file line number	Diff line number	Diff line change
`@@ -6,5 +6,11 @@ void setup()`
`6`	`6`
`7`	`7`	`void loop()`
`8`	`8`	`{`
	`9`	`+ /* If a value is available for reading within the internal`
	`10`	`+ * queue then the value is removed from the queue and made`
	`11`	`+ * available to the calling function. Should no data be`
	`12`	`+ * available, then this thread is suspended until new data`
	`13`	`+ * is available for reading.`
	`14`	`+ */`
`9`	`15`	`Serial.println(counter);`
`10`	`16`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
	`1`	`+/* Define a shared variable named 'counter' of type 'int'. */`
`1`	`2`	`SHARED(counter, int);`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,8 @@`
	`1`	`+/* This example demonstrates data exchange between`
	`2`	`+ * threads using a shared counter variable defined`
	`3`	`+ * within 'SharedVariables.h'.`
	`4`	`+ */`
	`5`	`+`
`1`	`6`	`void setup()`
`2`	`7`	`{`
`3`	`8`	`Producer.start();`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/* Define a data sink named 'counter' of type 'int' with a internal queue size of 10. */`
`1`	`2`	`SINK(counter, int, 10);`
`2`	`3`
`3`	`4`	`void setup()`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/* Define a data source named 'counter' of type 'int'. */`
`1`	`2`	`SOURCE(counter, int);`
`2`	`3`
`3`	`4`	`void setup()`