feat: polish command docstrings (#213)

* feat: polish command docstrings

* fix(docstring): update wording per review

Co-authored-by: Jake Dawkins <dawkinsjh@gmail.com>

README.md

@@ -32,9 +32,28 @@ rover subgraph fetch --name=pets test@cats
 
 ## Command-line options
 
-```
+```console
+$ rover --help
 Rover 0.0.1-rc.4
-The new CLI for Apollo
+
+Rover - Your Graph Companion
+Read the getting started guide: https://go.apollo.dev/r/start
+
+To begin working with Rover and to authenticate with Apollo Studio, 
+run the following command:
+
+    $ rover config auth
+
+This will prompt you for an API Key that can be generated in Apollo Studio.
+
+The most common commands from there are:
+
+    - rover graph fetch: Fetch a graph schema from the Apollo graph registry
+    - rover graph check: Check for breaking changes in a local graph schema against a graph schema in the Apollo graph
+registry
+    - rover graph push: Push an updated graph schema to the Apollo graph registry
+
+You can find full documentation for Rover here: https://go.apollo.dev/r/docs
 
 USAGE:
     rover [OPTIONS] <SUBCOMMAND>
@@ -48,7 +67,7 @@ OPTIONS:
                              debug, trace]
 
 SUBCOMMANDS:
-    config      Rover configuration
+    config      Configuration profile commands
     graph       Non-federated schema/graph commands
     help        Prints this message or the help of the given subcommand(s)
     subgraph    Federated schema/graph commands

installers/npm/README.md

@@ -32,9 +32,28 @@ rover subgraph fetch --name=pets test@cats
 
 ## Command-line options
 
-```
+```console
+$ rover --help
 Rover 0.0.1-rc.4
-The new CLI for Apollo
+
+Rover - Your Graph Companion
+Read the getting started guide: https://go.apollo.dev/r/start
+
+To begin working with Rover and to authenticate with Apollo Studio, 
+run the following command:
+
+    $ rover config auth
+
+This will prompt you for an API Key that can be generated in Apollo Studio.
+
+The most common commands from there are:
+
+    - rover graph fetch: Fetch a graph schema from the Apollo graph registry
+    - rover graph check: Check for breaking changes in a local graph schema against a graph schema in the Apollo graph
+registry
+    - rover graph push: Push an updated graph schema to the Apollo graph registry
+
+You can find full documentation for Rover here: https://go.apollo.dev/r/docs
 
 USAGE:
     rover [OPTIONS] <SUBCOMMAND>
@@ -48,7 +67,7 @@ OPTIONS:
                              debug, trace]
 
 SUBCOMMANDS:
-    config      Rover configuration
+    config      Configuration profile commands
     graph       Non-federated schema/graph commands
     help        Prints this message or the help of the given subcommand(s)
     subgraph    Federated schema/graph commands

src/cli.rs

@@ -31,10 +31,11 @@ This will prompt you for an API Key that can be generated in Apollo Studio.
 
 The most common commands from there are:
 
-    - rover graph push: Push a schema to Apollo Studio
-    - rover graph check: Validate changes to a graph
+    - rover graph fetch: Fetch a graph schema from the Apollo graph registry
+    - rover graph check: Check for breaking changes in a local graph schema against a graph schema in the Apollo graph registry
+    - rover graph push: Push an updated graph schema to the Apollo graph registry
 
-You can find full documentation for Rover here: https://go.apollo.dev/r
+You can find full documentation for Rover here: https://go.apollo.dev/r/docs
 ")]
 pub struct Rover {
     #[structopt(subcommand)]
@@ -82,7 +83,7 @@ impl Rover {
 
 #[derive(Debug, Serialize, StructOpt)]
 pub enum Command {
-    /// Rover configuration
+    /// Configuration profile commands
     Config(command::Config),
 
     /// Non-federated schema/graph commands

src/command/graph/mod.rs

@@ -17,14 +17,15 @@ pub struct Graph {
 
 #[derive(Debug, Serialize, StructOpt)]
 pub enum Command {
-    /// Fetch a schema from Apollo Studio
+    /// Check for breaking changes in a local graph schema
+    /// against a graph schema in the Apollo graph registry
+    Check(check::Check),
+
+    /// Fetch a graph schema from the Apollo graph registry
     Fetch(fetch::Fetch),
 
-    /// Push a schema to Apollo Studio from a local file
+    /// Push an updated graph schema to the Apollo graph registry
     Push(push::Push),
-
-    /// Validate changes to a graph
-    Check(check::Check),
 }
 
 impl Graph {

src/command/subgraph/mod.rs

@@ -19,20 +19,21 @@ pub struct Subgraph {
 
 #[derive(Debug, Serialize, StructOpt)]
 pub enum Command {
-    /// Check changes to an subgraph
+    /// Check for composition errors and breaking changes caused by an updated subgraph schema
+    /// against the federated graph in the Apollo graph registry
     Check(check::Check),
 
-    /// Delete a subgraph and trigger composition
+    /// Delete a subgraph from the Apollo registry and trigger composition in the graph router
     Delete(delete::Delete),
 
-    /// Fetch a subgraph's schema from Apollo Studio
+    /// Fetch a subgraph schema from the Apollo graph registry
     Fetch(fetch::Fetch),
 
-    /// Push a subgraph's schema from a local file
-    Push(push::Push),
-
-    /// List all subgraphs for a federated graph.
+    /// List all subgraphs for a federated graph
     List(list::List),
+
+    /// Push an updated subgraph schema to the Apollo graph registry and trigger composition in the graph router
+    Push(push::Push),
 }
 
 impl Subgraph {