1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

/// A Rust identifier
pub type Identifier = String;

/// A Rust pattern, as used in pattern matching.
pub type Pattern = String;

/// Documentation, a Markdown `String`
pub type Documentation = String;

/// The headline of a section
pub type SectionHeadline = String;

/// Information extracted from a doc comment
#[derive(Debug, PartialEq, Eq, Clone, Hash)]
pub struct DocBlock {
    /// First line
    pub teaser: String,
    /// Paragraphs after first line
    pub description: Option<Documentation>,
    /// Sections
    pub sections: Vec<DocSection>,
}

/// Documentation sections
#[derive(Debug, PartialEq, Eq, Clone, Hash)]
pub enum DocSection {
    /// Function parameters, mapping param name to docs
    Parameters(Vec<(Identifier, Documentation)>),
    /// Type parameters (generics), mapping ident of generic to docs
    TypeParameters(Vec<(Identifier, Documentation)>),
    /// Lifetime parameters, documenting the life and death of your times
    LifetimeParameters(Vec<(Identifier, Documentation)>),
    /// Return value documentation with optional list of enum variants.
    Returns(Documentation, Vec<(Pattern, Documentation)>),
    /// Custom/unknown sections, mapping headlines to docs
    ///
    /// In the future, some of the sections currently treated as 'custom' may
    /// be added as new variants, e.g. 'Examples', or 'Panics'.
    Custom(SectionHeadline, Documentation),
}