From 72800f9bba265912befb2899d91e06d01b898a18 Mon Sep 17 00:00:00 2001 From: Cyborus Date: Sun, 4 Aug 2024 11:12:02 -0400 Subject: docs: document commands --- src/auth.rs | 12 +++++++++--- src/issues.rs | 22 ++++++++++++++++------ src/release.rs | 21 ++++++++++++++------- src/repo.rs | 10 ++++++++++ src/user.rs | 27 +++++++++++++++++++++++++++ 5 files changed, 76 insertions(+), 16 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, }, + /// List all instances you're currently logged into List, } diff --git a/src/issues.rs b/src/issues.rs index f2a97ee..5889e59 100644 --- a/src/issues.rs +++ b/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, }, + /// 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, }, + /// 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>, }, + /// Search for an issue in a repo Search { #[clap(long, short, id = "[HOST/]OWNER/REPO")] repo: Option, @@ -56,12 +62,14 @@ pub enum IssueSubcommand { #[clap(long, short)] state: Option, }, + /// View an issue's info View { #[clap(id = "[REPO#]ID")] id: IssueId, #[clap(subcommand)] command: Option, }, + /// Open an issue in your browser Browse { #[clap(id = "[REPO#]ID")] id: IssueId, @@ -135,12 +143,11 @@ impl From for forgejo_api::structs::IssueListIssuesQueryState { #[derive(Subcommand, Clone, Debug)] pub enum EditCommand { - Title { - new_title: Option, - }, - Body { - new_body: Option, - }, + /// Edit an issue's title + Title { new_title: Option }, + /// Edit an issue's text content + Body { new_body: Option }, + /// Edit a comment on an issue Comment { idx: usize, new_body: Option, @@ -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, } diff --git a/src/release.rs b/src/release.rs index 887be27..f0069ee 100644 --- a/src/release.rs +++ b/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, }, + /// 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, - }, + /// Open a release in your browser + Browse { name: Option }, + /// 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, }, - 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 e294da0..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,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, }, + /// View a repo's info View { #[clap(id = "[HOST/]OWNER/REPO")] name: Option, #[clap(long, short = 'R')] remote: Option, }, + /// Clone a repo's code locally Clone { #[clap(id = "[HOST/]OWNER/REPO")] repo: RepoArg, path: Option, }, + /// 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, diff --git a/src/user.rs b/src/user.rs index 2b12867..8f8b4e9 100644 --- a/src/user.rs +++ b/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, }, + /// View a user's profile page View { /// The name of the user to view + /// + /// Omit to view your own page user: Option, }, + /// 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, }, + /// 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, }, + /// List a user's followers Followers { /// The name of the user whose followers to list + /// + /// Omit to view your own followers user: Option, }, + /// 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, /// List starred repos instead of owned repos #[clap(long)] @@ -62,14 +82,21 @@ pub enum UserSubcommand { #[clap(long)] sort: Option, }, + /// 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, }, + /// 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, }, + /// Edit your user settings #[clap(subcommand)] Edit(EditCommand), } -- cgit v1.2.3