Deprecate the --nodoc Option (#3690)

Author: srawlins

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 8.0.7-wip
+
+* Deprecate the `--nodoc` option. (#3690)
+
 ## 8.0.6
 
 * Add troubleshooting information when the sidebars failed to load. (#3643)

dartdoc_options.yaml

@@ -1,4 +1,4 @@
 dartdoc:
   linkToSource:
     root: '.'
-    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v8.0.6/%f%#L%l%'
+    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v8.0.7-wip/%f%#L%l%'

lib/src/dartdoc_options.dart

@@ -1652,13 +1652,13 @@ List<DartdocOption> createDartdocOptions(
             help: 'Allow links to be generated for packages outside this one.',
             negatable: true),
       ]),
-    // TODO(srawlins): Deprecate; with the advent of the unnamed library, this
-    // should be applied in each file, on the `library;` directive.
+    // Deprecated. Use of this option is reported.
+    // TODO(srawlins): Remove.
     DartdocOptionFileOnly<List<String>>('nodoc', [], resourceProvider,
         optionIs: OptionKind.glob,
-        help: 'Dart symbols declared in these files will be treated as though '
-            'they have the @nodoc directive added to their documentation '
-            'comment.'),
+        help: '(deprecated) Dart symbols declared in these files will be '
+            'treated as though they have the @nodoc directive added to their '
+            'documentation comment.'),
     DartdocOptionArgOnly<String>('output',
         resourceProvider.pathContext.join('doc', 'api'), resourceProvider,
         optionIs: OptionKind.dir, help: 'Path to the output directory.'),
@@ -1690,13 +1690,10 @@ List<DartdocOption> createDartdocOptions(
           (option.root['topLevelPackageMeta'].valueAt(dir) as PackageMeta)
               .requiresFlutter) {
         String? flutterRoot = option.root['flutterRoot'].valueAt(dir);
-        if (flutterRoot == null) {
-          // For now, return null. An error is reported in
-          // [PackageBuilder.buildPackageGraph].
-          return null;
-        }
-        return resourceProvider.pathContext
-            .join(flutterRoot, 'bin', 'cache', 'dart-sdk');
+        return flutterRoot == null
+            ? null
+            : resourceProvider.pathContext
+                .join(flutterRoot, 'bin', 'cache', 'dart-sdk');
       }
       return packageMetaProvider.defaultSdkDir.path;
     }, packageMetaProvider.resourceProvider,

lib/src/model/package_graph.dart

@@ -927,6 +927,13 @@ class PackageGraph with CommentReferable, Nameable {
       // a context is again, slow.
       var globs = (config.optionSet['nodoc'].valueAt(file.parent) as List)
           .cast<String>();
+      if (globs.isNotEmpty) {
+        packageGraph.defaultPackage.warn(
+          PackageWarning.deprecated,
+          message:
+              "The '--nodoc' option is deprecated, and will soon be removed.",
+        );
+      }
       return utils.matchGlobs(globs, fullName);
     });
   }

lib/src/version.dart

@@ -1 +1 @@
-const packageVersion = '8.0.6';
+const packageVersion = '8.0.7-wip';

pubspec.yaml

@@ -1,5 +1,5 @@
 name: dartdoc
-version: 8.0.6
+version: 8.0.7-wip
 description: A non-interactive HTML documentation generator for Dart source code.
 repository: https://github.com/dart-lang/dartdoc