From c98eb75a2ed242c57b4ddfb8a0a4c4958a8fdcee Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Wed, 30 Apr 2025 19:06:15 +0200 Subject: [PATCH 1/7] Module dokumentation for main --- src/main.rs | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/src/main.rs b/src/main.rs index 2e8e9b8575..151cd86f8a 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,36 @@ +//! +//! The gitui program is a text-based UI for working with a Git repository. +//! The main navigation occurs between a number of tabs. +//! When you execute commands, the program may use popups to communicate +//! with the user. It is possible to customize the keybindings. +//! +//! +//! ## Internal Modules +//! The top-level modules of gitui can be grouped as follows: +//! +//! - User Interface +//! - [tabs] for main navigation +//! - [components] for visual elements used on tabs +//! - [popups] for temporary dialogs +//! - [ui] for tooling like scrollbars +//! - Git Interface +//! - [asyncgit] (crate) for async operations on repository +//! - Distribution and Documentation +//! - Project files: README.md, LICENSE.md, CHANGELOG.md, CONTRIBUTING.md, etc +//! - Github CI: See .github/ +//! - Installation: wix/ holds an installer for Windows +//! - Usage: `KEY_CONIG.md`, THEMES.md, FAQ.md +//! +//! ## Included Crates +//! Some crates are part of the gitui repository: +//! - [asyncgit] for Git operations in the background. +//! - git2-hooks (used by asyncgit). +//! - git2-testing (used by git2-hooks). +//! - invalidstring used by asyncgit for testing with invalid strings. +//! - [filetreelist] for a tree view of files. +//! - [scopetime] for measuring execution time. +//! + #![forbid(unsafe_code)] #![deny( unused_imports, From c602674f08cb33eaa2fa049b3ef3585a9f1eb0f1 Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Mon, 5 May 2025 09:42:26 +0200 Subject: [PATCH 2/7] Module documentation for tabs --- src/tabs/mod.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/tabs/mod.rs b/src/tabs/mod.rs index 6d8100f63c..ba479ad511 100644 --- a/src/tabs/mod.rs +++ b/src/tabs/mod.rs @@ -1,3 +1,17 @@ +/*! +The tabs module contains a struct for each of the tabs visible in the +ui: + +- [`Status`]: Stage changes, push, pull +- [`Revlog`]: Revision log (think git log) +- [`FilesTab`]: See content of any file at HEAD. Blame +- [`Stashing`]: Managing one stash +- [`StashList`]: Managing all stashes + +Many of the tabs can expand to show more details. This is done via +Enter or right-arrow. To close again, press ESC. +*/ + mod files; mod revlog; mod stashing; From bf8a7a9c60897a26fa449240c30f44d26b1ab669 Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Tue, 6 May 2025 06:47:39 +0200 Subject: [PATCH 3/7] Module documentation for cmdbar --- src/cmdbar.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/cmdbar.rs b/src/cmdbar.rs index 790d0f09e1..74128f9b43 100644 --- a/src/cmdbar.rs +++ b/src/cmdbar.rs @@ -1,3 +1,13 @@ +/*! +The cmdbar module manages the [`CommandBar`] sitting at the bottom of the +screen. + +It shows a list of available keyboard commands. The full list can cover +several lines, so `CommandBar` has a "more/less" feature to toggle between +showing just one line or expanding. +Commands can be shown as disabled, if they are not enabled in the +current context. +*/ use crate::{ components::CommandInfo, keys::SharedKeyConfig, strings, ui::style::SharedTheme, From 016da5cb9a587032130a6047da228bdde5917087 Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Tue, 6 May 2025 06:59:09 +0200 Subject: [PATCH 4/7] Module documentation for components --- src/components/mod.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/components/mod.rs b/src/components/mod.rs index f20d3f981a..9c531a1e6e 100644 --- a/src/components/mod.rs +++ b/src/components/mod.rs @@ -1,3 +1,7 @@ +/*! +Components are the visible building blocks of tabs. +*/ + mod changes; mod command; mod commit_details; From 3b3e976f41981a9a65f7daf8446872618e09b92f Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Tue, 1 Apr 2025 12:12:41 +0200 Subject: [PATCH 5/7] Module documentation for components::commitlist --- src/components/commitlist.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/components/commitlist.rs b/src/components/commitlist.rs index dde38ba06e..61653a0c89 100644 --- a/src/components/commitlist.rs +++ b/src/components/commitlist.rs @@ -1,3 +1,8 @@ +/*! +The [`CommitList`] shows a list of commits. It is used by +the [revlog](crate::tabs::Revlog) tab +and the [stashlist](crate::tabs::StashList) tab. +*/ use super::utils::logitems::{ItemBatch, LogEntry}; use crate::{ app::Environment, From 9df472df690db99340597a5875076b9aa2bd7259 Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Fri, 9 May 2025 07:38:03 +0200 Subject: [PATCH 6/7] Crate documentation for asyncgit --- asyncgit/src/lib.rs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/asyncgit/src/lib.rs b/asyncgit/src/lib.rs index fa022e4020..1f8095e9fc 100644 --- a/asyncgit/src/lib.rs +++ b/asyncgit/src/lib.rs @@ -1,4 +1,10 @@ -//! asyncgit +/*! +`AsyncGit` is a library that provides non-blocking access to Git +operations, enabling `GitUI` to perform potentially slow Git operations +in the background while keeping the user interface responsive. + +It wraps libraries like git2 and gix. +*/ #![forbid(missing_docs)] #![deny( From cbdba947809a755442d56137883859ae0ca20526 Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Mon, 12 May 2025 20:55:02 +0200 Subject: [PATCH 7/7] Fix doc warnings in asyncgit --- asyncgit/src/sync/remotes/mod.rs | 6 +++--- asyncgit/src/sync/sign.rs | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/asyncgit/src/sync/remotes/mod.rs b/asyncgit/src/sync/remotes/mod.rs index 749940a192..8c3aaf32eb 100644 --- a/asyncgit/src/sync/remotes/mod.rs +++ b/asyncgit/src/sync/remotes/mod.rs @@ -132,7 +132,7 @@ fn get_current_branch( /// Tries to find the default repo to fetch from based on configuration. /// -/// > branch..remote +/// > `branch..remote` /// > /// > When on branch ``, it tells `git fetch` and `git push` which remote to fetch from or /// > push to. [...] If no remote is configured, or if you are not on any branch and there is more @@ -173,12 +173,12 @@ pub(crate) fn get_default_remote_for_fetch_in_repo( /// Tries to find the default repo to push to based on configuration. /// -/// > remote.pushDefault +/// > `remote.pushDefault` /// > /// > The remote to push to by default. Overrides `branch..remote` for all branches, and is /// > overridden by `branch..pushRemote` for specific branches. /// -/// > branch..remote +/// > `branch..remote` /// > /// > When on branch ``, it tells `git fetch` and `git push` which remote to fetch from or /// > push to. The remote to push to may be overridden with `remote.pushDefault` (for all diff --git a/asyncgit/src/sync/sign.rs b/asyncgit/src/sync/sign.rs index af6508466c..da5079f72c 100644 --- a/asyncgit/src/sync/sign.rs +++ b/asyncgit/src/sync/sign.rs @@ -281,7 +281,7 @@ pub struct SSHSign { } impl SSHSign { - /// Create new [`SSHDiskKeySign`] for sign. + /// Create new `SSHDiskKeySign` for sign. pub fn new(mut key: PathBuf) -> Result { key.set_extension(""); if key.is_file() {