From c706d6ade0f0ea8e5c95380ad6443ad5c9227848 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Thu, 27 Mar 2025 10:29:22 -0700 Subject: [PATCH 1/3] Bump to 9.0.0-dev --- CHANGELOG.md | 4 ++++ dartdoc_options.yaml | 2 +- lib/src/version.dart | 2 +- pubspec.yaml | 2 +- testing/test_package/lib/src/nodocme.dart | 11 ----------- 5 files changed, 7 insertions(+), 14 deletions(-) delete mode 100644 testing/test_package/lib/src/nodocme.dart diff --git a/CHANGELOG.md b/CHANGELOG.md index ecbb21a51c..4d856430fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +## 9.0.0-dev + +* Remove the deprecated `nodoc` option. + ## 8.3.3 * Require Dart 3.6 or later. diff --git a/dartdoc_options.yaml b/dartdoc_options.yaml index 01513eea5a..be4c175df8 100644 --- a/dartdoc_options.yaml +++ b/dartdoc_options.yaml @@ -1,4 +1,4 @@ dartdoc: linkToSource: root: '.' - uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v8.3.3/%f%#L%l%' + uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v9.0.0-dev/%f%#L%l%' diff --git a/lib/src/version.dart b/lib/src/version.dart index dfdd62ad95..15a50c49dc 100644 --- a/lib/src/version.dart +++ b/lib/src/version.dart @@ -1 +1 @@ -const packageVersion = '8.3.3'; +const packageVersion = '9.0.0-dev'; diff --git a/pubspec.yaml b/pubspec.yaml index c951c220f7..a4e6d636ba 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,5 +1,5 @@ name: dartdoc -version: 8.3.3 +version: 9.0.0-dev description: A non-interactive HTML documentation generator for Dart source code. repository: https://github.com/dart-lang/dartdoc diff --git a/testing/test_package/lib/src/nodocme.dart b/testing/test_package/lib/src/nodocme.dart deleted file mode 100644 index 707a399fb6..0000000000 --- a/testing/test_package/lib/src/nodocme.dart +++ /dev/null @@ -1,11 +0,0 @@ -/// -/// The library nodocme should never have any members documented, even if -/// reexported, due to dartdoc_options.yaml in the package root. -/// - -library nodocme; - -/// I should not appear in documentation. -class NodocMeImplementation {} - -class MeNeitherEvenWithoutADocComment {} From d7ca34a019f05846e7ebd5a34d69ed88115a5f3d Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Thu, 27 Mar 2025 10:29:34 -0700 Subject: [PATCH 2/3] Remove the deprecated nodoc option --- lib/src/dartdoc_options.dart | 9 ---- lib/src/model/documentation_comment.dart | 6 --- lib/src/model/package_graph.dart | 55 +++++------------------ test/end2end/model_test.dart | 16 ------- testing/test_package/dartdoc_options.yaml | 1 - 5 files changed, 10 insertions(+), 77 deletions(-) diff --git a/lib/src/dartdoc_options.dart b/lib/src/dartdoc_options.dart index 79c1a2a59c..4a09f99f08 100644 --- a/lib/src/dartdoc_options.dart +++ b/lib/src/dartdoc_options.dart @@ -1207,8 +1207,6 @@ class DartdocOptionContext extends DartdocOptionContextBase // ignore: unused_element String get _linkToHosted => optionSet['linkTo']['hosted'].valueAt(context); - List get nodoc => optionSet['nodoc'].valueAt(context); - String get output => optionSet['output'].valueAt(context); PackageMeta get packageMeta => optionSet['packageMeta'].valueAt(context); @@ -1504,13 +1502,6 @@ List createDartdocOptions( help: 'Allow links to be generated for packages outside this one.', negatable: true), ]), - // Deprecated. Use of this option is reported. - // TODO(srawlins): Remove. - DartdocOptionFileOnly>('nodoc', [], resourceProvider, - optionIs: OptionKind.glob, - help: '(deprecated) Dart symbols declared in these files will be ' - 'treated as though they have the @nodoc directive added to their ' - 'documentation comment.'), DartdocOptionArgOnly('output', resourceProvider.pathContext.join('doc', 'api'), resourceProvider, optionIs: OptionKind.dir, help: 'Path to the output directory.'), diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index 0d7522eda0..5b2e301ccf 100644 --- a/lib/src/model/documentation_comment.dart +++ b/lib/src/model/documentation_comment.dart @@ -85,15 +85,9 @@ mixin DocumentationComment /// dartdoc's generated output. /// /// An element is considered to be 'nodoc' if any of the following are true: - /// * a global 'nodoc' configuration has been set for this element (this - /// feature is deprecated), /// * the element has no documentation comment, /// * the documentation comment contains the `@nodoc` dartdoc directive. late final bool hasNodoc = () { - if (packageGraph - .configSetsNodocFor(element.library2!.firstFragment.source.fullName)) { - return true; - } if (!hasDocumentationComment) { return false; } diff --git a/lib/src/model/package_graph.dart b/lib/src/model/package_graph.dart index 398378a4a3..bc1ef3a4fb 100644 --- a/lib/src/model/package_graph.dart +++ b/lib/src/model/package_graph.dart @@ -170,15 +170,14 @@ class PackageGraph with CommentReferable, Nameable { e.canonicalModelElement == null || e is Library || e.enclosingElement!.isCanonical) { - for (var d in e.documentationFrom - .where((d) => d.hasDocumentationComment)) { + for (var d + in e.documentationFrom.where((d) => d.hasDocumentationComment)) { if (d.needsPrecache && !precachedElements.contains(d)) { precachedElements.add(d as ModelElement); futures.add(d.precacheLocalDocs()); // [TopLevelVariable]s get their documentation from getters and // setters, so should be precached if either has a template. - if (e is TopLevelVariable && - !precachedElements.contains(e)) { + if (e is TopLevelVariable && !precachedElements.contains(e)) { precachedElements.add(e); futures.add(e.precacheLocalDocs()); } @@ -647,7 +646,8 @@ class PackageGraph with CommentReferable, Nameable { checkAndAddContainer(modelElement, container); } } else if (container is Mixin) { - for (var modelElement in container.superclassConstraints.modelElements) { + for (var modelElement + in container.superclassConstraints.modelElements) { checkAndAddContainer(modelElement, container); } } @@ -752,8 +752,7 @@ class PackageGraph with CommentReferable, Nameable { // TODO(keertip): Find a better way to exclude members of extensions // when libraries are specified using the "--include" flag. if (library != null && library.isDocumented) { - return getModelFor(e, library, - enclosingContainer: preferredClass); + return getModelFor(e, library, enclosingContainer: preferredClass); } } // TODO(jcollins-g): The data structures should be changed to eliminate @@ -778,8 +777,7 @@ class PackageGraph with CommentReferable, Nameable { var setterElement = setter2 == null ? null : getModelFor(setter2, library) as Accessor; - canonicalModelElement = getModelForPropertyInducingElement( - e, library, + canonicalModelElement = getModelForPropertyInducingElement(e, library, getter: getterElement, setter: setterElement); } else { canonicalModelElement = getModelFor(e, library); @@ -791,8 +789,7 @@ class PackageGraph with CommentReferable, Nameable { } } // Prefer fields and top-level variables. - if (e is PropertyAccessorElement2 && - canonicalModelElement is Accessor) { + if (e is PropertyAccessorElement2 && canonicalModelElement is Accessor) { canonicalModelElement = canonicalModelElement.enclosingCombo; } return canonicalModelElement; @@ -804,8 +801,8 @@ class PackageGraph with CommentReferable, Nameable { var elem = modelElement.element; var candidates = {}; if (lib != null) { - var constructedWithKey = allConstructedModelElements[ - ConstructedModelElementsKey(elem, null)]; + var constructedWithKey = + allConstructedModelElements[ConstructedModelElementsKey(elem, null)]; if (constructedWithKey != null) { candidates.add(constructedWithKey); } @@ -909,38 +906,6 @@ class PackageGraph with CommentReferable, Nameable { return allElements; } - /// Cache of 'nodoc' configurations. - /// - /// Glob lookups can be expensive, so cache per filename. - final _configSetsNodocFor = HashMap(); - - /// Given an element's [fullName], look up the nodoc configuration data and - /// determine whether to unconditionally treat the element as "nodoc", an - /// attribute indicating that documentation should not be included in - /// dartdoc's generated output. - /// - /// This configuration setting is deprecated. - bool configSetsNodocFor(String fullName) { - return _configSetsNodocFor.putIfAbsent(fullName, () { - var file = resourceProvider.getFile(fullName); - // Direct lookup instead of generating a custom context will save some - // cycles. We can't use the element's [DartdocOptionContext] because that - // might not be where the element was defined, which is what's important - // for nodoc's semantics. Looking up the defining element just to pull - // a context is again, slow. - var globs = (config.optionSet['nodoc'].valueAt(file.parent) as List) - .cast(); - if (globs.isNotEmpty) { - packageGraph.defaultPackage.warn( - PackageWarning.deprecated, - message: - "The '--nodoc' option is deprecated, and will soon be removed.", - ); - } - return utils.matchGlobs(globs, fullName); - }); - } - /// Returns a macro by [name], or `null` if no macro is found. String? getMacro(String name) { assert(_localDocumentationBuilt); diff --git a/test/end2end/model_test.dart b/test/end2end/model_test.dart index 6fb5b8b493..2d739dd852 100644 --- a/test/end2end/model_test.dart +++ b/test/end2end/model_test.dart @@ -1153,22 +1153,6 @@ void main() async { }); }); - group('Comment processing', () { - test('can virtually add nodoc via options file', () { - var NodocMeLibrary = - packageGraph.defaultPackage.allLibraries.named('nodocme'); - expect(NodocMeLibrary.hasNodoc, isTrue); - var NodocMeImplementation = - fakeLibrary.classes.named('NodocMeImplementation'); - expect(NodocMeImplementation.hasNodoc, isTrue); - expect(NodocMeImplementation.isPublic, isFalse); - var MeNeitherEvenWithoutADocComment = - fakeLibrary.classes.named('MeNeitherEvenWithoutADocComment'); - expect(MeNeitherEvenWithoutADocComment.hasNodoc, isTrue); - expect(MeNeitherEvenWithoutADocComment.isPublic, isFalse); - }); - }); - group('doc references', () { late final String docsAsHtml; diff --git a/testing/test_package/dartdoc_options.yaml b/testing/test_package/dartdoc_options.yaml index 62cc21fd8f..81b41de0fd 100644 --- a/testing/test_package/dartdoc_options.yaml +++ b/testing/test_package/dartdoc_options.yaml @@ -7,7 +7,6 @@ dartdoc: Unreal: markdown: "Unreal.md" Real Libraries: - nodoc: ["lib/src/nodoc*.dart"] tools: drill: command: ["bin/drill.dart"] From 4c3c608682722298fdb6d2c78bc392162dddfe6b Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Thu, 27 Mar 2025 10:38:22 -0700 Subject: [PATCH 3/3] fix --- testing/test_package/lib/fake.dart | 3 --- 1 file changed, 3 deletions(-) diff --git a/testing/test_package/lib/fake.dart b/testing/test_package/lib/fake.dart index e42bcc10a0..4ed5131e92 100644 --- a/testing/test_package/lib/fake.dart +++ b/testing/test_package/lib/fake.dart @@ -79,9 +79,6 @@ import 'mylibpub.dart' as renamedLib2; import 'two_exports.dart' show BaseClass; export 'src/notadotdartfile'; -// Verify that even though reexported, objects don't show in documentation. -export 'package:test_package/src/nodocme.dart'; - // ignore: uri_does_not_exist export 'package:test_package_imported/categoryExporting.dart' show IAmAClassWithCategories;