morty 0.9.0

A SystemVerilog source file pickler.
Documentation 
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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

//! Raw documentation analysis
//!
//! This module implements the first level of syntax tree analysis to associate
//! doc comments with items in the SV source files.

use sv_parser::{NodeEvent, RefNode, SyntaxTree};

/// Raw documentation information.
pub struct RawDoc<'a> {
    /// The syntax tree for which the documentation was generated.
    pub ast: &'a SyntaxTree,
    /// The root documentation scope.
    pub root: Scope<'a>,
}

impl<'a> RawDoc<'a> {
    /// Generate raw documentation from an AST.
    pub fn new(ast: &'a SyntaxTree) -> Self {
        let mut comments = vec![];
        let mut stack = vec![];
        #[derive(PartialEq)]
        enum LastComment {
            None,
            Local,
            Parent,
        }
        let mut last_comment = LastComment::None;
        stack.push(Scope::default());

        // Visit the AST, gobble up comments, and process all nodes that make
        // their way into the documentation.
        for event in ast.into_iter().event() {
            match event {
                NodeEvent::Enter(node) => match node {
                    RefNode::Comment(comment) => {
                        let s = ast.get_str(&comment.nodes.0).unwrap();
                        if let Some(stripped) = s.strip_prefix("//!") {
                            let comments = &mut stack.last_mut().unwrap().comments;
                            if !comments.is_empty() && last_comment != LastComment::Parent {
                                comments.push("");
                            }
                            last_comment = LastComment::Parent;
                            comments.push(stripped);
                        } else if s.starts_with("///") && !s.starts_with("////") {
                            if !comments.is_empty() && last_comment != LastComment::Local {
                                comments.push("");
                            }
                            last_comment = LastComment::Local;
                            comments.push(&s[3..]);
                        }
                    }
                    RefNode::TypeDeclaration(..)
                    | RefNode::NetDeclaration(..)
                    | RefNode::ParameterDeclaration(..)
                    | RefNode::LocalParameterDeclaration(..)
                    | RefNode::AnsiPortDeclaration(..)
                    | RefNode::ModuleDeclaration(..)
                    | RefNode::PackageDeclaration(..) => {
                        last_comment = LastComment::None;
                        stack.push(Scope::new(node.clone(), std::mem::take(&mut comments)));
                    }
                    RefNode::SourceText(..)
                    | RefNode::WhiteSpace(..)
                    | RefNode::Locate(..)
                    | RefNode::Description(..)
                    | RefNode::DescriptionPackageItem(..)
                    | RefNode::PackageItem(..)
                    | RefNode::PackageOrGenerateItemDeclaration(..)
                    | RefNode::DataDeclaration(..)
                    | RefNode::NonPortModuleItem(..)
                    | RefNode::ModuleOrGenerateItem(..)
                    | RefNode::ModuleOrGenerateItemDeclaration(..)
                    | RefNode::ModuleItem(..)
                    | RefNode::ParameterPortDeclaration(..)
                    | RefNode::ModuleCommonItem(..)
                    | RefNode::ModuleOrGenerateItemModuleItem(..) => (),
                    _ => {
                        last_comment = LastComment::None;
                        if !comments.is_empty() {
                            debug!("Discarding comments: {:#?}", comments);
                            trace!("Discarded due to {:?}", node);
                            comments.clear();
                        }
                    }
                },
                NodeEvent::Leave(node) => {
                    // If we are leaving the current node on the stack, pop that
                    // node off the stack and add it as a child to its parent.
                    if stack.last().and_then(|s| s.node.clone()) == Some(node) {
                        let n = stack.pop().unwrap();
                        stack.last_mut().unwrap().children.push(n);
                    }
                }
            }
        }
        assert_eq!(stack.len(), 1);
        let root = stack.into_iter().next().unwrap();

        Self { ast, root }
    }
}

/// A documentation nesting level.
#[derive(Default, Debug)]
pub struct Scope<'a> {
    /// The node in the syntax tree.
    pub node: Option<RefNode<'a>>,
    /// Comments associated with this node.
    pub comments: Vec<&'a str>,
    /// Subscopes with additional documentation nodes.
    pub children: Vec<Scope<'a>>,
}

impl<'a> Scope<'a> {
    /// Create a new documentation scope.
    fn new(node: RefNode<'a>, comments: Vec<&'a str>) -> Self {
        Self {
            node: Some(node),
            comments,
            ..Default::default()
        }
    }
}