Updated API baselines, added XML docs.

6 files changed, 91 insertions, 5 deletions

diff --git a/src/Components/Components/src/NavigationManager.cs b/src/Components/Components/src/NavigationManager.cs
index 0ecc7d9b03..4e48b77f8f 100644
--- a/src/Components/Components/src/NavigationManager.cs
+++ b/src/Components/Components/src/NavigationManager.cs
@@ -269,7 +269,14 @@ public abstract class NavigationManager
         }
     }
 
-    public async ValueTask<bool> NotifyLocationChanging(string uri, bool intercepted, bool forceLoad)
+    /// <summary>
+    /// Notifies the registered <see cref="IHandleLocationChanging"/> handlers of the current location change.
+    /// </summary>
+    /// <param name="uri">The destination URI. This can be absolute, or relative to the base URI.</param>
+    /// <param name="isNavigationIntercepted">Whether this navigation was intercepted from a link.</param>
+    /// <param name="forceLoad">Whether the navigation is attempting to bypass client-side routing.</param>
+    /// <returns>A <see cref="ValueTask{TResult}"/> representing the completion of the operaiton.</returns>
+    public async ValueTask<bool> NotifyLocationChanging(string uri, bool isNavigationIntercepted, bool forceLoad)
     {
         _locationChangingCts?.Cancel();
         _locationChangingCts = null;
@@ -282,7 +289,7 @@ public abstract class NavigationManager
         _locationChangingCts = new();
 
         var cancellationToken = _locationChangingCts.Token;
-        var context = new LocationChangingContext(uri, intercepted, forceLoad, cancellationToken);
+        var context = new LocationChangingContext(uri, isNavigationIntercepted, forceLoad, cancellationToken);
         var handlerCount = _locationChangingHandlers.Count;
         var locationChangingHandlersCopy = ArrayPool<IHandleLocationChanging>.Shared.Rent(handlerCount);
         _locationChangingHandlers.CopyTo(locationChangingHandlersCopy);
@@ -316,11 +323,19 @@ public abstract class NavigationManager
         }
     }
 
+    /// <summary>
+    /// Sets whether there are active location changing handlers.
+    /// </summary>
+    /// <param name="value">Whether there are active location changing handlers.</param>
+    /// <returns><see langword="true"/> if the change was applied successfully, otherwise <see langword="false"/>.</returns>
     protected virtual bool SetHasLocationChangingHandlers(bool value)
     {
         return true;
     }
 
+    /// <summary>
+    /// Invokes <see cref="SetHasLocationChangingHandlers(bool)"/> if the existence of location changing handlers has changed.
+    /// </summary>
     protected void UpdateHasLocationChangingHandlers()
     {
         var hasLocationChangingHandlers = _locationChangingHandlers.Count != 0;
@@ -333,6 +348,10 @@ public abstract class NavigationManager
         }
     }
 
+    /// <summary>
+    /// Adds a handler to process incoming navigation events.
+    /// </summary>
+    /// <param name="locationChangingHandler">The handler to process incoming navigation events.</param>
     public void AddLocationChangingHandler(IHandleLocationChanging locationChangingHandler)
     {
         AssertInitialized();
@@ -340,6 +359,11 @@ public abstract class NavigationManager
         UpdateHasLocationChangingHandlers();
     }
 
+    /// <summary>
+    /// Removes a previously-added location changing handler.
+    /// </summary>
+    /// <param name="locationChangingHandler">The handler to remove.</param>
+    /// <returns><see langword="true"/> if the handler was removed, otherwise <see langword="false"/>.</returns>
     public bool RemoveLocationChangingHandler(IHandleLocationChanging locationChangingHandler)
     {
         AssertInitialized();
@@ -353,9 +377,19 @@ public abstract class NavigationManager
         return false;
     }
 
