Fix most comment reference issues (#3946)

Author: srawlins

lib/src/dartdoc_options.dart

@@ -194,7 +194,7 @@ class _OptionValueWithContext<T> {
   /// If non-null, the basename of the configuration file the value came from.
   String? definingFile;
 
-  /// A [pathLib.Context] variable initialized with 'canonicalDirectoryPath'.
+  /// A [p.Context] variable initialized with 'canonicalDirectoryPath'.
   p.Context pathContext;
 
   /// Build a _OptionValueWithContext.
@@ -795,8 +795,8 @@ mixin _DartdocFileOption<T> implements DartdocOption<T> {
     return __valueAtFromFiles[key];
   }
 
-  /// Searches all dartdoc_options files through parent directories, starting at
-  /// [dir], for the option and returns one once found.
+  /// Searches all dartdoc options files through parent directories, starting at
+  /// [folder], for the option and returns one once found.
   _OptionValueWithContext<T>? _valueAtFromFilesFirstFound(Folder folder) {
     _OptionValueWithContext<T>? value;
     for (var dir in folder.withAncestors) {
@@ -975,8 +975,8 @@ mixin _DartdocArgOption<T> implements DartdocOption<T> {
         'missing path: "$missingPath"');
   }
 
-  /// Generates an _OptionValueWithContext using the value of the argument from
-  /// the [argParser] and the working directory from [_directoryCurrent].
+  /// Generates an [_OptionValueWithContext] using the value of the argument
+  /// from the [_argResults] and the working directory from [_directoryCurrent].
   ///
   /// Throws [UnsupportedError] if [T] is not a supported type.
   _OptionValueWithContext<T>? _valueAtFromArgsWithContext() {

lib/src/generator/html_generator.dart

@@ -16,7 +16,7 @@ import 'package:meta/meta.dart';
 
 /// Creates a [Generator] with an [HtmlGeneratorBackend] backend.
 ///
-/// [forceRuntimeTemplates] should only be given [true] during tests.
+/// [forceRuntimeTemplates] should only be given `true` during tests.
 Future<Generator> initHtmlGenerator(
   DartdocGeneratorOptionContext context, {
   required FileWriter writer,

lib/src/generator/templates.dart

@@ -115,7 +115,7 @@ abstract class Templates {
   /// Creates a [Templates] instance either from the default set of templates,
   /// or a custom set if the 'templatesDir' Dartdoc option is used.
   ///
-  /// [forceRuntimeTemplates] should only be given [true] during tests.
+  /// [forceRuntimeTemplates] should only be given `true` during tests.
   static Future<Templates> fromContext(DartdocGeneratorOptionContext context,
       {bool forceRuntimeTemplates = false}) async {
     var templatesDir = context.templatesDir;

lib/src/model/container_modifiers.dart

@@ -43,7 +43,7 @@ class ContainerModifier implements Comparable<ContainerModifier> {
 }
 
 extension BuildLanguageFeatureSet on Iterable<ContainerModifier> {
-  /// Transforms [ContainerModifiers] into a series of [LanguageFeature] objects
+  /// Transforms [ContainerModifier]s into a series of [LanguageFeature] objects
   /// suitable for rendering as chips.   Assumes iterable is sorted.
   Iterable<LanguageFeature> get asLanguageFeatureSet =>
       where((m) => !m.hideIfPresent.any(contains))

lib/src/model/documentation.dart

@@ -23,7 +23,7 @@ class Documentation {
   /// A guard against re-computing [_asHtml].
   bool _hasHtmlBeenRendered = false;
 
-  /// A guard against re-computing [_asHOneLiner].
+  /// A guard against re-computing [_asOneLiner].
   bool _hasOneLinerBeenRendered = false;
 
   String get asHtml {

lib/src/model/documentation_comment.dart

@@ -2,6 +2,9 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+/// @docImport 'package:dartdoc/src/model/package_graph.dart';
+library;
+
 import 'package:analyzer/dart/element/element.dart';
 import 'package:args/args.dart';
 import 'package:crypto/crypto.dart' as crypto;
@@ -835,8 +838,8 @@ mixin DocumentationComment
 
   /// Replace `<dartdoc-html>[digest]</dartdoc-html>` in API comments with
   /// the contents of the HTML fragment earlier defined by the
-  /// &#123;@inject-html&#125; directive. The [digest] is a SHA1 of the contents
-  /// of the HTML fragment, automatically generated upon parsing the
+  /// &#123;@inject-html&#125; directive. The `[digest]` is a SHA1 of the
+  /// contents of the HTML fragment, automatically generated upon parsing the
   /// &#123;@inject-html&#125; directive.
   ///
   /// This markup is generated and inserted by [_stripHtmlAndAddToIndex] when it

lib/src/model/inheritable.dart

@@ -14,10 +14,9 @@ import 'package:dartdoc/src/model/model.dart';
 /// We can search the inheritance chain between this instance and
 /// [definingEnclosingContainer] in [Inheritable.canonicalEnclosingContainer],
 /// for the canonical [Class] closest to where this member was defined.  We
-/// can then know that when we find [Inheritable.modelElement] inside that
-/// [Class]'s namespace, that's the one we should treat as canonical and
-/// implementors of this class can use that knowledge to determine
-/// canonicalization.
+/// can then know that when we find [Inheritable.element] inside that [Class]'s
+/// namespace, that's the one we should treat as canonical and implementors of
+/// this class can use that knowledge to determine canonicalization.
 ///
 /// We pick the class closest to the [definingEnclosingContainer] so that all
 /// children of that class inheriting the same member will point to the same

lib/src/model/locatable.dart

@@ -16,7 +16,7 @@ mixin Locatable {
   /// class doesn't have docs for this element.
   List<Locatable> get documentationFrom;
 
-  /// True if documentationFrom contains only one item, [this].
+  /// Whether [documentationFrom] contains only one item, `this`.
   bool get documentationIsLocal =>
       documentationFrom.length == 1 && identical(documentationFrom.first, this);
 

lib/src/model/model_element.dart

@@ -255,7 +255,7 @@ abstract class ModelElement
     return newModelElement;
   }
 
-  /// Caches a newly-created [ModelElement] from [ModelElement._from] or
+  /// Caches a newly-created [ModelElement] from [ModelElement.for_] or
   /// [ModelElement.forPropertyInducingElement].
   static void _cacheNewModelElement(
       Element e, ModelElement newModelElement, Library library,

lib/src/model/package_graph.dart

@@ -707,10 +707,6 @@ class PackageGraph with CommentReferable, Nameable {
   /// If we know the element is related to a particular class, pass a
   /// [preferredClass] to disambiguate.
   ///
-  /// This doesn't know anything about [PackageGraph.inheritThrough] and
-  /// probably shouldn't, so using it with [Inheritable]s without special casing
-  /// is not advised.
-  ///
   /// This can return `null` in a few ways: if [modelElement] is `null`, or if
   /// it has no canonical library, or if a possible canonical model element has
   /// a `false` value for `isCanonical`.