From 6d0a2ec11511474eaa341591f1c291f2b336f407 Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Tue, 24 Jun 2025 09:23:02 +0200 Subject: [PATCH] Minimal docs at module level (#2639) --- asyncgit/src/lib.rs | 10 ++++++++- asyncgit/src/sync/remotes/mod.rs | 6 +++--- asyncgit/src/sync/sign.rs | 2 +- src/components/mod.rs | 37 ++++++++++++++++++++++++++++++++ src/main.rs | 33 ++++++++++++++++++++++++++++ src/tabs/mod.rs | 14 ++++++++++++ 6 files changed, 97 insertions(+), 5 deletions(-) diff --git a/asyncgit/src/lib.rs b/asyncgit/src/lib.rs index fa022e40..e37ac216 100644 --- a/asyncgit/src/lib.rs +++ b/asyncgit/src/lib.rs @@ -1,4 +1,12 @@ -//! 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 also provides synchronous Git operations. + +It wraps libraries like git2 and gix. +*/ #![forbid(missing_docs)] #![deny( diff --git a/asyncgit/src/sync/remotes/mod.rs b/asyncgit/src/sync/remotes/mod.rs index 749940a1..8c3aaf32 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 af650846..da5079f7 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() { diff --git a/src/components/mod.rs b/src/components/mod.rs index f20d3f98..51322e18 100644 --- a/src/components/mod.rs +++ b/src/components/mod.rs @@ -1,3 +1,40 @@ +/*! +Components are the visible building blocks in gitui. + +They have a state, handle events, and render to the terminal: + +* Some are full screen. That would be all the [`tabs`](super::tabs). +* Some look like panels, eg [`CommitDetailsComponent`] +* Some overlap others. They are collected in module [`popups`](super::popups) +* Some are decorations, eg [`HorizontalScroll`](utils::scroll_horizontal::HorizontalScroll). + +Components can be reused. +For example, [`CommitList`] is used in both tab "revlog" and tab "stashlist". + + +## Composition + +In gitui, composition is driven by code. This means each component must +have code that explicitly forwards component function calls like draw, +commands and event to the components it is composed of. + +Other systems use composition by data: They provide a generic data structure +that reflects the visual hierarchy, and uses it at runtime to +determine which code should be executed. This is not how gitui works. + +## Traits + +There are two traits defined here: +* [`Component`] handles events from the user, +* [`DrawableComponent`] renders to the terminal. + +In the current codebase these are always implemented together, and it probably +makes more sense to merge them some time in the future. +It is a little strange that you implement `draw()` on a `DrawableComponent`, +but have function `hide()` from trait Component which does not know how +to `draw()`. +*/ + mod changes; mod command; mod commit_details; diff --git a/src/main.rs b/src/main.rs index 2e8e9b85..50d7a98b 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 +//! - Github CI +//! - Installation files +//! - Usage guides +//! +//! ## 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, diff --git a/src/tabs/mod.rs b/src/tabs/mod.rs index 6d8100f6..ba479ad5 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;