+    /// <summary>
+    /// Enables a navigation prompt to be displayed before navigation events complete.
+    /// </summary>
+    /// <param name="message">The message to display in the prompt. Note that some browsers will ignore this message for external navigations.</param>
+    /// <param name="externalNavigationsOnly">If <see langword="true"/>, the prompt will not display for internal page navigations.</param>
+    /// <returns>A <see cref="ValueTask"/> representing the completion of the operation.</returns>
     protected internal virtual ValueTask EnableNavigationPromptAsync(string message, bool externalNavigationsOnly)
         => ValueTask.CompletedTask;
 
+    /// <summary>
+    /// Disables the current navigation prompt.
+    /// </summary>
+    /// <returns>A <see cref="ValueTask"/> representing the completion of the operation.</returns>
     protected internal virtual ValueTask DisableNavigationPromptAsync()
         => ValueTask.CompletedTask;
 
diff --git a/src/Components/Components/src/PublicAPI.Unshipped.txt b/src/Components/Components/src/PublicAPI.Unshipped.txt
index e00577c4e3..0c1b058a6f 100644
--- a/src/Components/Components/src/PublicAPI.Unshipped.txt
+++ b/src/Components/Components/src/PublicAPI.Unshipped.txt
@@ -1,13 +1,13 @@
 #nullable enable
 Microsoft.AspNetCore.Components.NavigationManager.AddLocationChangingHandler(Microsoft.AspNetCore.Components.Routing.IHandleLocationChanging! locationChangingHandler) -> void
-Microsoft.AspNetCore.Components.NavigationManager.NotifyLocationChanging(string! uri, bool intercepted, bool forceLoad) -> System.Threading.Tasks.ValueTask<bool>
+Microsoft.AspNetCore.Components.NavigationManager.NotifyLocationChanging(string! uri, bool isNavigationIntercepted, bool forceLoad) -> System.Threading.Tasks.ValueTask<bool>
 Microsoft.AspNetCore.Components.NavigationManager.RemoveLocationChangingHandler(Microsoft.AspNetCore.Components.Routing.IHandleLocationChanging! locationChangingHandler) -> bool
 Microsoft.AspNetCore.Components.NavigationManager.UpdateHasLocationChangingHandlers() -> void
 Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder.AddContent(int sequence, Microsoft.AspNetCore.Components.MarkupString? markupContent) -> void
 Microsoft.AspNetCore.Components.Routing.IHandleLocationChanging
-Microsoft.AspNetCore.Components.Routing.IHandleLocationChanging.OnLocationChanging(Microsoft.AspNetCore.Components.Routing.LocationChangingContext! context) -> System.Threading.Tasks.ValueTask<bool>
+Microsoft.AspNetCore.Components.Routing.IHandleLocationChanging.OnLocationChanging(Microsoft.AspNetCore.Components.Routing.LocationChangingContext! context) -> System.Threading.Tasks.ValueTask
 Microsoft.AspNetCore.Components.Routing.InternalNavigationLock
-Microsoft.AspNetCore.Components.Routing.InternalNavigationLock.InternalNavigationLock(Microsoft.AspNetCore.Components.NavigationManager! navigationManager) -> void
+Microsoft.AspNetCore.Components.Routing.InternalNavigationLock.InternalNavigationLock() -> void
 Microsoft.AspNetCore.Components.Routing.InternalNavigationLock.OnLocationChanging.get -> Microsoft.AspNetCore.Components.EventCallback<Microsoft.AspNetCore.Components.Routing.LocationChangingContext!>
 Microsoft.AspNetCore.Components.Routing.InternalNavigationLock.OnLocationChanging.set -> void
 Microsoft.AspNetCore.Components.Routing.LocationChangingContext
@@ -22,6 +22,7 @@ Microsoft.AspNetCore.Components.Routing.NavigationPrompt.ExternalNavigationsOnly
 Microsoft.AspNetCore.Components.Routing.NavigationPrompt.ExternalNavigationsOnly.set -> void
 Microsoft.AspNetCore.Components.Routing.NavigationPrompt.Message.get -> string!
 Microsoft.AspNetCore.Components.Routing.NavigationPrompt.Message.set -> void
