From 1225362a537bf03e5292854284e51e8521afbf42 Mon Sep 17 00:00:00 2001
From: Abtin Keshavarzian <abtink@google.com>
Date: Wed, 31 May 2017 09:07:45 -0700
Subject: [PATCH] NcpFrameBuffer: Update documentation/comments about in/out
 frame buffer pointers (#1847)

---
 src/ncp/ncp_buffer.hpp | 32 +++++++++++++++++++++++++-------
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/src/ncp/ncp_buffer.hpp b/src/ncp/ncp_buffer.hpp
index 5c414dae5..b5b52f996 100644
--- a/src/ncp/ncp_buffer.hpp
+++ b/src/ncp/ncp_buffer.hpp
@@ -320,6 +320,26 @@ private:
      *     \         /                                                             \         /
      *   Segment #1 Header                                                      Segment #2 Header
      *
+     *
+     * Buffer pointers:
+     *
+     *          mReadFrameStart
+     *          |
+     *          |         mReadSegmentHead                             mWriteFrameStart
+     *          |         |                                            |
+     *          |         |   mReadPointer                             |         mWriteSegmentHead
+     *          |         |   |                                        |         |
+     *  mBuffer |         |   |     mReadSegmentTail                   |         |         mWriteSegmentTail mBufferEnd
+     *  |       |         |   |     |                                  |         |         |                      |
+     *  V       V         V   V     V                                  V         V         V                      V
+     * +-------+---------+---------+-------+--------------------------+---------+---------+----------------------+-
+     * | ...   | Seg 1   | Seg 2   | Seg 3 |   . . .                  | Seg 1   | Seg 2   :   . . .              |
+     * +-------+---------+---------+-------+---------------------------+---------+--------+----------------------+-
+     *         \          \        /       /                           \                  /
+     *         |         Cur segment      |                            |                 |
+     *         |                          |                            |                 |
+     *        Current OutFrame (being read)                      Current InFrame (being written)
+     *
      */
 
     enum
@@ -351,17 +371,15 @@ private:
     uint16_t        ReadUint16At(uint8_t *aBufPtr);
     void            WriteUint16At(uint8_t *aBufPtr, uint16_t aValue);
 
-    otError     InFrameFeedByte(uint8_t aByte);
-    otError     InFrameBeginSegment(void);
+    otError         InFrameFeedByte(uint8_t aByte);
+    otError         InFrameBeginSegment(void);
     void            InFrameEndSegment(uint16_t aSegmentHeaderFlags);
     void            InFrameDiscard(void);
 
-    otError     OutFramePrepareSegment(void);
+    otError         OutFramePrepareSegment(void);
     void            OutFrameMoveToNextSegment(void);
-    otError     OutFramePrepareMessage(void);
-    otError     OutFrameFillMessageBuffer(void);
-
-    // Instance variables
+    otError         OutFramePrepareMessage(void);
+    otError         OutFrameFillMessageBuffer(void);
 
     uint8_t * const  mBuffer;                    // Pointer to the buffer used to store the data.
     uint8_t * const  mBufferEnd;                 // Points to after the end of buffer.