Deprecate the 'include-externals' option. (#3694)

I cannot see that this is used anywhere. We also have no tests for it. The
documentation is minimal. It was added 8 years ago! How time flies!

I suspect this was put in place for Flutter, and Flutter switched to using
the newer `--auto-include-dependencies` option.

lib/src/dartdoc.dart

@@ -188,6 +188,14 @@ 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/model/package_builder.dart

@@ -39,6 +39,10 @@ abstract class PackageBuilder {
   Future<PackageGraph> buildPackageGraph();
 
   Future<void> dispose();
+
+  /// 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.
@@ -283,7 +287,11 @@ class PubPackageBuilder implements PackageBuilder {
       }
       files.addAll(newFiles);
       if (!addingSpecials) {
-        files.addAll(_includedExternalsFrom(newFiles));
+        var externals = _includedExternalsFrom(newFiles);
+        if (externals.isNotEmpty) {
+          includeExternalsWasSpecified = true;
+        }
+        files.addAll(externals);
       }
 
       var packages = _packageMetasForFiles(files.difference(_knownParts));
@@ -437,14 +445,21 @@ class PubPackageBuilder implements PackageBuilder {
             includeDependencies: _config.autoIncludeDependencies,
             filterExcludes: true,
           ).toList();
-    files = [...files, ..._includedExternalsFrom(files)];
+    var externals = _includedExternalsFrom(files);
+    if (externals.isNotEmpty) {
+      includeExternalsWasSpecified = true;
+    }
+    files = [...files, ...externals];
     return {
       ...files
           .map((s) => _pathContext.absolute(_resourceProvider.getFile(s).path)),
       ..._embedderSdkFiles,
     };
   }
 
+  @override
+  bool includeExternalsWasSpecified = false;
+
   Iterable<String> get _embedderSdkFiles => [
         for (var dartUri in _embedderSdkUris)
           _pathContext.absolute(_resourceProvider