Add AsyncParsableCommand to README (#565)

* See issue #561

Author: robertmryan

README.md

@@ -6,6 +6,8 @@ Begin by declaring a type that defines the information
 that you need to collect from the command line.
 Decorate each stored property with one of `ArgumentParser`'s property wrappers,
 and then declare conformance to `ParsableCommand` and add the `@main` attribute.
+(Note, for `async` renditions of `run`, conform to `AsyncParsableCommand` rather
+than `ParsableCommand`.) 
 Finally, implement your command's logic in the `run()` method.
 
 ```swift
@@ -74,6 +76,7 @@ For guides, articles, and API documentation see the
 - [ArgumentParser documentation][docs]
 - [Getting Started with ArgumentParser](https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser/gettingstarted)
 - [`ParsableCommand` documentation](https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser/parsablecommand)
+- [`AsyncParsableCommand` documentation](https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser/asyncparsablecommand)
 
 [docs]: https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser
 

Sources/ArgumentParser/Documentation.docc/ArgumentParser.md

@@ -10,7 +10,8 @@ Begin by declaring a type that defines
 the information that you need to collect from the command line.
 Decorate each stored property with one of `ArgumentParser`'s property wrappers,
 declare conformance to ``ParsableCommand``,
-and implement your command's logic in its `run()` method.
+and implement your command's logic in its `run()` method. 
+For `async` renditions of `run`, declare ``AsyncParsableCommand`` conformance instead.
 
 ```swift
 import ArgumentParser

Sources/ArgumentParser/Documentation.docc/Articles/GettingStarted.md

@@ -287,3 +287,31 @@ struct RuntimeError: Error, CustomStringConvertible {
     }
 }
 ```
+
+
+## Next Steps … Swift concurrency
+
+`ArgumentParser` supports Swift concurrency, notably `async` renditions of `run`. If you use `async` rendition of `run`, conform to `AsyncParsableCommand` instead of `ParsableCommand`.
+
+```swift
+@main
+struct FileUtility: AsyncParsableCommand {
+    @Argument(
+        help: "File to be parsed.",
+        transform: URL.init(fileURLWithPath:)
+    )
+    var file: URL
+
+    mutating func run() async throws {
+        let handle = try FileHandle(forReadingFrom: file)
+
+        for try await line in handle.bytes.lines {
+            // do something with each line
+        }
+
+        try handle.close()
+    }
+}
+```
+
+> Note: If you accidentally use `ParsableCommand` with an `async` rendition of `run`, the app may never reach your `run` function and may only show the `USAGE` text. If you are using `async` version of `run`, you must use `AsyncParsableCommand`.

Sources/ArgumentParser/Documentation.docc/Articles/Validation.md

@@ -8,7 +8,7 @@ While `ArgumentParser` validates that the inputs given by your user match the re
 
 ### Validating Command-Line Input
 
-To validate your commands properties after parsing, implement the ``ParsableArguments/validate()-5r0ge`` method on any ``ParsableCommand`` or ``ParsableArguments`` type. Throwing an error from the `validate()` method causes the program to print a message to standard error and exit with an error code, preventing the `run()` method from being called with invalid inputs.
+To validate your commands properties after parsing, implement the ``ParsableArguments/validate()-5r0ge`` method on any ``ParsableCommand``, ``ParsableArguments``, or ``AsyncParsableCommand`` type. Throwing an error from the `validate()` method causes the program to print a message to standard error and exit with an error code, preventing the `run()` method from being called with invalid inputs.
 
 Here's a command that prints out one or more random elements from the list you provide. Its `validate()` method catches three different errors that a user can make and throws a relevant error for each one.