Add doc comment for main.rs

This patch adds a doc comment to the main.rs file that describes the
structure of rusty-man.

src/main.rs

@@ -1,6 +1,38 @@
 // SPDX-FileCopyrightText: 2020 Robin Krahl <robin.krahl@ireas.org>
 // SPDX-License-Identifier: MIT
 
+//! rusty-man is a command-line viewer for documentation generated by `rustdoc`.
+//!
+//! rusty-man opens the documentation for a given keyword.  It performs these steps to find the
+//! documentation for an item:
+//! 1. The sources, currently only local directories, are loaded, see the `load_sources` funnction
+//!    and the `source` module.
+//! 2. We split the keyword `{crate}::{item}` into the crate and the item and try to find the crate
+//!    in one of the sources – see the `find_crate` function.
+//! 3. If we found a crate, we look up the item in the `all.html` file of the crate and load the
+//!    documentation linked there.  If we can’t find the item in the index, we check whether it is
+//!    a module by trying to open the `{item}/index.html` file.  If this fails too, we check
+//!    whether the item `{parent}::{member}` is a member of another type.  See the `find_doc`
+//!    function and the `doc` module.
+//! 4. If we didn’t find a match in the previous step, we load the search index from the
+//!    `search-index.js` file for all sources and try to find a matching item.  If we find one, we
+//!    open the documentation for that item as in step 3.  See the `search_doc` function and the
+//!    `index` module.
+//!
+//! If we found a documentation item, we use a viewer to open it – see the `viewer` module.
+//! Currently, there are two viewer implementations:  `viewer::text::TextViewer` converts the
+//! documentaion to plain text, `viewer::text::RichViewer` adds some formatting to it.  Both
+//! viewers pipe their output through a pager, if available.
+//!
+//! The documentation is scraped from the HTML files generated by `rustdoc`.  See the `parser`
+//! module for the scraping and the `doc::Doc` struct for the structure of the documentation items.
+//! For details on the structure of the HTML files and the search index, you have to look at the
+//! `html::render` module in the `librustdoc` source code.
+//!
+//! Note that the format of the search index changed in Rust 1.40.  We don’t support the old index
+//! format.  As the format of the HTML files is not specified, rusty-man might not work with new
+//! Rust versions that change the documentation format.
+
 mod doc;
 mod index;
 mod parser;
@@ -12,7 +44,7 @@ use std::path;
 
 use structopt::StructOpt;
 
-/// Command-line interface for rustdoc documentation
+/// Command-line viewer for rustdoc documentation
 #[derive(Debug, StructOpt)]
 struct Opt {
     /// The keyword to open the documentation for, e. g. `rand_core::RngCore`
@@ -71,6 +103,7 @@ const DEFAULT_SOURCES: &[&str] = &[
     "./target/doc",
 ];
 
+/// Load all sources given as a command-line argument and, if enabled, the default sources.
 fn load_sources(
     sources: &[String],
     load_default_sources: bool,
@@ -96,6 +129,7 @@ fn load_sources(
     Ok(vec)
 }
 
+/// Find the documentation for an item with the given name (exact matches only).
 fn find_doc(
     sources: &[Box<dyn source::Source>],
     keyword: &str,
@@ -113,10 +147,13 @@ fn find_doc(
     }
 }
 
+/// Find the crate with the given name.
 fn find_crate(sources: &[Box<dyn source::Source>], name: &str) -> Option<doc::Crate> {
     sources.iter().filter_map(|s| s.find_crate(name)).next()
 }
 
+/// Use the search index to find the documentation for an item that partially matches the given
+/// keyword.
 fn search_doc(
     sources: &[Box<dyn source::Source>],
     keyword: &str,
@@ -133,6 +170,7 @@ fn search_doc(
     }
 }
 
+/// Use the search index to find an item that partially matches the given keyword.
 fn search_item(
     sources: &[Box<dyn source::Source>],
     keyword: &str,
@@ -161,6 +199,7 @@ fn search_item(
     }
 }
 
+/// Let the user select an item from the given list of matches.
 fn select_item(
     items: &[index::IndexItem],
     keyword: &str,