Minimal docs at module level (#2639)

Author: peso

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(

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/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;

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,

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;