Add docs to release create/upload

pkg/cmd/release/create/create.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 
 	"github.com/AlecAivazis/survey/v2"
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/internal/config"
 	"github.com/cli/cli/internal/ghrepo"
 	"github.com/cli/cli/internal/run"
@@ -62,7 +63,20 @@ func NewCmdCreate(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Co
 	cmd := &cobra.Command{
 		Use:   "create <tag> [<files>...]",
 		Short: "Create a new release",
-		Args:  cobra.MinimumNArgs(1),
+		Long: heredoc.Doc(`
+			Create a new GitHub Release for a repository.
+
+			A list of asset files may be given to upload to the new release. To define a
+			display label for an asset, append text starting with '#' after the file name.
+		`),
+		Example: heredoc.Doc(`
+			# use release notes from a file
+			$ gh release create v1.2.3 -F changelog.md
+
+			# upload a release asset with a display label
+			$ gh release create v1.2.3 '/path/to/asset.zip#My display label'
+		`),
+		Args: cobra.MinimumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override
 			opts.BaseRepo = f.BaseRepo

pkg/cmd/release/upload/upload.go

@@ -5,6 +5,7 @@ import (
 	"net/http"
 	"strings"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/internal/ghrepo"
 	"github.com/cli/cli/pkg/cmd/release/shared"
 	"github.com/cli/cli/pkg/cmdutil"
@@ -35,7 +36,13 @@ func NewCmdUpload(f *cmdutil.Factory, runF func(*UploadOptions) error) *cobra.Co
 	cmd := &cobra.Command{
 		Use:   "upload <tag> <files>...",
 		Short: "Upload assets to a release",
-		Args:  cobra.MinimumNArgs(2),
+		Long: heredoc.Doc(`
+			Upload asset files to a GitHub Release.
+
+			To define a display label for an asset, append text starting with '#' after the
+			file name.
+		`),
+		Args: cobra.MinimumNArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override
 			opts.BaseRepo = f.BaseRepo

pkg/cmd/release/view/view.go

@@ -35,7 +35,7 @@ func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Comman
 		Use:   "view [<tag>]",
 		Short: "View information about a release",
 		Long: heredoc.Doc(`
-			View information about a GitHub release.
+			View information about a GitHub Release.
 
 			Without an explicit tag name argument, the latest release in the project
 			is shown.