From 227a2207fbc19df42049eb7f90b6bdac24658934 Mon Sep 17 00:00:00 2001 From: Cyborus Date: Tue, 30 Jul 2024 18:10:11 -0400 Subject: [PATCH 1/3] docs: better clap ids --- src/issues.rs | 9 +++++++-- src/prs.rs | 10 +++++++++- src/release.rs | 2 +- src/repo.rs | 7 +++++++ 4 files changed, 24 insertions(+), 4 deletions(-) diff --git a/src/issues.rs b/src/issues.rs index 130a1ef..f2a97ee 100644 --- a/src/issues.rs +++ b/src/issues.rs @@ -23,25 +23,28 @@ pub enum IssueSubcommand { title: String, #[clap(long)] body: Option, - #[clap(long, short)] + #[clap(long, short, id = "[HOST/]OWNER/REPO")] repo: Option, }, Edit { + #[clap(id = "[REPO#]ID")] issue: IssueId, #[clap(subcommand)] command: EditCommand, }, Comment { + #[clap(id = "[REPO#]ID")] issue: IssueId, body: Option, }, Close { + #[clap(id = "[REPO#]ID")] issue: IssueId, #[clap(long, short)] with_msg: Option>, }, Search { - #[clap(long, short)] + #[clap(long, short, id = "[HOST/]OWNER/REPO")] repo: Option, query: Option, #[clap(long, short)] @@ -54,11 +57,13 @@ pub enum IssueSubcommand { state: Option, }, View { + #[clap(id = "[REPO#]ID")] id: IssueId, #[clap(subcommand)] command: Option, }, Browse { + #[clap(id = "[REPO#]ID")] id: IssueId, }, } diff --git a/src/prs.rs b/src/prs.rs index 9d38d5c..c8f7389 100644 --- a/src/prs.rs +++ b/src/prs.rs @@ -60,12 +60,13 @@ pub enum PrSubcommand { #[clap(long)] body: Option, /// The repo to create this issue on - #[clap(long, short)] + #[clap(long, short, id = "[HOST/]OWNER/REPO")] repo: Option, }, /// View the contents of a pull request View { /// The pull request to view. + #[clap(id = "[REPO#]ID")] id: Option, #[clap(subcommand)] command: Option, @@ -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, }, /// 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, /// 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, #[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, /// 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, /// 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, }, } diff --git a/src/release.rs b/src/release.rs index 716c508..887be27 100644 --- a/src/release.rs +++ b/src/release.rs @@ -16,7 +16,7 @@ use crate::{ pub struct ReleaseCommand { #[clap(long, short = 'R')] remote: Option, - #[clap(long, short)] + #[clap(long, short, id = "[HOST/]OWNER/REPO")] repo: Option, #[clap(subcommand)] command: ReleaseSubcommand, diff --git a/src/repo.rs b/src/repo.rs index f870add..e294da0 100644 --- a/src/repo.rs +++ b/src/repo.rs @@ -305,6 +305,7 @@ pub enum RepoCommand { push: bool, }, Fork { + #[clap(id = "[HOST/]OWNER/REPO")] repo: RepoArg, #[clap(long)] name: Option, @@ -312,24 +313,30 @@ pub enum RepoCommand { remote: Option, }, View { + #[clap(id = "[HOST/]OWNER/REPO")] name: Option, #[clap(long, short = 'R')] remote: Option, }, Clone { + #[clap(id = "[HOST/]OWNER/REPO")] repo: RepoArg, path: Option, }, Star { + #[clap(id = "[HOST/]OWNER/REPO")] repo: RepoArg, }, Unstar { + #[clap(id = "[HOST/]OWNER/REPO")] repo: RepoArg, }, Delete { + #[clap(id = "[HOST/]OWNER/REPO")] repo: RepoArg, }, Browse { + #[clap(id = "[HOST/]OWNER/REPO")] name: Option, #[clap(long, short = 'R')] remote: Option, From 72800f9bba265912befb2899d91e06d01b898a18 Mon Sep 17 00:00:00 2001 From: Cyborus Date: Sun, 4 Aug 2024 11:12:02 -0400 Subject: [PATCH 2/3] 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), } From ca6d0d821d1c851bb253778b437cca2ed61509e9 Mon Sep 17 00:00:00 2001 From: Cyborus Date: Sun, 4 Aug 2024 11:12:49 -0400 Subject: [PATCH 3/3] docs: document `--remote` --- src/issues.rs | 1 + src/prs.rs | 2 +- src/release.rs | 2 ++ src/user.rs | 1 + 4 files changed, 5 insertions(+), 1 deletion(-) diff --git a/src/issues.rs b/src/issues.rs index 5889e59..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, #[clap(subcommand)] diff --git a/src/prs.rs b/src/prs.rs index c8f7389..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, #[clap(subcommand)] diff --git a/src/release.rs b/src/release.rs index f0069ee..fa9d7d7 100644 --- a/src/release.rs +++ b/src/release.rs @@ -14,8 +14,10 @@ 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, + /// The name of the repository to operate on. #[clap(long, short, id = "[HOST/]OWNER/REPO")] repo: Option, #[clap(subcommand)] diff --git a/src/user.rs b/src/user.rs index 8f8b4e9..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, #[clap(subcommand)]