Add / fix documentation, change variable names to be clearer, use nullptr rather than 0.

Author: bakercp

src/Encoding/COBS.h

@@ -23,23 +23,22 @@
 /// additional byte per 254 bytes of data). For messages smaller than 254 bytes,
 /// the overhead is constant.
 ///
-/// (via http://www.jacquesf.com/2011/03/consistent-overhead-byte-stuffing/)
-///
 /// \sa http://conferences.sigcomm.org/sigcomm/1997/papers/p062.pdf
 /// \sa http://en.wikipedia.org/wiki/Consistent_Overhead_Byte_Stuffing
 /// \sa https://github.com/jacquesf/COBS-Consistent-Overhead-Byte-Stuffing
-/// \sa http://www.jacquesf.com/2011/03/consistent-overhead-byte-stuffing/
+/// \sa http://www.jacquesf.com/2011/03/consistent-overhead-byte-stuffing
 class COBS
 {
 public:
     /// \brief Encode a byte buffer with the COBS encoder.
-    /// \param source The buffer to encode.
-    /// \param size The size of the buffer to encode.
-    /// \param destination The target buffer for the encoded bytes.
-    /// \returns The number of bytes in the encoded buffer.
-    /// \warning destination must have a minimum capacity of
-    ///     (size + size / 254 + 1).
-    static size_t encode(const uint8_t* source, size_t size, uint8_t* destination)
+    /// \param buffer A pointer to the unencoded buffer to encode.
+    /// \param size  The number of bytes in the \p buffer.
+    /// \param encodedBuffer The buffer for the encoded bytes.
+    /// \returns The number of bytes written to the \p encodedBuffer.
+    /// \warning The encodedBuffer must have at least getEncodedBufferSize() allocated.
+    static size_t encode(const uint8_t* buffer,
+                         size_t size,
+                         uint8_t* encodedBuffer)
     {
         size_t read_index  = 0;
         size_t write_index = 1;
@@ -48,51 +47,54 @@ class COBS
 
         while (read_index < size)
         {
-            if (source[read_index] == 0)
+            if (buffer[read_index] == 0)
             {
-                destination[code_index] = code;
+                encodedBuffer[code_index] = code;
                 code = 1;
                 code_index = write_index++;
                 read_index++;
             }
             else
             {
-                destination[write_index++] = source[read_index++];
+                encodedBuffer[write_index++] = buffer[read_index++];
                 code++;
 
                 if (code == 0xFF)
                 {
-                    destination[code_index] = code;
+                    encodedBuffer[code_index] = code;
                     code = 1;
                     code_index = write_index++;
                 }
             }
         }
 
-        destination[code_index] = code;
+        encodedBuffer[code_index] = code;
 
         return write_index;
     }
 
+
     /// \brief Decode a COBS-encoded buffer.
-    /// \param source The COBS-encoded buffer to decode.
-    /// \param size The size of the COBS-encoded buffer.
-    /// \param destination The target buffer for the decoded bytes.
-    /// \returns The number of bytes in the decoded buffer.
-    /// \warning destination must have a minimum capacity of size.
-    static size_t decode(const uint8_t* source, size_t size, uint8_t* destination)
+    /// \param encodedBuffer A pointer to the \p encodedBuffer to decode.
+    /// \param size The number of bytes in the \p encodedBuffer.
+    /// \param decodedBuffer The target buffer for the decoded bytes.
+    /// \returns The number of bytes written to the \p decodedBuffer.
+    /// \warning decodedBuffer must have a minimum capacity of size.
+    static size_t decode(const uint8_t* encodedBuffer,
+                         size_t size,
+                         uint8_t* decodedBuffer)
     {
         if (size == 0)
             return 0;
 
         size_t read_index  = 0;
         size_t write_index = 0;
-        uint8_t code;
-        uint8_t i;
+        uint8_t code       = 0;
+        uint8_t i          = 0;
 
         while (read_index < size)
         {
-            code = source[read_index];
+            code = encodedBuffer[read_index];
 
             if (read_index + code > size && code != 1)
             {
@@ -103,24 +105,24 @@ class COBS
 
             for (i = 1; i < code; i++)
             {
-                destination[write_index++] = source[read_index++];
+                decodedBuffer[write_index++] = encodedBuffer[read_index++];
             }
 
             if (code != 0xFF && read_index != size)
             {
-                destination[write_index++] = '\0';
+                decodedBuffer[write_index++] = '\0';
             }
         }
 
         return write_index;
     }
 
-    /// \brief Get the maximum encoded buffer size needed for a given source size.
-    /// \param sourceSize The size of the buffer to be encoded.
+    /// \brief Get the maximum encoded buffer size needed for a given unencoded buffer size.
+    /// \param unencodedBufferSize The size of the buffer to be encoded.
     /// \returns the maximum size of the required encoded buffer.
-    static size_t getEncodedBufferSize(size_t sourceSize)
+    static size_t getEncodedBufferSize(size_t unencodedBufferSize)
     {
-        return sourceSize + sourceSize / 254 + 1;
+        return unencodedBufferSize + unencodedBufferSize / 254 + 1;
     }
 
 };

src/Encoding/SLIP.h

@@ -14,24 +14,25 @@
 
 /// \brief A Serial Line IP (SLIP) Encoder.
 ///
-/// Serial Line IP (SLIP) is a packet framing protocol: SLIP defines a
-/// sequence of characters that frame IP packets on a serial line and
-/// nothing more. It provides no addressing, packet type identification,
-/// error detection/correction or compression mechanisms.  Because the
-/// protocol does so little, though, it is usually very easy to
-/// implement.
+/// Serial Line IP (SLIP) is a packet framing protocol: SLIP defines a sequence
+/// of characters that frame IP packets on a serial line and nothing more. It
+/// provides no addressing, packet type identification, error detection,
+/// correction or compression mechanisms. Because the protocol does so little
+/// its implementation is trivial and fast.
 ///
 /// \sa http://tools.ietf.org/html/rfc1055
 class SLIP
 {
 public:
-    /// \brief Encode the given buffer.
-    /// \param buffer A pointer to the buffer to be encoded.
-    /// \param size The size of the buffer pointed to by \p buffer.
-    /// \param encoded A pointer to the target encoded buffer.  This buffer must have sufficient memory allocated.
-    /// \returns The number of bytes written to the encoded \p buffer.
-    /// \warning The encoded buffer must have at least getEncodedBufferSize() allocated.
-    static size_t encode(const uint8_t* buffer, size_t size, uint8_t* encoded)
+    /// \brief Encode a byte buffer with the SLIP encoder.
+    /// \param buffer A pointer to the unencoded buffer to encode.
+    /// \param size  The number of bytes in the \p buffer.
+    /// \param encodedBuffer The buffer for the encoded bytes.
+    /// \returns The number of bytes written to the \p encodedBuffer.
+    /// \warning The encodedBuffer must have at least getEncodedBufferSize() allocated.
+    static size_t encode(const uint8_t* buffer,
+                         size_t size,
+                         uint8_t* encodedBuffer)
     {
         if (size == 0)
             return 0;
@@ -40,38 +41,40 @@ class SLIP
         size_t write_index = 0;
 
         // double-ENDed, flush any data that may have accumulated due to line noise
-        encoded[write_index++] = END;
+        encodedBuffer[write_index++] = END;
 
         while (read_index < size)
         {
             if(buffer[read_index] == END)
             {
-                encoded[write_index++] = ESC;
-                encoded[write_index++] = ESC_END;
+                encodedBuffer[write_index++] = ESC;
+                encodedBuffer[write_index++] = ESC_END;
                 read_index++;
             }
             else if(buffer[read_index] == ESC)
             {
-                encoded[write_index++] = ESC;
-                encoded[write_index++] = ESC_ESC;
+                encodedBuffer[write_index++] = ESC;
+                encodedBuffer[write_index++] = ESC_ESC;
                 read_index++;
             }
             else
             {
-                encoded[write_index++] = buffer[read_index++];
+                encodedBuffer[write_index++] = buffer[read_index++];
             }
         }
 
         return write_index;
     }
 
     /// \brief Decode a SLIP-encoded buffer.
-    /// \param source The SLIP-encoded buffer to decode.
-    /// \param size The size of the SLIP-encoded buffer.
-    /// \param destination The target buffer for the decoded bytes.
-    /// \returns The number of bytes in the decoded buffer.
-    /// \warning destination must have a minimum capacity of size.
-    static size_t decode(const uint8_t* buffer, size_t size, uint8_t* decoded)
+    /// \param encodedBuffer A pointer to the \p encodedBuffer to decode.
+    /// \param size The number of bytes in the \p encodedBuffer.
+    /// \param decodedBuffer The target buffer for the decoded bytes.
+    /// \returns The number of bytes written to the \p decodedBuffer.
+    /// \warning decodedBuffer must have a minimum capacity of size.
+    static size_t decode(const uint8_t* encodedBuffer,
+                         size_t size,
+                         uint8_t* decodedBuffer)
     {
         if (size == 0)
             return 0;
@@ -81,21 +84,21 @@ class SLIP
 
         while (read_index < size)
         {
-            if (buffer[read_index] == END)
+            if (encodedBuffer[read_index] == END)
             {
                 // flush or done
                 read_index++;
             }
-            else if (buffer[read_index] == ESC)
+            else if (encodedBuffer[read_index] == ESC)
             {
-                if (buffer[read_index+1] == ESC_END)
+                if (encodedBuffer[read_index+1] == ESC_END)
                 {
-                    decoded[write_index++] = END;
+                    decodedBuffer[write_index++] = END;
                     read_index += 2;
                 }
-                else if (buffer[read_index+1] == ESC_ESC)
+                else if (encodedBuffer[read_index+1] == ESC_ESC)
                 {
-                    decoded[write_index++] = ESC;
+                    decodedBuffer[write_index++] = ESC;
                     read_index += 2;
                 }
                 else
@@ -105,24 +108,25 @@ class SLIP
             }
             else
             {
-                decoded[write_index++] = buffer[read_index++];
+                decodedBuffer[write_index++] = encodedBuffer[read_index++];
             }
         }
 
         return write_index;
     }
 
-    /// \brief Get the maximum encoded buffer size needed for a given source size.
+    /// \brief Get the maximum encoded buffer size needed for a given unencoded buffer size.
     ///
-    /// SLIP has a start and a end markers (192 and 219).
-    /// Marker value is replaced by 2 bytes in the encoded buffer.
-    /// So in the worst case of sending a buffer with only '192' or '219',
-    /// the encoded buffer length will be 2 * buffer.size() + 2
-    /// \param sourceSize The size of the buffer to be encoded.
+    /// SLIP has a start and a end markers (192 and 219). Marker value is
+    /// replaced by 2 bytes in the encoded buffer. So in the worst case of
+    /// sending a buffer with only '192' or '219', the encoded buffer length
+    /// will be 2 * buffer.size() + 2
+    ///
+    /// \param unencodedBufferSize The size of the buffer to be encoded.
     /// \returns the maximum size of the required encoded buffer.
-    static size_t getEncodedBufferSize(size_t sourceSize)
+    static size_t getEncodedBufferSize(size_t unencodedBufferSize)
     {
-        return sourceSize * 2 + 2;
+        return unencodedBufferSize * 2 + 2;
     }
 
     /// \brief Key constants used in the SLIP protocol.