Improve Documentation (#433)

- document more assumptions about usage context of gitea
- improve some flag descriptions (#432, #377)

Co-authored-by: Norwin <git@nroo.de>
Reviewed-on: https://gitea.com/gitea/tea/pulls/433
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Reviewed-by: 6543 <6543@obermui.de>
Co-authored-by: Norwin <noerw@noreply.gitea.io>
Co-committed-by: Norwin <noerw@noreply.gitea.io>

cmd/pulls/create.go

@@ -18,17 +18,17 @@ var CmdPullsCreate = cli.Command{
 	Name:        "create",
 	Aliases:     []string{"c"},
 	Usage:       "Create a pull-request",
-	Description: "Create a pull-request",
+	Description: "Create a pull-request in the current repo",
 	Action:      runPullsCreate,
 	Flags: append([]cli.Flag{
 		&cli.StringFlag{
 			Name:  "head",
-			Usage: "Set head branch (default is current one)",
+			Usage: "Branch name of the PR source (default is current one). To specify a different head repo, use <user>:<branch>",
 		},
 		&cli.StringFlag{
 			Name:    "base",
 			Aliases: []string{"b"},
-			Usage:   "Set base branch (default is default branch)",
+			Usage:   "Branch name of the PR target (default is repos default branch)",
 		},
 	}, flags.IssuePREditFlags...),
 }

cmd/releases/create.go

@@ -27,11 +27,11 @@ var CmdReleaseCreate = cli.Command{
 	Flags: append([]cli.Flag{
 		&cli.StringFlag{
 			Name:  "tag",
-			Usage: "Tag name",
+			Usage: "Tag name. If the tag does not exist yet, it will be created by Gitea",
 		},
 		&cli.StringFlag{
 			Name:  "target",
-			Usage: "Target refs, branch name or commit id",
+			Usage: "Target branch name or commit hash. Defaults to the default branch of the repo",
 		},
 		&cli.StringFlag{
 			Name:    "title",
@@ -56,7 +56,7 @@ var CmdReleaseCreate = cli.Command{
 		&cli.StringSliceFlag{
 			Name:    "asset",
 			Aliases: []string{"a"},
-			Usage:   "List of files to attach",
+			Usage:   "Path to file attachment. Can be specified multiple times",
 		},
 	}, flags.AllDefaultFlags...),
 }