Minimal docs at module level

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(

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.<name>.remote
+/// > `branch.<name>.remote`
 /// >
 /// > When on branch `<name>`, 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.<name>.remote` for all branches, and is
 /// > overridden by `branch.<name>.pushRemote` for specific branches.
 ///
-/// > branch.<name>.remote
+/// > `branch.<name>.remote`
 /// >
 /// > When on branch `<name>`, 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

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<Self, SignBuilderError> {
 		key.set_extension("");
 		if key.is_file() {

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,

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,

src/components/mod.rs

@@ -1,3 +1,7 @@
+/*!
+Components are the visible building blocks of tabs.
+*/
+
 mod changes;
 mod command;
 mod commit_details;

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,

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;