Fix most comment reference issues (#3946)

srawlins · web-flow · commit 652403357037 · 2024-12-30T12:17:28.000-08:00
diff --git a/lib/src/dartdoc_options.dart b/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() {
diff --git a/lib/src/generator/html_generator.dart b/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,
diff --git a/lib/src/generator/templates.dart b/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;
diff --git a/lib/src/model/container_modifiers.dart b/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))
diff --git a/lib/src/model/documentation.dart b/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 {
diff --git a/lib/src/model/documentation_comment.dart b/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
diff --git a/lib/src/model/inheritable.dart b/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
diff --git a/lib/src/model/locatable.dart b/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);
 
diff --git a/lib/src/model/model_element.dart b/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,
diff --git a/lib/src/model/package_graph.dart b/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`.
diff --git a/lib/src/mustachio/annotations.dart b/lib/src/mustachio/annotations.dart
@@ -11,9 +11,8 @@ import 'package:meta/meta.dart';
 
 /// Specifies information for generating both a runtime-interpreted Mustache
 /// renderer and a pre-compiled Mustache renderer for a [context] object, using
-/// a Mustache template located at [standardHtmlTemplate] and at
-/// [standardMdTemplate], for an HTML template, and for a Markdown template,
-/// respectively.
+/// a Mustache template located at [standardHtmlTemplate], for an HTML template,
+/// and for a Markdown template, respectively.
 // Update `test/builder_test_base.dart` when updating this.
 class Renderer {
   /// The name of the render function to generate.
@@ -40,8 +39,8 @@ class Renderer {
   /// render [context] objects.
   ///
   /// [standardTemplateBasename] is used as a basename in an
-  /// Asset URL, in both [standardHtmlTemplate] and [standardMdTemplate],
-  /// in order to render with the out-of-the-box Mustache templates.
+  /// Asset URL, in both [standardHtmlTemplate], in order to render with the
+  /// out-of-the-box Mustache templates.
   const Renderer(
     this.name,
     this.context,
diff --git a/lib/src/tool_definition.dart b/lib/src/tool_definition.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/tool_configuration.dart';
+library;
+
 import 'dart:async';
 
 import 'package:analyzer/file_system/file_system.dart';
@@ -188,8 +191,8 @@ class _Snapshot {
 
   bool _needsSnapshot = true;
 
-  /// Will return true precisely once, unless [snapshotFile] was already a
-  /// snapshot.  In that case, will always return false.
+  /// Returns `true` precisely once, unless [_snapshotFile] was already a
+  /// snapshot.  In that case, will always return `false`.
   bool get needsSnapshot {
     if (_needsSnapshot) {
       _needsSnapshot = false;
diff --git a/test/comment_referable/comment_referable_test.dart b/test/comment_referable/comment_referable_test.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/model_element.dart';
+library;
+
 import 'package:collection/collection.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
 import 'package:dartdoc/src/model/nameable.dart';
diff --git a/test/mustachio/builder_test_base.dart b/test/mustachio/builder_test_base.dart
@@ -101,7 +101,7 @@ Future<LibraryElement> resolveGeneratedLibrary(String libraryPath) async {
 }
 
 extension LibraryExtensions on LibraryElement {
-  /// Returns the top-level function in [this] library, named [name], or `null`
+  /// Returns the top-level function in `this` library, named [name], or `null`
   /// if no function is found.
   FunctionElement? getTopLevelFunction(String name) => topLevelElements
       .whereType<FunctionElement>()
diff --git a/tool/mustachio/codegen_runtime_renderer.dart b/tool/mustachio/codegen_runtime_renderer.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/mustachio/renderer_base.dart';
+library;
+
 import 'dart:collection';
 
 import 'package:analyzer/dart/element/element.dart';
@@ -268,7 +271,7 @@ import '${path.basename(_sourceUri.path)}';
     }
   }
 
-  /// Adds [type] to the [_typesToProcess] queue, if it is not already there.
+  /// Adds [element] to the [_typesToProcess] queue, if it is not already there.
   void _addTypeToProcess(
     InterfaceElement element, {
     required bool isFullRenderer,
diff --git a/tool/src/io_utils.dart b/tool/src/io_utils.dart
@@ -9,12 +9,10 @@ import 'dart:io';
 
 final String _sep = Platform.pathSeparator;
 
-/// Copy the given entity to the destination directory.
-///
-/// Note that the [context] parameter is deprecated.
-void copy(FileSystemEntity entity, Directory destDir) {
-  print('copying ${entity.path} to ${destDir.path}');
-  return _copyImpl(entity, destDir);
+/// Copies the given [entity] to the [destinationDir].
+void copy(FileSystemEntity entity, Directory destinationDir) {
+  print('copying ${entity.path} to ${destinationDir.path}');
+  return _copyImpl(entity, destinationDir);
 }
 
 void _copyImpl(FileSystemEntity? entity, Directory destDir) {

Original file line number	Diff line number	Diff line change
`@@ -43,7 +43,7 @@ class ContainerModifier implements Comparable<ContainerModifier> {`
`43`	`43`	`}`
`44`	`44`
`45`	`45`	`extension BuildLanguageFeatureSet on Iterable<ContainerModifier> {`
`46`		`- /// Transforms [ContainerModifiers] into a series of [LanguageFeature] objects`
	`46`	`+ /// Transforms [ContainerModifier]s into a series of [LanguageFeature] objects`
`47`	`47`	`/// suitable for rendering as chips. Assumes iterable is sorted.`
`48`	`48`	`Iterable<LanguageFeature> get asLanguageFeatureSet =>`
`49`	`49`	`where((m) => !m.hideIfPresent.any(contains))`
Original file line number	Diff line number	Diff line change
`@@ -255,7 +255,7 @@ abstract class ModelElement`
`255`	`255`	`return newModelElement;`
`256`	`256`	`}`
`257`	`257`
`258`		`- /// Caches a newly-created [ModelElement] from [ModelElement._from] or`
	`258`	`+ /// Caches a newly-created [ModelElement] from [ModelElement.for_] or`
`259`	`259`	`/// [ModelElement.forPropertyInducingElement].`
`260`	`260`	`static void _cacheNewModelElement(`
`261`	`261`	`Element e, ModelElement newModelElement, Library library,`