From 3d56168db7e5d644eefe368b3941d67da1670fc6 Mon Sep 17 00:00:00 2001
From: Sam Rawlins <srawlins@google.com>
Date: Fri, 8 Mar 2024 10:40:51 -0800
Subject: [PATCH] Add some help messages to tool/task.dart (#3707)

There has been basically no help text, which doesn't help anyone. :D So now the following invocations work as you'd expect:

* `dart tool/task.dart help`
* `dart tool/task.dart help doc`
* `dart tool/task.dart doc help`
---
 tool/task.dart | 60 +++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 55 insertions(+), 5 deletions(-)

diff --git a/tool/task.dart b/tool/task.dart
index 862fbc984f..d6f66462ff 100644
--- a/tool/task.dart
+++ b/tool/task.dart
@@ -26,14 +26,15 @@ void main(List<String> args) async {
     ..addCommand('buildbot')
     ..addCommand('clean')
     ..addCommand('compare')
+    ..addCommand('help')
     ..addCommand('test')
     ..addCommand('try-publish')
     ..addCommand('validate');
-  parser.addCommand('doc')
-    ..addOption('name')
-    ..addOption('version')
-    ..addFlag('stats');
-  parser.addCommand('serve')
+  var docCommand = parser.addCommand('doc')
+    ..addOption('name', help: 'package name')
+    ..addOption('version', help: 'package version')
+    ..addFlag('stats', help: 'print runtime stats');
+  var serveCommand = parser.addCommand('serve')
     ..addOption('name')
     ..addOption('version');
 
@@ -43,6 +44,9 @@ void main(List<String> args) async {
     return;
   }
 
+  docUsage = docCommand.usage;
+  serveUsage = serveCommand.usage;
+
   return await switch (commandResults.name) {
     'analyze' => runAnalyze(commandResults),
     'build' => runBuild(commandResults),
@@ -50,6 +54,7 @@ void main(List<String> args) async {
     'clean' => runClean(),
     'compare' => runCompare(commandResults),
     'doc' => runDoc(commandResults),
+    'help' => runHelp(commandResults),
     'serve' => runServe(commandResults),
     'test' => runTest(),
     'try-publish' => runTryPublish(),
@@ -58,6 +63,9 @@ void main(List<String> args) async {
   };
 }
 
+late String docUsage;
+late String serveUsage;
+
 String _getPackageVersion() {
   var pubspec = File('pubspec.yaml');
   if (!pubspec.existsSync()) {
@@ -288,6 +296,7 @@ Future<void> runDoc(ArgResults commandResults) async {
   var stats = commandResults['stats'];
   await switch (target) {
     'flutter' => docFlutter(withStats: stats),
+    'help' => _docHelp(),
     'package' => _docPackage(commandResults, withStats: stats),
     'sdk' => docSdk(),
     'testing-package' => docTestingPackage(),
@@ -360,6 +369,14 @@ Future<Iterable<Map<String, Object?>>> _docFlutter({
 final Directory flutterDir =
     Directory.systemTemp.createTempSync('flutter').absolute;
 
+Future<void> _docHelp() async {
+  print('''
+Usage:
+dart tool/task.dart doc [flutter|package|sdk|testing-package]
+$docUsage
+''');
+}
+
 Future<void> _docPackage(
   ArgResults commandResults, {
   bool withStats = false,
@@ -577,6 +594,30 @@ String get _dartdocOriginalBranch {
   return branch;
 }
 
+Future<void> runHelp(ArgResults commandResults) async {
+  if (commandResults.rest.isEmpty) {
+    // TODO(srawlins): Add more help for more individual commands.
+    print('''
+Usage:
+    dart tool/task.dart [analyze|build|buildbot|clean|compare|doc|help|serve|test|tryp-publish|validate] options...
+
+Help usage:
+    dart tool/task.dart help [doc|serve]
+''');
+    return;
+  }
+  if (commandResults.rest.length != 1) {
+    throw ArgumentError('"help" command requires a single command name.');
+  }
+  var command = commandResults.rest.single;
+  return switch (command) {
+    'doc' => _docHelp(),
+    'serve' => _serveHelp(),
+    _ => throw UnimplementedError(
+        'Unknown command: "$command", or no specific help text'),
+  };
+}
+
 Future<void> runServe(ArgResults commandResults) async {
   if (commandResults.rest.length != 1) {
     throw ArgumentError('"serve" command requires a single target.');
@@ -584,6 +625,7 @@ Future<void> runServe(ArgResults commandResults) async {
   var target = commandResults.rest.single;
   await switch (target) {
     'flutter' => serveFlutterDocs(),
+    'help' => _serveHelp(),
     'package' => _servePackageDocs(commandResults),
     'sdk' => serveSdkDocs(),
     'testing-package' => serveTestingPackageDocs(),
@@ -608,6 +650,14 @@ Future<void> serveFlutterDocs() async {
   ]);
 }
 
+Future<void> _serveHelp() async {
+  print('''
+Usage:
+dart tool/task.dart serve [flutter|package|sdk|testing-package]
+$docUsage
+''');
+}
+
 Future<void> _servePackageDocs(ArgResults commandResults) async {
   var name = commandResults['name'] as String;
   var version = commandResults['version'] as String?;