Diff: io/MTSBufferedIO.h

Revision:

36:bb6b293c7495

Parent:

17:2d7c4ea7491b

Child:

40:14342c4de476

Child:

45:40745c2036cf

--- a/io/MTSBufferedIO.h	Wed Dec 18 23:05:31 2013 +0000
+++ b/io/MTSBufferedIO.h	Thu Dec 19 16:47:26 2013 +0000
@@ -4,10 +4,25 @@
 #include "mbed.h"
 #include "MTSCircularBuffer.h"
 
+/** This is an abstract class for lightweight buffered io to an underlying
+* data interface. Specifically the inheriting class will need to override
+* both the handle read and handle write functions which transfer data between
+* the classes internal read and write buffers and the physical communications
+* link or its HW buffers.
+*/
 class MTSBufferedIO
 {
 public:
+    /** Creates a new BufferedIO object with the passed in static buffer sizes.
+    * Note that because this class is abstract you cannot construct it directly.
+    * Instead, please construct when of its derived classes like MTSSerial or
+    * MTSSerialFlowControl.
+    */
     MTSBufferedIO(int txBufferSize = 128, int rxBufferSize = 128);
+
+    /** Destructs an MTSBufferedIO object and frees all related resources, including
+    * internal buffers.
+    */
     ~MTSBufferedIO();
 
     int write(char* data, int length);
@@ -19,26 +34,58 @@
 
     template<typename T>
     void attach(T *tptr, void(T::*mptr)(void), int threshold, Vars::RelationalOperator op, Serial::IrqType type);
-    
+
     void attach(void(*fptr)(void), int threshold, Vars::RelationalOperator op, Serial::IrqType type);
 
+    /** This method determines if the Tx or write buffer is empty.
+    *
+    * @returns true if empty, otherwise false.
+    */
     bool txEmpty();
+
+    /** This method determines if the Rx or read buffer is empty.
+    *
+    * @returns true if empty, otherwise false.
+    */
     bool rxEmpty();
+
+    /** This method determines if the Tx or write buffer is full.
+    *
+    * @returns true if full, otherwise false.
+    */
     bool txFull();
+
+    /** This method determines if the Rx or read buffer is full.
+    *
+    * @returns true if full, otherwise false.
+    */
     bool rxFull();
+
+    /** This method clears all the data from the internal Tx or write buffer.
+    */
     void txClear();
+
+    /** This method clears all the data from the internal Rx or read buffer.
+    */
     void rxClear();
-    int txAvailable();
-    int rxAvailable();
-    int txCapacity();
-    int rxCapacity();
 
+    /** This abstract method should be used by the deriving class to transfer
+    * data from the internal write buffer (txBuffer) to the physical interface.
+    * Note that this function is called everytime new data is written to the
+    * txBuffer though one of the write calls.
+    */
     virtual void handleWrite() = 0;
+
+    /** This abstract method should be used by the deriving class to transfer
+    * data from the physical interface ot the internal read buffer (rxBuffer).
+    * Note that this function is never called in this class and typically should
+    * be called as part of a receive data interrupt routine.
+    */
     virtual void handleRead() = 0;
 
 protected:
-    MTSCircularBuffer* txBuffer;
-    MTSCircularBuffer* rxBuffer;
+    MTSCircularBuffer* txBuffer; // Internal write or transmit circular buffer
+    MTSCircularBuffer* rxBuffer; // Internal read or receieve circular buffer
 };
 
 #endif /* MTSBUFFEREDIO_H */
\ No newline at end of file