Browse Source

Clarify `ClearItemContainer` docs.

And change usages of "should" to "must" as it's not optional.
Steven Kirk 2 years ago
parent
commit
3d693beffa
1 changed files with 11 additions and 4 deletions
  1. 11 4
      src/Avalonia.Controls/Generators/ItemContainerGenerator.cs

+ 11 - 4
src/Avalonia.Controls/Generators/ItemContainerGenerator.cs

@@ -85,7 +85,7 @@ namespace Avalonia.Controls.Generators
         /// <param name="index">The index of the item to display.</param>
         /// <remarks>
         /// If <see cref="IsItemItsOwnContainer(Control)"/> is true for an item, then this method
-        /// only needs to be called a single time, otherwise this method should be called after the
+        /// must only be called a single time, otherwise this method must be called after the
         /// container is created, and each subsequent time the container is recycled to display a
         /// new item.
         /// </remarks>
@@ -100,10 +100,11 @@ namespace Avalonia.Controls.Generators
         /// <param name="item">The item being displayed.</param>
         /// <param name="index">The index of the item being displayed.</param>
         /// <remarks>
-        /// This method should be called when a container has been fully prepared and added
+        /// This method must be called when a container has been fully prepared and added
         /// to the logical and visual trees, but may be called before a layout pass has completed.
-        /// It should be called regardless of the result of
-        /// <see cref="IsItemItsOwnContainer(Control)"/>.
+        /// It must be called regardless of the result of
+        /// <see cref="IsItemItsOwnContainer(Control)"/> but if that method returned true then
+        /// must be called only a single time.
         /// </remarks>
         public void ItemContainerPrepared(Control container, object? item, int index) =>
             _owner.ItemContainerPrepared(container, item, index);
@@ -122,6 +123,12 @@ namespace Avalonia.Controls.Generators
         /// Undoes the effects of the <see cref="PrepareItemContainer(Control, object, int)"/> method.
         /// </summary>
         /// <param name="container">The container control.</param>
+        /// <remarks>
+        /// This method must be called when a container is unrealized. The container must have
+        /// already have been removed from the virtualizing panel's list of realized containers before
+        /// this method is called. This method must not be called if
+        /// <see cref="IsItemItsOwnContainer"/> returned true for the item.
+        /// </remarks>
         public void ClearItemContainer(Control container) => _owner.ClearItemContainer(container);
 
         [Obsolete("Use ItemsControl.ContainerFromIndex")]