DocumentationWriter

doc_writer

Trait DocumentationWriter 

Source 
pub trait DocumentationWriter {
    type Error: Error;


Show 18 methods    // Required methods
    fn set_title(&mut self, title: Cow<'static, str>);
    fn set_subtitle(&mut self, subtitle: Cow<'static, str>);
    fn set_license(&mut self, license: Cow<'static, str>);
    fn usage(&mut self, usage: &str) -> Result<(), Self::Error>;
    fn start_description(&mut self) -> Result<(), Self::Error>;
    fn start_section(&mut self, name: &str) -> Result<(), Self::Error>;
    fn plain(&mut self, s: &str) -> Result<(), Self::Error>;
    fn paragraph_break(&mut self) -> Result<(), Self::Error>;
    fn emphasis(&mut self, text: &str) -> Result<(), Self::Error>;
    fn strong(&mut self, text: &str) -> Result<(), Self::Error>;
    fn link(&mut self, text: &str, to: &str) -> Result<(), Self::Error>;
    fn start_options(&mut self) -> Result<(), Self::Error>;
    fn option(&mut self, name: &str, default: &str) -> Result<(), Self::Error>;
    fn start_environment(&mut self) -> Result<(), Self::Error>;
    fn variable(&mut self, name: &str, default: &str) -> Result<(), Self::Error>;
    fn start_enum(&mut self, name: &str) -> Result<(), Self::Error>;
    fn variant(&mut self, name: &str) -> Result<(), Self::Error>;
    fn finish(self) -> Result<(), Self::Error>;

}
Expand description

A way to format documentation.

The order in which this trait’s methods can be called is outlined below. Any other order is undefined behaviour.

(set_title | set_subtitle | set_license)*
usage?
(start_description text*)?
custom_section*
(start_options text* (option text*)*)?
custom_section*
(start_environment text* (variable text*)*)?
(custom_section | (start_enum text* (variant text*)*))*
finish

with

custom_section := start_section text*
text := plain | paragraph_break | emphasis | bold | link
  • a*: a is repeated 0 or more times
  • a?: a is optional
  • a | b: either a or b is called
  • a := b: a is a shorthand for b
  • a: If a was not defined using the syntax above then DocumentationWriter::a is called

MarkdownParseExt::write_markdown can be used instead of text at any point to convert markdown comments into the documentation format if the parse-markdown feature is enabled.

§Examples

let mut man_string = Vec::new();
let mut md_string = Vec::new();

generate(ManWriter::new(&mut man_string).with_section("1")).unwrap();
generate(MarkdownWriter::new(&mut md_string)).unwrap();

fn generate<W: DocumentationWriter>(mut w: W) -> Result<(), W::Error> {
    w.set_title("grep".into());
    w.set_subtitle("print lines that match patterns".into());
    w.set_license(
        r#"Copyright 1998-2000, 2002, 2005-2020 Free Software Foundation, Inc.

This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE."#
            .into(),
    );

    w.usage("grep [OPTION...] PATTERNS [FILE...]")?;

    w.start_description()?;
    w.plain("grep searches for PATTERNS in each FILE.\nPATTERNS is one or more patterns separated by newline characters.")?;
    w.paragraph_break()?;
    w.plain("A FILE of “-” stands for standard input.")?;

    w.start_options()?;
    w.option("--help", "")?;
    w.plain("Output a usage message and exit.")?;

    w.option("--color", "auto")?;
    w.plain("Display color on the terminal")?;

    w.start_section("Regular Expressions")?;
    w.plain("A regular expression is a pattern that describes a set of strings.")?;
    w.paragraph_break()?;
    w.plain("Perl-compatible regular expressions give additional functionality, and are documented in ")?;
    w.link("", "man:pcresyntax(3)")?;

    w.start_environment()?;
    w.variable("GREP_COLOR", "auto")?;
    w.plain("Display color on the terminal")?;

    w.finish()
}

assert_eq!(&String::from_utf8(md_string).unwrap(), include_str!("../examples/grep.md").trim());
assert_eq!(&String::from_utf8(man_string).unwrap(), include_str!("../examples/grep.1").trim());

§grep.md

§grep – print lines that match patterns

usage: grep [OPTION...] PATTERNS [FILE...]

grep searches for PATTERNS in each FILE. PATTERNS is one or more patterns separated by newline characters.

A FILE of “-” stands for standard input.

§Options

  • --help: Output a usage message and exit.
  • --color=auto: Display color on the terminal

§Regular Expressions

A regular expression is a pattern that describes a set of strings.

Perl-compatible regular expressions give additional functionality, and are documented in pcresyntax(3)

§Environment

  • GREP_COLOR=auto: Display color on the terminal

§License

Copyright 1998-2000, 2002, 2005-2020 Free Software Foundation, Inc.

This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

§man grep.1

GREP(1)                           General Commands Manual                          GREP(1)

NAME
       grep — print lines that match patterns

SYNOPSIS
       grep [OPTION...] PATTERNS [FILE...]

DESCRIPTION
       grep  searches  for  PATTERNS in each FILE.  PATTERNS is one or more patterns sepa‐
       rated by newline characters.

       A FILE of “-” stands for standard input.

OPTIONS
       --help    Output a usage message and exit.

       --color=auto
                 Display color on the terminal

REGULAR EXPRESSIONS
       A regular expression is a pattern that describes a set of strings.

       Perl-compatible regular expressions give additional functionality,  and  are  docu‐
       mented in pcresyntax(3)

ENVIRONMENT
       GREP_COLOR=auto
                 Display color on the terminal

SEE ALSO
       pcresyntax(3)

COPYRIGHT
       Copyright 1998-2000, 2002, 2005-2020 Free Software Foundation, Inc.

       This is free software; see the source for copying conditions.
       There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
       POSE.

                                                                                   GREP(1)

Required Associated Types§

Source

type Error: Error

The error type returned by this writer.

Required Methods§

Source

fn set_title(&mut self, title: Cow<'static, str>)

Set the title of this document.

§Examples
w.set_title("grep".into());
Source

fn set_subtitle(&mut self, subtitle: Cow<'static, str>)

Set the subtitle of this document.

§Examples
w.set_title("grep".into());
w.set_subtitle("print lines that match patterns".into());
Source

fn set_license(&mut self, license: Cow<'static, str>)

Set the license of this man page and/or the code it covers.

§Examples
w.set_license(r"Copyright 1998-2000, 2002, 2005-2020 Free Software Foundation, Inc.

This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.".into())
Source

fn usage(&mut self, usage: &str) -> Result<(), Self::Error>

Emit usage information.

§Examples
w.usage("grep [OPTION...] PATTERNS [FILE...]")?;
Source

fn start_description(&mut self) -> Result<(), Self::Error>

Start the description section.

§Examples
w.start_description()?;
w.plain("grep searches for PATTERNS in each FILE.\nPATTERNS is one or more patterns separated by newline characters.")?;
w.paragraph_break()?;
w.plain("A FILE of “-” stands for standard input.")?;
Source

fn start_section(&mut self, name: &str) -> Result<(), Self::Error>

Start a custom section.

§Examples
w.start_section("Regular Expressions")?;
w.plain("A regular expression is a pattern that describes a set of strings.")?;
Source

fn plain(&mut self, s: &str) -> Result<(), Self::Error>

Emit unformatted text.

§Examples
w.start_description()?;
w.plain("grep searches for PATTERNS in each FILE.")?;
w.plain("PATTERNS is one or more patterns separated by newline characters.")?;
Source

fn paragraph_break(&mut self) -> Result<(), Self::Error>

Emit a paragraph break.

§Examples
w.start_description()?;
w.plain("grep searches for PATTERNS in each FILE.\nPATTERNS is one or more patterns separated by newline characters.")?;
w.paragraph_break()?;
w.plain("A FILE of “-” stands for standard input.")?;
Source

fn emphasis(&mut self, text: &str) -> Result<(), Self::Error>

Emit emphasized (italicized) text.

§Examples
w.start_description()?;
w.emphasis("grep")?;
w.plain("searches for PATTERNS in each FILE.\nPATTERNS is one or more patterns separated by newline characters.")?;
Source

fn strong(&mut self, text: &str) -> Result<(), Self::Error>

Emit strong (bold) text.

§Examples
w.start_description()?;
w.strong("NOTE:")?;
w.plain("quite important information")?;

Emit a hyperlink.

If text == "", to is used as the displayed text.

§Examples
w.start_description()?;
w.plain("Perl-compatible regular expressions give additional functionality, and are documented in ")?;
w.link("", "man:pcresyntax(3)")?;
w.plain("and can be tested using online services like")?;
w.link("regex101", "https://regex101.com")?;
w.plain(".")?;
Source

fn start_options(&mut self) -> Result<(), Self::Error>

Start the options section.

§Examples
w.start_options()?;
w.plain("These options are available:")?;

w.option("--help", "")?;
w.plain("Output a usage message and exit.")?;

w.option("--color", "auto")?;
w.plain("Display color on the terminal")?;
Source

fn option(&mut self, name: &str, default: &str) -> Result<(), Self::Error>

Emit an option.

§Examples
w.start_options()?;
w.plain("These options are available:")?;

w.option("--help", "")?;
w.plain("Output a usage message and exit.")?;

w.option("--color", "auto")?;
w.plain("Display color on the terminal")?;
Source

fn start_environment(&mut self) -> Result<(), Self::Error>

Start the environment section.

§Examples
w.start_environment()?;
w.variable("GREP_COLOR", "auto")?;
w.plain("Display color on the terminal")?;
Source

fn variable(&mut self, name: &str, default: &str) -> Result<(), Self::Error>

Emit an environment variable.

§Examples
w.start_environment()?;
w.variable("GREP_COLOR", "auto")?;
w.plain("Display color on the terminal")?;
Source

fn start_enum(&mut self, name: &str) -> Result<(), Self::Error>

Start a custom enum section.

§Examples
w.start_enum("COLOR")?;
w.variant("never")?;
w.plain("Never output any colors to stdout.")?;
w.variant("always")?;
w.plain("Always output colors to stdout.")?;
w.variant("auto")?;
w.plain("Only output colors to stdout if a tty is attached.")?;
Source

fn variant(&mut self, name: &str) -> Result<(), Self::Error>

Emit a enum variant.

§Examples
w.start_enum("COLOR")?;
w.variant("never")?;
w.plain("Never output any colors to stdout.")?;
w.variant("always")?;
w.plain("Always output colors to stdout.")?;
w.variant("auto")?;
w.plain("Only output colors to stdout if a tty is attached.")?;
Source

fn finish(self) -> Result<(), Self::Error>

Finish the document by writing a footer.

This function must always be called.

Implementors§