Resolved cref references within XML Docs

JeremyCaney · JeremyCaney · commit 684b47959bd4 · 2021-02-22T12:30:32.000-08:00
Not all `&lt;see cref /&gt;` references resolved. Sometimes this was due to references to old or incorrect identifiers, but more often simply out-of-scope references. In many cases, these can be resolved by simply adding a `using` statement. In other cases, it required updating the references—and, especially, the method signatures. This resolves CS1574.
diff --git a/OnTopic.AspNetCore.Mvc.Host/Components/MenuViewComponent.cs b/OnTopic.AspNetCore.Mvc.Host/Components/MenuViewComponent.cs
@@ -5,6 +5,7 @@
 \=============================================================================================================================*/
 using Microsoft.AspNetCore.Mvc;
 using OnTopic.AspNetCore.Mvc.Components;
+using OnTopic.AspNetCore.Mvc.Controllers;
 using OnTopic.AspNetCore.Mvc.Models;
 using OnTopic.Mapping.Hierarchical;
 using OnTopic.Repositories;
@@ -16,7 +17,7 @@ namespace OnTopic.AspNetCore.Mvc.Host.Components {
   | CLASS: MENU VIEW COMPONENT
   \---------------------------------------------------------------------------------------------------------------------------*/
   /// <summary>
-  ///   Defines a <see cref="ViewComponent"/> which provides access to a menu of <typeparamref name="NavigationTopicViewModel"/>
+  ///   Defines a <see cref="ViewComponent"/> which provides access to a menu of <see cref="NavigationTopicViewModel"/>
   ///   instances.
   /// </summary>
   /// <remarks>
diff --git a/OnTopic.AspNetCore.Mvc.Host/Components/PageLevelNavigationViewComponent.cs b/OnTopic.AspNetCore.Mvc.Host/Components/PageLevelNavigationViewComponent.cs
@@ -5,6 +5,7 @@
 \=============================================================================================================================*/
 using Microsoft.AspNetCore.Mvc;
 using OnTopic.AspNetCore.Mvc.Components;
+using OnTopic.AspNetCore.Mvc.Controllers;
 using OnTopic.AspNetCore.Mvc.Models;
 using OnTopic.Mapping.Hierarchical;
 using OnTopic.Repositories;
@@ -16,15 +17,14 @@ namespace OnTopic.AspNetCore.Mvc.Host.Components {
   | CLASS: PAGE-LEVEL NAVIGATION VIEW COMPONENT
   \---------------------------------------------------------------------------------------------------------------------------*/
   /// <summary>
-  ///   Defines a <see cref="ViewComponent"/> which provides access to a menu of <typeparamref name="NavigationTopicViewModel"/>
+  ///   Defines a <see cref="ViewComponent"/> which provides access to a menu of <see cref="NavigationTopicViewModel"/>
   ///   instances representing the nearest page-level navigation.
   /// </summary>
   /// <remarks>
   ///   <para>
   ///     As a best practice, global data required by the layout view are requested independent of the current page. This
-  ///     allows each layout element to be provided with its own layout data, in the form of <see
-  ///     cref="NavigationViewModel{T}"/>s, instead of needing to add this data to every view model returned by <see
-  ///     cref="TopicController"/>.
+  ///     allows each layout element to be provided with its own layout data, in the form of <see cref="NavigationViewModel{T}"
+  ///     />s, instead of needing to add this data to every view model returned by <see cref="TopicController"/>.
   ///   </para>
   /// </remarks>
   public class PageLevelNavigationViewComponent : PageLevelNavigationViewComponentBase<NavigationTopicViewModel> {
diff --git a/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs b/OnTopic.AspNetCore.Mvc.Host/SampleActivator.cs
@@ -46,8 +46,8 @@ public class SampleActivator : IControllerActivator, IViewComponentActivator {
     | CONSTRUCTOR
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Establishes a new instance of the <see cref="SampleControllerFactory"/>, including any shared dependencies to be used
-    ///   across instances of controllers.
+    ///   Establishes a new instance of the <see cref="SampleActivator"/>, including any shared dependencies to be used across
+    ///   instances of controllers.
     /// </summary>
     /// <remarks>
     ///   The constructor is responsible for establishing dependencies with the singleton lifestyle so that they are available
@@ -88,7 +88,7 @@ public SampleActivator(string connectionString) {
     /// <summary>
     ///   Registers dependencies, and injects them into new instances of controllers in response to each request.
     /// </summary>
-    /// <returns>A concrete instance of an <see cref="IController"/>.</returns>
+    /// <returns>A concrete instance of an <see cref="Controller"/>.</returns>
     public object Create(ControllerContext context) {
 
       /*------------------------------------------------------------------------------------------------------------------------
@@ -128,7 +128,7 @@ public object Create(ControllerContext context) {
     /// <summary>
     ///   Registers dependencies, and injects them into new instances of view components in response to each request.
     /// </summary>
-    /// <returns>A concrete instance of an <see cref="IController"/>.</returns>
+    /// <returns>A concrete instance of an <see cref="ViewComponent"/>.</returns>
     public object Create(ViewComponentContext context) {
 
       /*------------------------------------------------------------------------------------------------------------------------
diff --git a/OnTopic.AspNetCore.Mvc.Tests/TopicControllerTest.cs b/OnTopic.AspNetCore.Mvc.Tests/TopicControllerTest.cs
@@ -25,7 +25,7 @@ namespace OnTopic.Tests {
   \---------------------------------------------------------------------------------------------------------------------------*/
   /// <summary>
   ///   Provides unit tests for the <see cref="TopicController"/>, and other <see cref="Controller"/> classes that are part of
-  ///   the <see cref="OnTopic.Web.Mvc"/> namespace.
+  ///   the <see cref="OnTopic.AspNetCore.Mvc"/> namespace.
   /// </summary>
   [TestClass]
   public class TopicControllerTest {
@@ -104,7 +104,7 @@ public async Task TopicController_IndexAsync_ReturnsTopicViewResult() {
     | TEST: REDIRECT CONTROLLER: REDIRECT: RETURNS REDIRECT RESULT
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Triggers the <see cref="FallbackController.Index()" /> action.
+    ///   Triggers the <see cref="RedirectController.Redirect(Int32)" /> action.
     /// </summary>
     [TestMethod]
     public void RedirectController_TopicRedirect_ReturnsRedirectResult() {
@@ -124,7 +124,7 @@ public void RedirectController_TopicRedirect_ReturnsRedirectResult() {
     | TEST: SITEMAP CONTROLLER: INDEX: RETURNS SITEMAP XML
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Triggers the index action of the <see cref="SitemapController.Index()" /> action.
+    ///   Triggers the index action of the <see cref="SitemapController.Index(Boolean, Boolean)" /> action.
     /// </summary>
     [TestMethod]
     public void SitemapController_Index_ReturnsSitemapXml() {
@@ -152,8 +152,8 @@ public void SitemapController_Index_ReturnsSitemapXml() {
     | TEST: SITEMAP CONTROLLER: INDEX: EXCLUDES CONTENT TYPES
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Triggers the index action of the <see cref="SitemapController.Index()" /> action and verifies that it properly
-    ///   excludes <c>List</c> content types, and skips over <c>Container</c> and <c>PageGroup</c>.
+    ///   Triggers the index action of the <see cref="SitemapController.Index(Boolean, Boolean)" /> action and verifies that it
+    ///   properly excludes <c>List</c> content types, and skips over <c>Container</c> and <c>PageGroup</c>.
     /// </summary>
     [TestMethod]
     public void SitemapController_Index_ExcludesContentTypes() {
@@ -198,8 +198,8 @@ public void SitemapController_Index_ExcludesContentTypes() {
     | TEST: SITEMAP CONTROLLER: INDEX: EXCLUDES ATTRIBUTES
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Triggers the index action of the <see cref="SitemapController.Index()" /> action and verifies that it properly
-    ///   excludes the <c>Body</c> and <c>IsHidden</c> attributes.
+    ///   Triggers the index action of the <see cref="SitemapController.Index(Boolean, Boolean)" /> action and verifies that it
+    ///   properly excludes the <c>Body</c> and <c>IsHidden</c> attributes.
     /// </summary>
     [TestMethod]
     public void SitemapController_Index_ExcludesAttributes() {
diff --git a/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs b/OnTopic.AspNetCore.Mvc.Tests/TopicViewComponentTest.cs
@@ -9,6 +9,7 @@
 using Microsoft.AspNetCore.Mvc.ViewComponents;
 using Microsoft.AspNetCore.Routing;
 using Microsoft.VisualStudio.TestTools.UnitTesting;
+using OnTopic.AspNetCore.Mvc.Components;
 using OnTopic.AspNetCore.Mvc.Host.Components;
 using OnTopic.AspNetCore.Mvc.Models;
 using OnTopic.Data.Caching;
diff --git a/OnTopic.AspNetCore.Mvc.Tests/ValidateTopicAttributeTest.cs b/OnTopic.AspNetCore.Mvc.Tests/ValidateTopicAttributeTest.cs
@@ -14,6 +14,7 @@
 using OnTopic.AspNetCore.Mvc;
 using OnTopic.AspNetCore.Mvc.Controllers;
 using OnTopic.Attributes;
+using OnTopic.Metadata;
 using OnTopic.TestDoubles;
 
 namespace OnTopic.Tests {
diff --git a/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs b/OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs
@@ -6,6 +6,7 @@
 using System;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Mvc;
+using OnTopic.AspNetCore.Mvc.Controllers;
 using OnTopic.AspNetCore.Mvc.Models;
 using OnTopic.Internal.Diagnostics;
 using OnTopic.Mapping.Hierarchical;
diff --git a/OnTopic.AspNetCore.Mvc/Components/NavigationTopicViewComponentBase{T}.cs b/OnTopic.AspNetCore.Mvc/Components/NavigationTopicViewComponentBase{T}.cs
@@ -52,7 +52,7 @@ IHierarchicalTopicMappingService<T> hierarchicalTopicMappingService
     ///   on the route data.
     /// </summary>
     /// <returns>
-    ///   The <see cref="ITopicRepository"/> associated with the <see cref="TopicViewComponentBase{T}"/>.
+    ///   The <see cref="ITopicRepository"/> associated with the <see cref="NavigationTopicViewComponentBase{T}"/>.
     /// </returns>
     protected ITopicRepository TopicRepository { get; }
 
@@ -64,7 +64,8 @@ IHierarchicalTopicMappingService<T> hierarchicalTopicMappingService
     ///   be mapped.
     /// </summary>
     /// <returns>
-    ///   The <see cref="IHierarchicalTopicMappingService{T}"/> associated with the <see cref="TopicViewComponentBase{T}"/>.
+    ///   The <see cref="IHierarchicalTopicMappingService{T}"/> associated with the <see cref="
+    ///   NavigationTopicViewComponentBase{T}"/>.
     /// </returns>
     protected IHierarchicalTopicMappingService<T> HierarchicalTopicMappingService { get; }
 
diff --git a/OnTopic.AspNetCore.Mvc/Components/PageLevelNavigationViewComponentBase{T}.cs b/OnTopic.AspNetCore.Mvc/Components/PageLevelNavigationViewComponentBase{T}.cs
@@ -5,6 +5,7 @@
 \=============================================================================================================================*/
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Mvc;
+using OnTopic.AspNetCore.Mvc.Controllers;
 using OnTopic.AspNetCore.Mvc.Models;
 using OnTopic.Mapping.Hierarchical;
 using OnTopic.Models;
@@ -16,8 +17,8 @@ namespace OnTopic.AspNetCore.Mvc.Components {
   | CLASS: PAGE-LEVEL NAVIGATION VIEW COMPONENT
   \---------------------------------------------------------------------------------------------------------------------------*/
   /// <summary>
-  ///   Defines a <see cref="ViewComponent"/> which provides access to a menu of <typeparamref name="NavigationTopicViewModel"/>
-  ///   instances representing the nearest page-level navigation.
+  ///   Defines a <see cref="ViewComponent"/> which provides access to a menu of <typeparamref name="T"/> instances representing
+  ///   the nearest page-level navigation.
   /// </summary>
   /// <remarks>
   ///   <para>
diff --git a/OnTopic.AspNetCore.Mvc/Models/NavigationViewModel{T}.cs b/OnTopic.AspNetCore.Mvc/Models/NavigationViewModel{T}.cs
@@ -3,6 +3,8 @@
 | Client        Ignia, LLC
 | Project       Topics Library
 \=============================================================================================================================*/
+using System;
+using OnTopic.AspNetCore.Mvc.Components;
 using OnTopic.Models;
 
 namespace OnTopic.AspNetCore.Mvc.Models {
@@ -16,13 +18,13 @@ namespace OnTopic.AspNetCore.Mvc.Models {
   /// <remarks>
   ///   <para>
   ///     No topics are expected to have a <c>Navigation</c> content type. Instead, this view model is expected to be manually
-  ///     constructed by the <see cref="LayoutController"/>.
+  ///     constructed by the <see cref="NavigationTopicViewComponentBase{T}"/>.
   ///   </para>
   ///   <para>
-  ///     The <see cref="NavigationRoot"/> can be any view model that implements <see cref="INavigationTopicViewModel"/>,
+  ///     The <see cref="NavigationRoot"/> can be any view model that implements <see cref="INavigationTopicViewModel{T}"/>,
   ///     which provides a base level of support for properties associated with the typical <c>Page</c> content type as well as
-  ///     a method for determining if a given <see cref="INavigationTopicViewModel"/> instance is the currently-selected topic.
-  ///     Implementations may support additional properties, as appropriate.
+  ///     a method for determining if a given <see cref="INavigationTopicViewModel{T}"/> instance is the currently-selected
+  ///     topic. Implementations may support additional properties, as appropriate.
   ///   </para>
   /// </remarks>
   public class NavigationViewModel<T> where T : class, INavigationTopicViewModel<T> {
diff --git a/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs b/OnTopic.AspNetCore.Mvc/TopicRepositoryExtensions.cs
@@ -31,7 +31,7 @@ public static class TopicRepositoryExtensions {
     ///   of the box routes, such as <c>controller</c> and <c>action</c>, the <see cref="ServiceCollectionExtensions"/> defines
     ///   additional topic-specific routes, such as <c>rootTopic</c> and <c>path</c>. These can be combined to identify a topic
     ///   in the repository. By using the extension method, callers needn't assemble their own <see cref="Topic.GetUniqueKey"/>
-    ///   prior to calling <see cref="ITopicRepository.Load(String uniqueKey)"/>, assuming they are using the standard routing
+    ///   prior to calling <see cref="ITopicRepository.Load(String?, Boolean)"/>, assuming they are using the standard routing
     ///   variables.
     /// </remarks>
     public static Topic? Load(
diff --git a/OnTopic.AspNetCore.Mvc/TopicViewLocationExpander.cs b/OnTopic.AspNetCore.Mvc/TopicViewLocationExpander.cs
@@ -74,9 +74,7 @@ public TopicViewLocationExpander() {
     /// <summary>
     ///   Initializes a new instance of the <see cref="TopicViewLocationExpander"/> class.
     /// </summary>
-    /// <remarks>
-    /// </remarks>
-    /// <seealso cref="https://stackoverflow.com/questions/36802661/what-is-iviewlocationexpander-populatevalues-for-in-asp-net-core-mvc"/>
+    /// <seealso href="https://stackoverflow.com/questions/36802661/what-is-iviewlocationexpander-populatevalues-for-in-asp-net-core-mvc"/>
     /// <param name="context">The <see cref="ViewLocationExpanderContext"/> that the request is operating within.</param>
     public void PopulateValues(ViewLocationExpanderContext context) {
       Contract.Requires(context, nameof(context));
diff --git a/OnTopic.AspNetCore.Mvc/TopicViewResult.cs b/OnTopic.AspNetCore.Mvc/TopicViewResult.cs
@@ -9,6 +9,7 @@
 using Microsoft.AspNetCore.Mvc.ViewFeatures;
 using Microsoft.Extensions.DependencyInjection;
 using OnTopic.Internal.Diagnostics;
+using OnTopic.Metadata;
 
 namespace OnTopic.AspNetCore.Mvc {
 
@@ -65,8 +66,8 @@ public TopicViewResult(
     /// </summary>
     /// <remarks>
     ///   The preferred nomenclature for the name of a <see cref="ContentTypeDescriptor"/> is simply <c>ContentType</c>. The
-    ///   base <see cref="ViewResult"/> class has an existing <see cref="ContentType"/> property representing the HTTP response
-    ///   value, however. As such, <see cref="TopicContentType"/> is used to disambiguate the terms.
+    ///   base <see cref="ViewResult"/> class has an existing <see cref="ViewResult.ContentType"/> property representing the
+    ///   HTTP response value, however. As such, <see cref="TopicContentType"/> is used to disambiguate the terms.
     /// </remarks>
     public string TopicContentType { get; } = "Page";
 
diff --git a/OnTopic.AspNetCore.Mvc/TopicViewResultExecutor.cs b/OnTopic.AspNetCore.Mvc/TopicViewResultExecutor.cs
@@ -8,9 +8,11 @@
 using System.Diagnostics;
 using System.Linq;
 using System.Threading.Tasks;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.Mvc.Infrastructure;
 using Microsoft.AspNetCore.Mvc.ModelBinding;
+using Microsoft.AspNetCore.Mvc.Razor;
 using Microsoft.AspNetCore.Mvc.ViewEngines;
 using Microsoft.AspNetCore.Mvc.ViewFeatures;
 using Microsoft.Extensions.Logging;
diff --git a/OnTopic.AspNetCore.Mvc/ValidateTopicAttribute.cs b/OnTopic.AspNetCore.Mvc/ValidateTopicAttribute.cs
@@ -23,7 +23,8 @@ namespace OnTopic.AspNetCore.Mvc {
   ///   Not all topics are appropriate to display in a view. If the topic isn't in the repository, the action should return a
   ///   <see cref="NotFoundResult"/>. If the topic is marked as <see cref="Topic.IsDisabled"/>, then the action should return a
   ///   <see cref="UnauthorizedResult"/>. If the topic contains a <c>Url</c> attribute, then the action should return a <see
-  ///   cref="RedirectResult"/>. All of this logic can be enforced by adding the <see cref="ValidateTopicFilter"/> to an action.
+  ///   cref="RedirectResult"/>. All of this logic can be enforced by adding the <see cref="ValidateTopicAttribute"/> to an
+  ///   action.
   /// </remarks>
   [AttributeUsage(AttributeTargets.Method)]
   public sealed class ValidateTopicAttribute : ActionFilterAttribute {
@@ -48,10 +49,10 @@ public sealed class ValidateTopicAttribute : ActionFilterAttribute {
     /// </summary>
     /// <remarks>
     ///   While the <see cref="OnActionExecuting(ActionExecutingContext)"/> event can be used to provide a wide variety of
-    ///   filters, this specific implementation is focused on validating the state of the <see cref="CurrentTopic"/>. Namely,
-    ///   it will provide error handling (if the <see cref="CurrentTopic"/> is null), a redirect (if the <see
-    ///   cref="CurrentTopic"/>'s <c>Url</c> attribute is set, and an unauthorized response (if the <see cref="CurrentTopic"/>'s
-    ///   <see cref="Topic.IsDisabled"/> flag is set.
+    ///   filters, this specific implementation is focused on validating the state of the <see cref="TopicController.
+    ///   CurrentTopic"/>. Namely, it will provide error handling (if the <see cref="TopicController.CurrentTopic"/> is null), a
+    ///   redirect (if the <see cref="TopicController.CurrentTopic"/>'s <c>Url</c> attribute is set, and an unauthorized
+    ///   response (if the <see cref="TopicController.CurrentTopic"/>'s <see cref="Topic.IsDisabled"/> flag is set.
     /// </remarks>
     /// <returns>A view associated with the requested topic's Content Type and view.</returns>
     [NonAction]
diff --git a/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs b/OnTopic.Data.Sql/Models/AttributeValuesDataTable.cs
@@ -5,6 +5,7 @@
 \=============================================================================================================================*/
 using System.Data;
 using OnTopic.Attributes;
+using OnTopic.Collections.Specialized;
 
 namespace OnTopic.Data.Sql.Models {
 
@@ -51,8 +52,8 @@ internal AttributeValuesDataTable() {
     /// <summary>
     ///   Provides a convenience method for adding a new <see cref="DataRow"/> based on the expected column values.
     /// </summary>
-    /// <param name="attributeKey">The <see cref="AttributeRecord.Key"/>.</param>
-    /// <param name="attributeValue">The <see cref="AttributeRecord.Value"/>.</param>
+    /// <param name="attributeKey">The <see cref="TrackedRecord{T}.Key"/>.</param>
+    /// <param name="attributeValue">The <see cref="TrackedRecord{T}.Value"/>.</param>
     internal DataRow AddRow(string attributeKey, string? attributeValue = null) {
 
       /*------------------------------------------------------------------------------------------------------------------------
diff --git a/OnTopic.Data.Sql/SqlDataReaderExtensions.cs b/OnTopic.Data.Sql/SqlDataReaderExtensions.cs
@@ -28,7 +28,7 @@ namespace OnTopic.Data.Sql {
   ///   main entry point is <see cref="LoadTopicGraph"/>. It is supported by a number of <c>private</c> extensions which allow
   ///   it to handle individual records from particular data sets (e.g., the <see cref="SetExtendedAttributes"/> method maps to
   ///   data returned from the <c>ExtendedAttributeIndex</c> view). That said, the <c>Get</c> extensions (e.g., <see
-  ///   cref="GetString(SqlDataReader, String)"/>) are not specific to this format, and remain useful for a variety of database
+  ///   cref="GetString(IDataReader, String)"/>) are not specific to this format, and remain useful for a variety of database
   ///   queries, should they be needed, and thus are marked as <c>internal</c>.
   /// </remarks>
   internal static class SqlDataReaderExtensions {
diff --git a/OnTopic.Data.Sql/SqlTopicRepository.cs b/OnTopic.Data.Sql/SqlTopicRepository.cs
@@ -24,7 +24,7 @@ namespace OnTopic.Data.Sql {
   ///   Provides data access to topics stored in Microsoft SQL Server.
   /// </summary>
   /// <remarks>
-  ///   Concrete implementation of the <see cref="OnTopic.Repositories.IDataRepository"/> class.
+  ///   Concrete implementation of the <see cref="ITopicRepository"/> class.
   /// </remarks>
   public class SqlTopicRepository : TopicRepository, ITopicRepository {
 
diff --git a/OnTopic.TestDoubles/DummyTopicMappingService.cs b/OnTopic.TestDoubles/DummyTopicMappingService.cs
@@ -26,7 +26,7 @@ public class DummyTopicMappingService : ITopicMappingService {
     | CONSTRUCTOR
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Establishes a new instance of a <see cref="DummmyTopicMappingService"/> with required dependencies.
+    ///   Establishes a new instance of a <see cref="DummyTopicMappingService"/> with required dependencies.
     /// </summary>
     public DummyTopicMappingService() {
     }
diff --git a/OnTopic.TestDoubles/StubTopicRepository.cs b/OnTopic.TestDoubles/StubTopicRepository.cs
diff --git a/OnTopic.ViewModels/Collections/TopicViewModelCollection.cs b/OnTopic.ViewModels/Collections/TopicViewModelCollection.cs
diff --git a/OnTopic.ViewModels/Items/ListTopicViewModel.cs b/OnTopic.ViewModels/Items/ListTopicViewModel.cs
diff --git a/OnTopic.ViewModels/TopicViewModelLookupService.cs b/OnTopic.ViewModels/TopicViewModelLookupService.cs