+Microsoft.AspNetCore.Components.Routing.NavigationPrompt.NavigationPrompt() -> void
 static Microsoft.AspNetCore.Components.CompilerServices.RuntimeHelpers.CreateInferredEventCallback<T>(object! receiver, Microsoft.AspNetCore.Components.EventCallback<T> callback, T value) -> Microsoft.AspNetCore.Components.EventCallback<T>
 static Microsoft.AspNetCore.Components.CompilerServices.RuntimeHelpers.InvokeAsynchronousDelegate(System.Action! callback) -> System.Threading.Tasks.Task!
 static Microsoft.AspNetCore.Components.CompilerServices.RuntimeHelpers.InvokeAsynchronousDelegate(System.Func<System.Threading.Tasks.Task!>! callback) -> System.Threading.Tasks.Task!
@@ -58,4 +59,6 @@ static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.Crea
 static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.CreateBinder(this Microsoft.AspNetCore.Components.EventCallbackFactory! factory, object! receiver, Microsoft.AspNetCore.Components.EventCallback<short?> setter, short? existingValue, System.Globalization.CultureInfo? culture = null) -> Microsoft.AspNetCore.Components.EventCallback<Microsoft.AspNetCore.Components.ChangeEventArgs!>
 static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.CreateBinder(this Microsoft.AspNetCore.Components.EventCallbackFactory! factory, object! receiver, Microsoft.AspNetCore.Components.EventCallback<string?> setter, string! existingValue, System.Globalization.CultureInfo? culture = null) -> Microsoft.AspNetCore.Components.EventCallback<Microsoft.AspNetCore.Components.ChangeEventArgs!>
 static Microsoft.AspNetCore.Components.EventCallbackFactoryBinderExtensions.CreateBinder<T>(this Microsoft.AspNetCore.Components.EventCallbackFactory! factory, object! receiver, Microsoft.AspNetCore.Components.EventCallback<T> setter, T existingValue, System.Globalization.CultureInfo? culture = null) -> Microsoft.AspNetCore.Components.EventCallback<Microsoft.AspNetCore.Components.ChangeEventArgs!>
+virtual Microsoft.AspNetCore.Components.NavigationManager.DisableNavigationPromptAsync() -> System.Threading.Tasks.ValueTask
+virtual Microsoft.AspNetCore.Components.NavigationManager.EnableNavigationPromptAsync(string! message, bool externalNavigationsOnly) -> System.Threading.Tasks.ValueTask
 virtual Microsoft.AspNetCore.Components.NavigationManager.SetHasLocationChangingHandlers(bool value) -> bool
diff --git a/src/Components/Components/src/Routing/IHandleLocationChanging.cs b/src/Components/Components/src/Routing/IHandleLocationChanging.cs
index 7a30d27800..cd0d45678a 100644
--- a/src/Components/Components/src/Routing/IHandleLocationChanging.cs
+++ b/src/Components/Components/src/Routing/IHandleLocationChanging.cs
@@ -3,7 +3,15 @@
 
 namespace Microsoft.AspNetCore.Components.Routing;
 
+/// <summary>
+/// Used to intercept changes to the browser's location.
+/// </summary>
 public interface IHandleLocationChanging
 {
+    /// <summary>
+    /// Invoked before the browser's location changes.
+    /// </summary>
+    /// <param name="context">The context for the navigation event.</param>
+    /// <returns>A <see cref="ValueTask"/> representing the completion of the operation.</returns>
     ValueTask OnLocationChanging(LocationChangingContext context);
 }
diff --git a/src/Components/Components/src/Routing/InternalNavigationLock.cs b/src/Components/Components/src/Routing/InternalNavigationLock.cs
index eb89c54794..bd1925ad91 100644
--- a/src/Components/Components/src/Routing/InternalNavigationLock.cs
+++ b/src/Components/Components/src/Routing/InternalNavigationLock.cs
@@ -3,6 +3,9 @@
 
 namespace Microsoft.AspNetCore.Components.Routing;
 
