Improve issue/pr/repo view documentation

mislav · mislav · commit d1754b2bb065 · 2020-04-08T12:04:39.000+02:00
- Short-form docs for `pr/repo view` no longer say "in browser"

- Long-form docs for all these commands now list more information about
  what will be displayed in the terminal, plus stressing out the
  alternate behavior with the `--web` flag.

- `--web` flag docs: add English articles
diff --git a/command/issue.go b/command/issue.go
@@ -38,7 +38,7 @@ func init() {
 	issueListCmd.Flags().StringP("author", "A", "", "Filter by author")
 
 	issueCmd.AddCommand(issueViewCmd)
-	issueViewCmd.Flags().BoolP("web", "w", false, "Open issue in browser")
+	issueViewCmd.Flags().BoolP("web", "w", false, "Open an issue in the browser")
 }
 
 var issueCmd = &cobra.Command{
@@ -74,7 +74,10 @@ var issueViewCmd = &cobra.Command{
 		return nil
 	},
 	Short: "View an issue",
-	RunE:  issueView,
+	Long: `Display the title, body, and other information about an issue.
+
+With '--web', open the issue in a web browser instead.`,
+	RunE: issueView,
 }
 
 func issueList(cmd *cobra.Command, args []string) error {
diff --git a/command/pr.go b/command/pr.go
@@ -31,7 +31,7 @@ func init() {
 	prListCmd.Flags().StringSliceP("label", "l", nil, "Filter by label")
 	prListCmd.Flags().StringP("assignee", "a", "", "Filter by assignee")
 
-	prViewCmd.Flags().BoolP("web", "w", false, "Open pull request in browser")
+	prViewCmd.Flags().BoolP("web", "w", false, "Open a pull request in the browser")
 }
 
 var prCmd = &cobra.Command{
@@ -56,11 +56,13 @@ var prStatusCmd = &cobra.Command{
 }
 var prViewCmd = &cobra.Command{
 	Use:   "view [{<number> | <url> | <branch>}]",
-	Short: "View a pull request in the browser",
-	Long: `View a pull request specified by the argument.
+	Short: "View a pull request",
+	Long: `Display the title, body, and other information about a pull request.
 
-Without an argument, the pull request that belongs to the current
-branch is displayed.`,
+Without an argument, the pull request that belongs to the current branch
+is displayed.
+
+With '--web', open the pull request in a web browser instead.`,
 	RunE: prView,
 }
 
diff --git a/command/repo.go b/command/repo.go
@@ -37,7 +37,7 @@ func init() {
 	repoForkCmd.Flags().Lookup("remote").NoOptDefVal = "true"
 
 	repoCmd.AddCommand(repoViewCmd)
-	repoViewCmd.Flags().BoolP("web", "w", false, "Open repository in browser")
+	repoViewCmd.Flags().BoolP("web", "w", false, "Open a repository in the browser")
 }
 
 var repoCmd = &cobra.Command{
@@ -80,10 +80,12 @@ With no argument, creates a fork of the current repository. Otherwise, forks the
 
 var repoViewCmd = &cobra.Command{
 	Use:   "view [<repository>]",
-	Short: "View a repository in the browser",
-	Long: `View a GitHub repository.
+	Short: "View a repository",
+	Long: `Display the description and the README of a GitHub repository.
 
-With no argument, the repository for the current directory is displayed.`,
+With no argument, the repository for the current directory is displayed.
+
+With '--web', open the repository in a web browser instead.`,
 	RunE: repoView,
 }
 
