From 2258654714cb3cdd7a5fd1a82886e6acae690921 Mon Sep 17 00:00:00 2001
From: Kevin Schoedel <67607049+kpschoedel@users.noreply.github.com>
Date: Mon, 26 Jul 2021 10:12:27 -0400
Subject: [PATCH] Comment changes (#8616)

#### Problem

- Comments in `SystemClock.h` are outdated.
- The various lengths and pointers of a `PacketBuffer` can be hard
  to follow.

#### Change overview

- Fix comments in `SystemClock.h`.
- Add a diagram for `PacketBuffer`.
---
 src/system/SystemClock.h        |  6 +++---
 src/system/SystemPacketBuffer.h | 15 +++++++++++++++
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/src/system/SystemClock.h b/src/system/SystemClock.h
index 741c06be26c4fb..1c6955ad72b015 100644
--- a/src/system/SystemClock.h
+++ b/src/system/SystemClock.h
@@ -51,7 +51,7 @@ namespace Clock {
  *
  * @note
  *   This function is reserved for internal use by the CHIP System Layer.  Users of the CHIP System
- *   Layer should call System::Layer::GetMonotonicMicroseconds().
+ *   Layer should call System::Clock::GetMonotonicMicroseconds().
  *
  * @returns             Elapsed time in microseconds since an arbitrary, platform-defined epoch.
  */
@@ -69,7 +69,7 @@ extern uint64_t GetMonotonicMicroseconds();
  *
  * @note
  *   This function is reserved for internal use by the CHIP System Layer.  Users of the CHIP System
- *   Layer should call System::Layer::GetMonotonicMilliseconds().
+ *   Layer should call System::Clock::GetMonotonicMilliseconds().
  *
  * @returns             Elapsed time in milliseconds since an arbitrary, platform-defined epoch.
  */
@@ -94,7 +94,7 @@ extern uint64_t GetMonotonicMilliseconds();
  *
  * @note
  *   This function is reserved for internal use by the CHIP System Layer.  Users of the CHIP System
- *   Layer should call System::Layer::GetUnixTimeMicroseconds().
+ *   Layer should call System::Clock::GetUnixTimeMicroseconds().
  *
  * @param[out] curTime                  The current time, expressed as Unix time scaled to microseconds.
  *
diff --git a/src/system/SystemPacketBuffer.h b/src/system/SystemPacketBuffer.h
index 44a3bc18b0d774..5e622043eb4582 100644
--- a/src/system/SystemPacketBuffer.h
+++ b/src/system/SystemPacketBuffer.h
@@ -130,6 +130,21 @@ struct pbuf
  *          @ref chip::chipTLVReader
  *          @ref chip::chipTLVWriter
  *
+ * ### PacketBuffer format
+ *
+ * <pre>
+ *           ┌────────────────────────────────────┐
+ *           │       ┌────────────────────┐       │
+ *           │       │                    │◁──────┴───────▷│
+ *  ┏━━━━━━━━┿━━━━━━━┿━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
+ *  ┃ pbuf len payload ┃ reserve          ┃ data           ┃ unused                  ┃
+ *  ┗━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━┛
+ *  │                  │← ReservedSize() →│← DataLength() →│← AvailableDataLength() →│
+ *  │                  │                  │← MaxDataLength() → · · · · · · · · · · ·→│
+ *  │                  │                  Start()                                    │
+ *  │← kStructureSize →│← AllocSize() → · · · · · · · · · · · · · · · · · · · · · · →│
+ * </pre>
+ *
  */
 class DLL_EXPORT PacketBuffer : private pbuf
 {