diff --git a/lib/src/dartdoc_options.dart b/lib/src/dartdoc_options.dart index 93605a531b..e6852a8569 100644 --- a/lib/src/dartdoc_options.dart +++ b/lib/src/dartdoc_options.dart @@ -194,7 +194,7 @@ class _OptionValueWithContext { /// 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 implements DartdocOption { 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? _valueAtFromFilesFirstFound(Folder folder) { _OptionValueWithContext? value; for (var dir in folder.withAncestors) { @@ -975,8 +975,8 @@ mixin _DartdocArgOption implements DartdocOption { '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? _valueAtFromArgsWithContext() { diff --git a/lib/src/generator/html_generator.dart b/lib/src/generator/html_generator.dart index 4db154a715..a3a2623fef 100644 --- 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 initHtmlGenerator( DartdocGeneratorOptionContext context, { required FileWriter writer, diff --git a/lib/src/generator/templates.dart b/lib/src/generator/templates.dart index 20a2ea83bb..4fcd71becb 100644 --- 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 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 index fed36a2561..67a576dd37 100644 --- a/lib/src/model/container_modifiers.dart +++ b/lib/src/model/container_modifiers.dart @@ -43,7 +43,7 @@ class ContainerModifier implements Comparable { } extension BuildLanguageFeatureSet on Iterable { - /// 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 get asLanguageFeatureSet => where((m) => !m.hideIfPresent.any(contains)) diff --git a/lib/src/model/documentation.dart b/lib/src/model/documentation.dart index 89adebfd8e..c9bece4bbe 100644 --- 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 index c4a1b12731..e09d81c624 100644 --- 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 `[digest]` in API comments with /// the contents of the HTML fragment earlier defined by the - /// {@inject-html} directive. The [digest] is a SHA1 of the contents - /// of the HTML fragment, automatically generated upon parsing the + /// {@inject-html} directive. The `[digest]` is a SHA1 of the + /// contents of the HTML fragment, automatically generated upon parsing the /// {@inject-html} 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 index 7ed7e5dc1f..a51840454d 100644 --- 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 index 6198d74b02..f1cdca5cab 100644 --- 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 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 index 1a853babaa..d14de0fade 100644 --- 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 index 7b09625ca2..63a50dd3de 100644 --- 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 index badfce80ee..dc00aae5d2 100644 --- 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 index 8eb9b0455d..15312554fe 100644 --- 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 index 3ebf1efae0..be04c302a1 100644 --- 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 index 7b513f074b..5dadac45eb 100644 --- a/test/mustachio/builder_test_base.dart +++ b/test/mustachio/builder_test_base.dart @@ -101,7 +101,7 @@ Future 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() diff --git a/tool/mustachio/codegen_runtime_renderer.dart b/tool/mustachio/codegen_runtime_renderer.dart index 9bd7c851da..6826aede62 100644 --- 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 index 037b458a95..4d11c9b70f 100644 --- 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) {