+/// <summary>
+/// A component that can be used to intercept internal navigation events.
+/// </summary>
 public class InternalNavigationLock : IComponent, IHandleLocationChanging, IDisposable
 {
     private bool _isInitialized;
@@ -10,6 +13,9 @@ public class InternalNavigationLock : IComponent, IHandleLocationChanging, IDisp
     [Inject]
     private NavigationManager NavigationManager { get; set; } = default!;
 
+    /// <summary>
+    /// A callback to be invoked when an internal navigation event occurs.
+    /// </summary>
     [Parameter]
     [EditorRequired]
     public EventCallback<LocationChangingContext> OnLocationChanging { get; set; }
diff --git a/src/Components/Components/src/Routing/LocationChangingContext.cs b/src/Components/Components/src/Routing/LocationChangingContext.cs
index 1196827329..d030d1545d 100644
--- a/src/Components/Components/src/Routing/LocationChangingContext.cs
+++ b/src/Components/Components/src/Routing/LocationChangingContext.cs
@@ -3,6 +3,9 @@
 
 namespace Microsoft.AspNetCore.Components.Routing;
 
+/// <summary>
+/// Contains context for a change to the browser's current location.
+/// </summary>
 public class LocationChangingContext
 {
     internal LocationChangingContext(string location, bool isNavigationIntercepted, bool forceLoad, CancellationToken cancellationToken)
@@ -13,16 +16,35 @@ public class LocationChangingContext
         CancellationToken = cancellationToken;
     }
 
+    /// <summary>
+    /// Gets the URI being navigated to.
+    /// </summary>
     public string Location { get; }
 
+    /// <summary>
+    /// Gets whether this navigation was intercepted from a link.
+    /// </summary>
     public bool IsNavigationIntercepted { get; }
 
+    /// <summary>
+    /// Gets whether the navigation is attempting to bypass client-side routing.
+    /// </summary>
     public bool ForceLoad { get; }
 
+    /// <summary>
+    /// Gets a <see cref="System.Threading.CancellationToken"/> that can be used to determine if this navigation gets canceled
+    /// by a successive navigation.
+    /// </summary>
     public CancellationToken CancellationToken { get; }
 
+    /// <summary>
+    /// Gets whether this navigation has been canceled.
+    /// </summary>
     public bool IsCanceled { get; private set; }
 
+    /// <summary>
+    /// Cancels this navigation.
+    /// </summary>
     public void Cancel()
     {
         IsCanceled = true;
diff --git a/src/Components/Components/src/Routing/NavigationPrompt.cs b/src/Components/Components/src/Routing/NavigationPrompt.cs
index c9641110c4..4eb82a7307 100644
--- a/src/Components/Components/src/Routing/NavigationPrompt.cs
+++ b/src/Components/Components/src/Routing/NavigationPrompt.cs
@@ -3,15 +3,28 @@
 
 namespace Microsoft.AspNetCore.Components.Routing;
 
+/// <summary>
+/// A component that displays a browser prompt when the user navigates away from the page.
+/// </summary>
 public class NavigationPrompt : IComponent, IAsyncDisposable
 {
     [Inject]
     private NavigationManager NavigationManager { get; set; } = default!;
 
+    /// <summary>
+    /// Gets or sets message to be displayed when the user navigates away from the page.
+    /// </summary>
+    /// <remarks>
+    /// Some browsers will not display this message for external navigations.
+    /// For more info, see <see href="https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event#compatibility_notes"/>.
+    /// </remarks>
     [Parameter]
     [EditorRequired]
     public string Message { get; set; } = default!;
 
+    /// <summary>
+    /// Gets or sets whether the prompt will only display for external navigations.
+    /// </summary>
     [Parameter]
     public bool ExternalNavigationsOnly { get; set; }