Merge pull request 'improve help/docs' (#102) from improve-help into main

Reviewed-on: https://codeberg.org/Cyborus/forgejo-cli/pulls/102

6 files changed, 105 insertions, 21 deletions

diff --git a/src/auth.rs b/src/auth.rs
index d86325f..58b2f80 100644
--- a/src/auth.rs
+++ b/src/auth.rs
@@ -3,10 +3,15 @@ use eyre::OptionExt;
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum AuthCommand {
+    /// Log in to an instance.
+    ///
+    /// Opens an auth page in your browser
     Login,
-    Logout {
-        host: String,
-    },
+    /// Deletes login info for an instance
+    Logout { host: String },
+    /// Add an application token for an instance
+    ///
+    /// Use this if `fj auth login` doesn't work
     AddKey {
         /// The domain name of the forgejo instance.
         host: String,
@@ -15,6 +20,7 @@ pub enum AuthCommand {
         /// The key to add. If not present, the key will be read in from stdin.
         key: Option<String>,
     },
+    /// List all instances you're currently logged into
     List,
 }
 
diff --git a/src/issues.rs b/src/issues.rs
index 130a1ef..a65e3d4 100644
--- a/src/issues.rs
+++ b/src/issues.rs
@@ -11,6 +11,7 @@ use crate::repo::{RepoArg, RepoInfo, RepoName};
 
 #[derive(Args, Clone, Debug)]
 pub struct IssueCommand {
+    /// The local git remote that points to the repo to operate on.
     #[clap(long, short = 'R')]
     remote: Option<String>,
     #[clap(subcommand)]
@@ -19,29 +20,38 @@ pub struct IssueCommand {
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum IssueSubcommand {
+    /// Create a new issue on a repo
     Create {
         title: String,
         #[clap(long)]
         body: Option<String>,
-        #[clap(long, short)]
+        #[clap(long, short, id = "[HOST/]OWNER/REPO")]
         repo: Option<RepoArg>,
     },
+    /// Edit an issue
     Edit {
+        #[clap(id = "[REPO#]ID")]
         issue: IssueId,
         #[clap(subcommand)]
         command: EditCommand,
     },
+    /// Add a comment on an issue
     Comment {
+        #[clap(id = "[REPO#]ID")]
         issue: IssueId,
         body: Option<String>,
     },
+    /// Close an issue
     Close {
+        #[clap(id = "[REPO#]ID")]
         issue: IssueId,
+        /// A comment to leave on the issue before closing it
         #[clap(long, short)]
         with_msg: Option<Option<String>>,
     },
+    /// Search for an issue in a repo
     Search {
-        #[clap(long, short)]
+        #[clap(long, short, id = "[HOST/]OWNER/REPO")]
         repo: Option<RepoArg>,
         query: Option<String>,
         #[clap(long, short)]
@@ -53,12 +63,16 @@ pub enum IssueSubcommand {
         #[clap(long, short)]
         state: Option<State>,
     },
+    /// View an issue's info
     View {
+        #[clap(id = "[REPO#]ID")]
         id: IssueId,
         #[clap(subcommand)]
         command: Option<ViewCommand>,
     },
+    /// Open an issue in your browser
     Browse {
+        #[clap(id = "[REPO#]ID")]
         id: IssueId,
     },
 }
@@ -130,12 +144,11 @@ impl From<State> for forgejo_api::structs::IssueListIssuesQueryState {
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum EditCommand {
-    Title {
-        new_title: Option<String>,
-    },
-    Body {
-        new_body: Option<String>,
-    },
+    /// Edit an issue's title
+    Title { new_title: Option<String> },
+    /// Edit an issue's text content
+    Body { new_body: Option<String> },
+    /// Edit a comment on an issue
     Comment {
         idx: usize,
         new_body: Option<String>,
@@ -144,8 +157,11 @@ pub enum EditCommand {
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum ViewCommand {
+    /// View an issue's title and body. The default
     Body,
+    /// View a specific
     Comment { idx: usize },
+    /// List every comment
     Comments,
 }
 
diff --git a/src/prs.rs b/src/prs.rs
index 9d38d5c..840ae12 100644
--- a/src/prs.rs
+++ b/src/prs.rs
@@ -18,7 +18,7 @@ use crate::{
 
 #[derive(Args, Clone, Debug)]
 pub struct PrCommand {
-    /// The git remote to operate on.
+    /// The local git remote that points to the repo to operate on.
     #[clap(long, short = 'R')]
     remote: Option<String>,
     #[clap(subcommand)]
@@ -60,12 +60,13 @@ pub enum PrSubcommand {
         #[clap(long)]
         body: Option<String>,
         /// The repo to create this issue on
-        #[clap(long, short)]
+        #[clap(long, short, id = "[HOST/]OWNER/REPO")]
         repo: Option<RepoArg>,
     },
     /// View the contents of a pull request
     View {
         /// The pull request to view.
+        #[clap(id = "[REPO#]ID")]
         id: Option<IssueId>,
         #[clap(subcommand)]
         command: Option<ViewCommand>,
@@ -73,6 +74,7 @@ pub enum PrSubcommand {
     /// View the mergability and CI status of a pull request
     Status {
         /// The pull request to view.
+        #[clap(id = "[REPO#]ID")]
         id: Option<IssueId>,
     },
     /// Checkout a pull request in a new branch
@@ -80,6 +82,7 @@ pub enum PrSubcommand {
         /// The pull request to check out.
         ///
         /// Prefix with ^ to get a pull request from the parent repo.
+        #[clap(id = "ID")]
         pr: PrNumber,
         /// The name to give the newly created branch.
         ///
@@ -90,6 +93,7 @@ pub enum PrSubcommand {
     /// Add a comment on a pull request
     Comment {
         /// The pull request to comment on.
+        #[clap(id = "[REPO#]ID")]
         pr: Option<IssueId>,
         /// The text content of the comment.
         ///
@@ -99,6 +103,7 @@ pub enum PrSubcommand {
     /// Edit the contents of a pull request
     Edit {
         /// The pull request to edit.
+        #[clap(id = "[REPO#]ID")]
         pr: Option<IssueId>,
         #[clap(subcommand)]
         command: EditCommand,
@@ -106,6 +111,7 @@ pub enum PrSubcommand {
     /// Close a pull request, without merging.
     Close {
         /// The pull request to close.
+        #[clap(id = "[REPO#]ID")]
         pr: Option<IssueId>,
         /// A comment to add before closing.
         ///
@@ -116,6 +122,7 @@ pub enum PrSubcommand {
     /// Merge a pull request
     Merge {
         /// The pull request to merge.
+        #[clap(id = "[REPO#]ID")]
         pr: Option<IssueId>,
         /// The merge style to use.
         #[clap(long, short = 'M')]
@@ -133,6 +140,7 @@ pub enum PrSubcommand {
     /// Open a pull request in your browser
     Browse {
         /// The pull request to open in your browser.
+        #[clap(id = "[REPO#]ID")]
         id: Option<IssueId>,
     },
 }
diff --git a/src/release.rs b/src/release.rs
index 716c508..fa9d7d7 100644
--- a/src/release.rs
+++ b/src/release.rs
@@ -14,9 +14,11 @@ use crate::{
 
 #[derive(Args, Clone, Debug)]
 pub struct ReleaseCommand {
+    /// The local git remote that points to the repo to operate on.
     #[clap(long, short = 'R')]
     remote: Option<String>,
-    #[clap(long, short)]
+    /// The name of the repository to operate on.
+    #[clap(long, short, id = "[HOST/]OWNER/REPO")]
     repo: Option<RepoArg>,
     #[clap(subcommand)]
     command: ReleaseSubcommand,
@@ -24,6 +26,7 @@ pub struct ReleaseCommand {
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum ReleaseSubcommand {
+    /// Create a new release
     Create {
         name: String,
         #[clap(long, short = 'T')]
@@ -56,6 +59,7 @@ pub enum ReleaseSubcommand {
         #[clap(long, short)]
         prerelease: bool,
     },
+    /// Edit a release's info
     Edit {
         name: String,
         #[clap(long, short = 'n')]
@@ -73,40 +77,45 @@ pub enum ReleaseSubcommand {
         #[clap(long, short)]
         prerelease: Option<bool>,
     },
+    /// Delete a release
     Delete {
         name: String,
         #[clap(long, short = 't')]
         by_tag: bool,
     },
+    /// List all the releases on a repo
     List {
         #[clap(long, short = 'p')]
         include_prerelease: bool,
         #[clap(long, short = 'd')]
         include_draft: bool,
     },
+    /// View a release's info
     View {
         name: String,
         #[clap(long, short = 't')]
         by_tag: bool,
     },
-    Browse {
-        name: Option<String>,
-    },
+    /// Open a release in your browser
+    Browse { name: Option<String> },
+    /// Commands on a release's attached files
     #[clap(subcommand)]
     Asset(AssetCommand),
 }
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum AssetCommand {
+    /// Create a new attachment on a release
     Create {
         release: String,
         path: std::path::PathBuf,
         name: Option<String>,
     },
-    Delete {
-        release: String,
-        asset: String,
-    },
+    /// Remove an attachment from a release
+    Delete { release: String, asset: String },
+    /// Download an attached file
+    ///
+    /// Use `source.zip` or `source.tar.gz` to download the repo archive
     Download {
         release: String,
         asset: String,
diff --git a/src/repo.rs b/src/repo.rs
index f870add..ee67b9b 100644
--- a/src/repo.rs
+++ b/src/repo.rs
@@ -288,6 +288,7 @@ impl std::fmt::Display for RepoArgError {
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum RepoCommand {
+    /// Creates a new repository
     Create {
         repo: String,
 
@@ -304,32 +305,48 @@ pub enum RepoCommand {
         #[clap(long, short)]
         push: bool,
     },
+    /// Fork a repository onto your account
     Fork {
+        #[clap(id = "[HOST/]OWNER/REPO")]
         repo: RepoArg,
         #[clap(long)]
         name: Option<String>,
         #[clap(long, short = 'R')]
         remote: Option<String>,
     },
+    /// View a repo's info
     View {
+        #[clap(id = "[HOST/]OWNER/REPO")]
         name: Option<RepoArg>,
         #[clap(long, short = 'R')]
         remote: Option<String>,
     },
+    /// Clone a repo's code locally
     Clone {
+        #[clap(id = "[HOST/]OWNER/REPO")]
         repo: RepoArg,
         path: Option<PathBuf>,
     },
+    /// Add a star to a repo
     Star {
+        #[clap(id = "[HOST/]OWNER/REPO")]
         repo: RepoArg,
     },
+    /// Take away a star from a repo
     Unstar {
+        #[clap(id = "[HOST/]OWNER/REPO")]
         repo: RepoArg,
     },
+    /// Delete a repository
+    ///
+    /// This cannot be undone!
     Delete {
+        #[clap(id = "[HOST/]OWNER/REPO")]
         repo: RepoArg,
     },
+    /// Open a repository's page in your browser
     Browse {
+        #[clap(id = "[HOST/]OWNER/REPO")]
         name: Option<RepoArg>,
         #[clap(long, short = 'R')]
         remote: Option<String>,
diff --git a/src/user.rs b/src/user.rs
index 2b12867..d38d8b5 100644
--- a/src/user.rs
+++ b/src/user.rs
@@ -6,6 +6,7 @@ use crate::{repo::RepoInfo, SpecialRender};
 
 #[derive(Args, Clone, Debug)]
 pub struct UserCommand {
+    /// The local git remote that points to the repo to operate on.
     #[clap(long, short = 'R')]
     remote: Option<String>,
     #[clap(subcommand)]
@@ -14,46 +15,66 @@ pub struct UserCommand {
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum UserSubcommand {
+    /// Search for a user by username
     Search {
         /// The name to search for
         query: String,
         #[clap(long, short)]
         page: Option<usize>,
     },
+    /// View a user's profile page
     View {
         /// The name of the user to view
+        ///
+        /// Omit to view your own page
         user: Option<String>,
     },
+    /// Open a user's profile page in your browser
     Browse {
         /// The name of the user to open in your browser
+        ///
+        /// Omit to view your own page
         user: Option<String>,
     },
+    /// Follow a user
     Follow {
         /// The name of the user to follow
         user: String,
     },
+    /// Unfollow a user
     Unfollow {
         /// The name of the user to follow
         user: String,
     },
+    /// List everyone a user's follows
     Following {
         /// The name of the user whose follows to list
+        ///
+        /// Omit to view your own follows
         user: Option<String>,
     },
+    /// List a user's followers
     Followers {
         /// The name of the user whose followers to list
+        ///
+        /// Omit to view your own followers
         user: Option<String>,
     },
+    /// Block a user
     Block {
         /// The name of the user to block
         user: String,
     },
+    /// Unblock a user
     Unblock {
         /// The name of the user to unblock
         user: String,
     },
+    /// List a user's repositories
     Repos {
         /// The name of the user whose repos to list
+        ///
+        /// Omit to view your own repos.
         user: Option<String>,
         /// List starred repos instead of owned repos
         #[clap(long)]
@@ -62,14 +83,21 @@ pub enum UserSubcommand {
         #[clap(long)]
         sort: Option<RepoSortOrder>,
     },
+    /// List the organizations a user is a member of
     Orgs {
         /// The name of the user to view org membership of
+        ///
+        /// Omit to view your own orgs.
         user: Option<String>,
     },
+    /// List a user's recent activity
     Activity {
         /// The name of the user to view the activity of
+        ///
+        /// Omit to view your own activity.
         user: Option<String>,
     },
+    /// Edit your user settings
     #[clap(subcommand)]
     Edit(EditCommand),
 }