From 746512dc4c932444e292588c5b379e956882083c Mon Sep 17 00:00:00 2001
From: Daniel Cazzulino <daniel@cazzulino.com>
Date: Sat, 2 Nov 2019 23:19:40 -0300
Subject: [PATCH] Add documentation on
 ISupportInitialize/ISupportInitializeNotification (#286)

---
 Terminal.Gui/Core.cs | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Terminal.Gui/Core.cs b/Terminal.Gui/Core.cs
index 872761afe..465f036e3 100644
--- a/Terminal.Gui/Core.cs
+++ b/Terminal.Gui/Core.cs
@@ -1283,6 +1283,19 @@ namespace Terminal.Gui {
 	///     toplevel and then invoke <see cref="M:Terminal.Gui.Application.Run"/> with the
 	///     new toplevel.
 	///   </para>
+	///   <para>
+	///     TopLevels can also opt-in to more sophisticated initialization 
+	///     by implementing <see cref="ISupportInitialize"/>. When they do 
+	///     so, the <see cref="ISupportInitialize.BeginInit"/> and 
+	///     <see cref="ISupportInitialize.EndInit"/> methods will be called 
+	///     before running the view.
+	///     If first-run-only initialization is preferred, the <see cref="ISupportInitializeNotification"/> 
+	///     can be implemented too, in which case the <see cref="ISupportInitialize"/> 
+	///     methods will only be called if <see cref="ISupportInitializeNotification.IsInitialized"/> 
+	///     is <see langword="false"/>. This allows proper View inheritance hierarchies 
+	///     to override base class layout code optimally by doing so only on first run, 
+	///     instead of on every run.
+	///   </para>
 	/// </remarks>
 	public class Toplevel : View {
 		/// <summary>