From 09819ec373448c539934273d970ba05e4e402573 Mon Sep 17 00:00:00 2001
From: Karl Wiberg <kwiberg@webrtc.org>
Date: Fri, 24 Nov 2017 13:26:32 +0100
Subject: [PATCH] Improve the rtc::Buffer docs

Bug: none
Notry: true
Change-Id: Ie18d2c30617a168eb7cf8b1497e924eeb5083892
Reviewed-on: https://webrtc-review.googlesource.com/25822
Commit-Queue: Karl Wiberg <kwiberg@webrtc.org>
Reviewed-by: Henrik Lundin <henrik.lundin@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#20882}
---
 rtc_base/buffer.h | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/rtc_base/buffer.h b/rtc_base/buffer.h
index 4948aaeff3..eff3e40f0d 100644
--- a/rtc_base/buffer.h
+++ b/rtc_base/buffer.h
@@ -214,13 +214,15 @@ class BufferT {
     SetData(w.data(), w.size());
   }
 
-  // Replace the data in the buffer with at most |max_elements| of data, using
+  // Replaces the data in the buffer with at most |max_elements| of data, using
   // the function |setter|, which should have the following signature:
+  //
   //   size_t setter(ArrayView<U> view)
-  // |setter| is given an appropriately typed ArrayView of the area in which to
-  // write the data (i.e. starting at the beginning of the buffer) and should
-  // return the number of elements actually written. This number must be <=
-  // |max_elements|.
+  //
+  // |setter| is given an appropriately typed ArrayView of length exactly
+  // |max_elements| that describes the area where it should write the data; it
+  // should return the number of elements actually written. (If it doesn't fill
+  // the whole ArrayView, it should leave the unused space at the end.)
   template <typename U = T,
             typename F,
             typename std::enable_if<
@@ -268,13 +270,15 @@ class BufferT {
     AppendData(&item, 1);
   }
 
-  // Append at most |max_elements| to the end of the buffer, using the function
+  // Appends at most |max_elements| to the end of the buffer, using the function
   // |setter|, which should have the following signature:
+  //
   //   size_t setter(ArrayView<U> view)
-  // |setter| is given an appropriately typed ArrayView of the area in which to
-  // write the data (i.e. starting at the former end of the buffer) and should
-  // return the number of elements actually written. This number must be <=
-  // |max_elements|.
+  //
+  // |setter| is given an appropriately typed ArrayView of length exactly
+  // |max_elements| that describes the area where it should write the data; it
+  // should return the number of elements actually written. (If it doesn't fill
+  // the whole ArrayView, it should leave the unused space at the end.)
   template <typename U = T,
             typename F,
             typename std::enable_if<