From b59e68a84d9c62729d2c355272bd525b1dcd9356 Mon Sep 17 00:00:00 2001
From: Steve Sanderson <SteveSandersonMS@users.noreply.github.com>
Date: Mon, 5 Feb 2018 17:20:34 +0000
Subject: [PATCH] Clarify why ArrayBuilder<T> exists

---
 src/Microsoft.AspNetCore.Blazor/RenderTree/ArrayBuilder.cs | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/Microsoft.AspNetCore.Blazor/RenderTree/ArrayBuilder.cs b/src/Microsoft.AspNetCore.Blazor/RenderTree/ArrayBuilder.cs
index 4a54e5965c..d11c136fc6 100644
--- a/src/Microsoft.AspNetCore.Blazor/RenderTree/ArrayBuilder.cs
+++ b/src/Microsoft.AspNetCore.Blazor/RenderTree/ArrayBuilder.cs
@@ -8,6 +8,12 @@ namespace Microsoft.AspNetCore.Blazor.RenderTree
 {
     /// <summary>
     /// Implements a list that uses an array of objects to store the elements.
+    /// 
+    /// This differs from a <see cref="System.Collections.Generic.List{T}"/> in that
+    /// it not only grows as required but also shrinks if cleared with significant
+    /// excess capacity. This makes it useful for component rendering, because
+    /// components can be long-lived and re-render frequently, with the rendered size
+    /// varying dramatically depending on the user's navigation in the app.
     /// </summary>
     internal class ArrayBuilder<T>
     {