Remove the include-external option (#4027)

---------

Co-authored-by: Sarah Zakarias <[email protected]>

Author: srawlins

CHANGELOG.md

@@ -1,7 +1,8 @@
 ## 9.0.0-wip
-* Remove deprecated `missingCodeBlockLanguage` warning.
+* Remove the deprecated `missingCodeBlockLanguage` warning.
 * Remove the deprecated `templates-dir` option.
 * Remove the deprecated `nodoc` option.
+* Remove the deprecated `include-external` option.
 
 ## 8.3.4
 * The URL for category pages now uses _category name_ instead of

lib/src/dartdoc.dart

@@ -187,14 +187,6 @@ class Dartdoc {
     runtimeStats.startPerfTask('buildPackageGraph');
     var packageGraph = await packageBuilder.buildPackageGraph();
     runtimeStats.endPerfTask();
-    if (packageBuilder.includeExternalsWasSpecified) {
-      packageGraph.defaultPackage.warn(
-        PackageWarning.deprecated,
-        message:
-            "The '--include-externals' option is deprecated, and will soon be "
-            'removed.',
-      );
-    }
     var libs = packageGraph.libraryCount;
     logInfo("Initialized dartdoc with $libs librar${libs == 1 ? 'y' : 'ies'}");
 

lib/src/dartdoc_options.dart

@@ -1179,9 +1179,6 @@ class DartdocOptionContext extends DartdocOptionContextBase
   late final Set<String> include =
       Set.of(optionSet['include'].valueAt(context));
 
-  List<String> get includeExternal =>
-      optionSet['includeExternal'].valueAt(context);
-
   bool get includeSource => optionSet['includeSource'].valueAt(context);
 
   bool get injectHtml => optionSet['injectHtml'].valueAt(context);
@@ -1394,7 +1391,7 @@ List<DartdocOption> createDartdocOptions(
     DartdocOptionArgOnly<bool>(
         'autoIncludeDependencies', false, resourceProvider,
         help: 'Include all the used libraries into the docs, even the ones not '
-            'in the current package or "include-external"',
+            'in the current package',
         negatable: true),
     DartdocOptionArgFile<List<String>>(
         'categoryOrder', const [], resourceProvider,
@@ -1426,12 +1423,6 @@ List<DartdocOption> createDartdocOptions(
         mustExist: true),
     DartdocOptionArgFile<List<String>>('include', [], resourceProvider,
         help: 'Names of libraries to document.', splitCommas: true),
-    DartdocOptionArgFile<List<String>>('includeExternal', [], resourceProvider,
-        optionIs: OptionKind.file,
-        help: 'Additional (external) dart files to include; use '
-            '"<directory name>/<file name>", as in "lib/material.dart".',
-        mustExist: true,
-        splitCommas: true),
     DartdocOptionArgOnly<bool>('includeSource', true, resourceProvider,
         help: 'Show source code blocks.', negatable: true),
     DartdocOptionArgOnly<bool>('injectHtml', false, resourceProvider,

lib/src/generator/templates.runtime_renderers.dart

@@ -25682,7 +25682,6 @@ const _invisibleGetters = {
     'flutterRoot',
     'hashCode',
     'include',
-    'includeExternal',
     'includeSource',
     'injectHtml',
     'inputDir',

lib/src/model/package_builder.dart

@@ -36,10 +36,6 @@ import 'package:path/path.dart' as p show Context;
 abstract class PackageBuilder {
   // Builds package graph to be used by documentation generator.
   Future<PackageGraph> buildPackageGraph();
-
-  /// The `include-external` option is deprecated, so we track whether it was
-  /// used, to report it.
-  bool get includeExternalsWasSpecified;
 }
 
 /// A package builder that understands pub package format.
@@ -281,11 +277,6 @@ class PubPackageBuilder implements PackageBuilder {
         processedLibraries.add(resolvedLibrary.element);
       }
       files.addAll(newFiles);
-      var externals = _includedExternalsFrom(newFiles);
-      if (externals.isNotEmpty) {
-        includeExternalsWasSpecified = true;
-      }
-      files.addAll(externals);
 
       var packages = _packageMetasForFiles(files.difference(_knownParts));
       filesInCurrentPass = {...files.difference(_knownParts)};
@@ -382,25 +373,11 @@ class PubPackageBuilder implements PackageBuilder {
     return dirs;
   }
 
-  /// Calculates 'includeExternal' based on a list of files.
-  ///
-  /// Assumes each file might be part of a [DartdocOptionContext], and loads
-  /// those objects to find any [DartdocOptionContext.includeExternal]
-  /// configurations therein.
-  List<String> _includedExternalsFrom(Iterable<String> files) => [
-        for (var file in files)
-          ...DartdocOptionContext.fromContext(
-            _config,
-            _config.resourceProvider.getFile(file),
-            _config.resourceProvider,
-          ).includeExternal,
-      ];
-
   /// Returns the set of files that may contain elements that need to be
   /// documented.
   ///
-  /// This takes into account the 'auto-include-dependencies' option, the
-  /// 'exclude' option, and the 'include-external' option.
+  /// This takes into account the 'auto-include-dependencies' option, and the
+  /// 'exclude' option.
   Future<Set<String>> _getFilesToDocument() async {
     if (_config.topLevelPackageMeta.isSdk) {
       return _sdkFilesToDocument
@@ -410,12 +387,7 @@ class PubPackageBuilder implements PackageBuilder {
       var packagesToDocument = await _findPackagesToDocument(
         _config.inputDir,
       );
-      var files = _findFilesToDocumentInPackage(packagesToDocument).toList();
-      var externals = _includedExternalsFrom(files);
-      if (externals.isNotEmpty) {
-        includeExternalsWasSpecified = true;
-        files = [...files, ...externals];
-      }
+      var files = _findFilesToDocumentInPackage(packagesToDocument);
       return {
         ...files.map(
             (s) => _pathContext.absolute(_resourceProvider.getFile(s).path)),
@@ -444,9 +416,6 @@ class PubPackageBuilder implements PackageBuilder {
     };
   }
 
-  @override
-  bool includeExternalsWasSpecified = false;
-
   Iterable<String> get _embedderSdkFiles => [
         for (var dartUri in _embedderSdkUris)
           _pathContext.absolute(_resourceProvider

test/packages_test.dart

@@ -330,35 +330,6 @@ dartdoc:
             packageGraph.packages.singleWhere((p) => p.name == 'one');
         expect(packageOne.documentedWhere, equals(DocumentLocation.missing));
       });
-
-      test(
-          'includes external remote elements when includeExternal is specified',
-          () async {
-        packageOneRoot
-            .getChildAssumingFile('dartdoc_options.yaml')
-            .writeAsStringSync('''
-dartdoc:
-  includeExternal:
-    - bin/script.dart
-  linkTo:
-    url: 'https://mypub.topdomain/%n%/%v%'
-''');
-        var packageGraph = await utils.bootBasicPackage(
-            packageTwoRoot.path, packageMetaProvider, packageConfigProvider,
-            additionalArguments: ['--link-to-remote']);
-
-        expect(packageGraph.packages, hasLength(3));
-        var packageOne =
-            packageGraph.packages.singleWhere((p) => p.name == 'one');
-        expect(packageOne.documentedWhere, equals(DocumentLocation.remote));
-        // TODO(srawlins): Why is there more than one?
-        var libraryScript = packageOne.allLibraries.named('script');
-        var classScript = libraryScript.classesAndExceptions.named('Script');
-        expect(
-            classScript.href,
-            equals(
-                'https://mypub.topdomain/one/0.0.1/script/Script-class.html'));
-      });
     });
 
     group('SDK package', () {

test/src/utils.dart

@@ -47,7 +47,7 @@ Future<DartdocOptionContext> contextFromArgv(
       'dartdoc', [createDartdocOptions], packageMetaProvider);
   optionSet.parseArguments(argv);
   return DartdocOptionContext.fromDefaultContextLocation(
-      optionSet, pubPackageMetaProvider.resourceProvider);
+      optionSet, packageMetaProvider.resourceProvider);
 }
 
 /// Convenience factory to build a [DartdocGeneratorOptionContext] and