blob42/rusty-man
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update main and CLI doc comments

Browse Source 
This patch updates the main module doc comment and the documentation
printed with rusty-man --help.
This commit is contained in:
Robin Krahl 2020-07-24 13:36:17 +02:00
parent 41dd007390
commit afe3b02a34
No known key found for this signature in database
GPG Key ID: 8E9B0870524F69D8
1 changed files with 17 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
src/main.rs
View File

@ -21,18 +21,18 @@
//! `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: `PlainTextViewer` converts the documentaion
//! to plain text, `RichTextViewer` adds some formatting to it. Both viewers pipe their output
//! through a pager, if available.
//! Currently, there are two viewer implementations: `plain` converts the documentaion to plain
//! text, `rich` 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.
//! Note that the format of the search index changed in a recent Rust version (> 1.40 and <= 1.44).
//! 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;
@ -46,6 +46,16 @@ use std::path;
use structopt::StructOpt;
/// Command-line viewer for rustdoc documentation
///
/// rusty-man reads the HTML documentation generated by rustdoc and displays a documentation item.
/// Make sure to run `cargo doc` before using rusty-man. Per default, rusty-man looks up
/// documentation in the ./target/doc directory relative to the current working directory and in
/// the system documentation directories (/usr/share/doc/rust{,-doc}/html). Use the -s/--source
/// option if you want to read the documentation from a different directory.
///
/// rusty-man tries to find an item that exactly matches the given keyword. If it doesn’t find an
/// exact match, it reads the search indexes of all available sources and tries to find a partial
/// match.
#[derive(Debug, StructOpt)]
struct Opt {
/// The keyword to open the documentation for, e. g. `rand_core::RngCore`
@ -65,7 +75,7 @@ struct Opt {
/// Do not search the default documentation sources
///
/// If this option is not set, rusty-man appends `/usr/share/doc/rust{,-doc}/html` and
/// `target/doc` directory to the list of sources if they exist.
/// `target/doc` to the list of sources if they exist.
#[structopt(long)]
no_default_sources: bool,