Document NavigableElement (dotnet#21507)

* Document NavigableElement * Finish Navigable Element docs * Minor styling * Update NavigableElement.cs --------- Co-authored-by: Rui Marinho <me@ruimarinho.net>
lytico · Apr 15, 2024 · ccffb28 · ccffb28
1 parent ea369b9
commit ccffb28
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 200 deletions.
diff --git a/src/Controls/docs/Microsoft.Maui.Controls/NavigableElement.xml b/src/Controls/docs/Microsoft.Maui.Controls/NavigableElement.xml
diff --git a/src/Controls/src/Core/INavigation.cs b/src/Controls/src/Core/INavigation.cs
@@ -4,6 +4,7 @@
 
 namespace Microsoft.Maui.Controls
 {
+ /// <summary>Provides the functionality for handling stack-based navigation.</summary>
  public interface INavigation
  {
  IReadOnlyList<Page> ModalStack { get; }

diff --git a/src/Controls/src/Core/NavigationProxy.cs b/src/Controls/src/Core/NavigationProxy.cs
@@ -13,7 +13,11 @@ public interface INavigationProxy
  NavigationProxy NavigationProxy { get; }
  }
 
- /// <include file="../../docs/Microsoft.Maui.Controls.Internals/NavigationProxy.xml" path="Type[@FullName='Microsoft.Maui.Controls.Internals.NavigationProxy']/Docs/*" />
+ /// <summary>Represents an object capable of handling stack-based navigation via proxying.</summary>
+ /// <remarks>
+ /// <para>Elements may use navigation proxies to delegate navigation capabilities to their parents if they themselves can't handle it.</para>
+ /// <para>For internal use for .NET MAUI.</para>
+ /// </remarks>
  [EditorBrowsable(EditorBrowsableState.Never)]
  public class NavigationProxy : INavigation
  {

diff --git a/src/Controls/src/Core/Shell/NavigableElement.cs b/src/Controls/src/Core/Shell/NavigableElement.cs
@@ -6,7 +6,8 @@
 
 namespace Microsoft.Maui.Controls
 {
- /// <include file="../../../docs/Microsoft.Maui.Controls/NavigableElement.xml" path="Type[@FullName='Microsoft.Maui.Controls.NavigableElement']/Docs/*" />
+ /// <summary>Represents an <see cref="Element"/> with base functionality for <see cref="Page"/> navigation. Does not necessarily render on screen.</summary>
+ /// <remarks>Not meant to be used directly. Instead, opt to use derived types, such as <see cref="View"/>.</remarks>
  public class NavigableElement : Element, INavigationProxy, IStyleSelectable
  {
  static readonly BindablePropertyKey NavigationPropertyKey =
@@ -28,29 +29,40 @@ internal NavigableElement()
  _mergedStyle = new MergedStyle(GetType(), this);
  }
 
- /// <include file="../../../docs/Microsoft.Maui.Controls/NavigableElement.xml" path="//Member[@MemberName='Navigation']/Docs/*" />
+ /// <summary>Gets the object responsible for handling stack-based navigation.</summary>
+ /// <remarks>Binds to the <see cref="NavigationProperty"/> <see cref="BindableProperty"/>.</remarks>
  public INavigation Navigation
  {
  get { return (INavigation)GetValue(NavigationProperty); }
  internal set { SetValue(NavigationPropertyKey, value); }
  }
 
- /// <include file="../../../docs/Microsoft.Maui.Controls/NavigableElement.xml" path="//Member[@MemberName='Style']/Docs/*" />
+ /// <summary>Gets or sets the unique <see cref="Style"/> for this element.</summary>
  public Style Style
  {
  get { return (Style)GetValue(StyleProperty); }
  set { SetValue(StyleProperty, value); }
  }
 
- /// <include file="../../../docs/Microsoft.Maui.Controls/NavigableElement.xml" path="//Member[@MemberName='StyleClass']/Docs/*" />
+ /// <summary>Gets or sets the style classes for the element.</summary>
+ /// <remarks>
+ /// <para>Equiavalent to <see cref="@class"/>.</para>
+ /// <para>Style classes enable multiple styles to be applied to a control, without resorting to style inheritance.</para>
+ /// </remarks>
+ /// <seealso href="https://learn.microsoft.com/dotnet/maui/user-interface/styles/xaml?view=net-maui-8.0#style-classes">Conceptual documentation on style classes</seealso>
  [System.ComponentModel.TypeConverter(typeof(ListStringTypeConverter))]
  public IList<string> StyleClass
  {
  get { return @class; }
  set { @class = value; }
  }
 
- /// <include file="../../../docs/Microsoft.Maui.Controls/NavigableElement.xml" path="//Member[@MemberName='class']/Docs/*" />
+ /// <summary>Gets or sets the style classes for the element.</summary>
+ /// <remarks>
+ /// <para>Equiavalent to <see cref="StyleClass"/>.</para>
+ /// <para>Style classes enable multiple styles to be applied to a control, without resorting to style inheritance.</para>
+ /// </remarks>
+ /// <seealso href="https://learn.microsoft.com/dotnet/maui/user-interface/styles/xaml?view=net-maui-8.0#style-classes">Conceptual documentation on style classes</seealso>
  [System.ComponentModel.TypeConverter(typeof(ListStringTypeConverter))]
  public IList<string> @class
  {
@@ -63,13 +75,23 @@ public IList<string> @class
 
  IList<string> IStyleSelectable.Classes => StyleClass;
 
- /// <include file="../../../docs/Microsoft.Maui.Controls/NavigableElement.xml" path="//Member[@MemberName='NavigationProxy']/Docs/*" />
+ /// <summary>Gets the cast of <see cref="Navigation"/> to a <see cref="Maui.Controls.Internals.NavigationProxy"/>.</summary>
+ /// <remarks>
+ /// <para>Determines whether the element will proxy navigation calls.</para>
+ /// <para>For internal use by .NET MAUI.</para>
+ /// </remarks>
  [EditorBrowsable(EditorBrowsableState.Never)]
  public NavigationProxy NavigationProxy
  {
  get { return Navigation as NavigationProxy; }
  }
 
+
+ /// <summary>Raises the (internal) <c>ParentSet</c> event.</summary>
+ /// <remarks>
+ /// Will set the <see cref="NavigationProxy">NavigationProxy's</see> inner navigation object to closest topmost element capable of handling navigation calls.
+ /// </remarks>
+ /// <seealso cref="Element.OnParentSet"/>
  protected override void OnParentSet()
  {
  base.OnParentSet();
@@ -96,4 +118,4 @@ protected override void OnParentSet()
  }
  }
  }
-}
+}