docs: document commands

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 {
+    /// Deletes login info for an instance
-        host: String,
+    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,
 }
 

src/issues.rs

@@ -19,6 +19,7 @@ pub struct IssueCommand {
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum IssueSubcommand {
+    /// Create a new issue on a repo
     Create {
         title: String,
         #[clap(long)]
@@ -26,23 +27,28 @@ pub enum IssueSubcommand {
         #[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, id = "[HOST/]OWNER/REPO")]
         repo: Option<RepoArg>,
@@ -56,12 +62,14 @@ 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,
@@ -135,12 +143,11 @@ impl From<State> for forgejo_api::structs::IssueListIssuesQueryState {
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum EditCommand {
-    Title {
+    /// Edit an issue's title
-        new_title: Option<String>,
+    Title { new_title: Option<String> },
-    },
+    /// Edit an issue's text content
-    Body {
+    Body { new_body: Option<String> },
-        new_body: Option<String>,
+    /// Edit a comment on an issue
-    },
     Comment {
         idx: usize,
         new_body: Option<String>,
@@ -149,8 +156,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,
 }
 

src/release.rs

@@ -24,6 +24,7 @@ pub struct ReleaseCommand {
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum ReleaseSubcommand {
+    /// Create a new release
     Create {
         name: String,
         #[clap(long, short = 'T')]
@@ -56,6 +57,7 @@ pub enum ReleaseSubcommand {
         #[clap(long, short)]
         prerelease: bool,
     },
+    /// Edit a release's info
     Edit {
         name: String,
         #[clap(long, short = 'n')]
@@ -73,40 +75,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 {
+    /// Open a release in your browser
-        name: Option<String>,
+    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 {
+    /// Remove an attachment from a release
-        release: String,
+    Delete { release: String, asset: String },
-        asset: String,
+    /// Download an attached file
-    },
+    ///
+    /// Use `source.zip` or `source.tar.gz` to download the repo archive
     Download {
         release: String,
         asset: String,

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,6 +305,7 @@ pub enum RepoCommand {
         #[clap(long, short)]
         push: bool,
     },
+    /// Fork a repository onto your account
     Fork {
         #[clap(id = "[HOST/]OWNER/REPO")]
         repo: RepoArg,
@@ -312,29 +314,37 @@ pub enum RepoCommand {
         #[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>,

src/user.rs

@@ -14,46 +14,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 +82,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),
 }