From d1754b2bb065df2bcaaf953f28b6c905491304c1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mislav=20Marohni=C4=87?= <mislav.marohnic@gmail.com>
Date: Wed, 8 Apr 2020 12:04:39 +0200
Subject: [PATCH] Improve `issue/pr/repo view` documentation

- 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
---
 command/issue.go |  7 +++++--
 command/pr.go    | 12 +++++++-----
 command/repo.go  | 10 ++++++----
 3 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/command/issue.go b/command/issue.go
index 9e57556e1..fd2e03eef 100644
--- 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
index e494d88b5..c87010365 100644
--- 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
index 5e16f9645..43a28a2fa 100644
--- 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,
 }