forge_doc/parser/
source.rs

1//! Owned source types extracted from the parse tree for documentation generation.
2//!
3//! These types hold only the data needed by the doc writer and preprocessors,
4//! avoiding lifetime dependencies on the parser's arena-allocated AST.
5
6/// Information about a parameter, struct field, event/error parameter, etc.
7#[derive(Clone, Debug, PartialEq, Eq)]
8pub struct ParamInfo {
9    /// The parameter name, if any.
10    pub name: Option<String>,
11    /// The type rendered as a string (e.g. `"uint256"`, `"address"`).
12    pub ty: String,
13}
14
15/// A base contract reference (e.g. `is IERC721, Ownable`).
16#[derive(Clone, Debug, PartialEq, Eq)]
17pub struct BaseInfo {
18    /// The full dotted name (e.g. `"IERC721"` or `"SomeLib.Base"`).
19    pub name: String,
20    /// The last identifier in the path, used for linking.
21    pub ident: String,
22}
23
24/// The kind of a contract-like definition.
25#[derive(Clone, Debug, PartialEq, Eq)]
26pub enum ContractKind {
27    Contract,
28    Abstract,
29    Interface,
30    Library,
31}
32
33impl ContractKind {
34    /// Returns the lowercase keyword string.
35    pub const fn as_str(&self) -> &'static str {
36        match self {
37            Self::Contract => "contract",
38            Self::Abstract => "abstract",
39            Self::Interface => "interface",
40            Self::Library => "library",
41        }
42    }
43}
44
45/// Owned contract definition data.
46#[derive(Clone, Debug, PartialEq, Eq)]
47pub struct ContractSource {
48    pub name: String,
49    pub kind: ContractKind,
50    pub bases: Vec<BaseInfo>,
51}
52
53/// Owned function definition data.
54#[derive(Clone, Debug, PartialEq, Eq)]
55pub struct FunctionSource {
56    /// The function name, or `None` for unnamed functions (fallback/receive).
57    pub name: Option<String>,
58    /// The function kind as a display string (e.g. `"function"`, `"constructor"`, `"fallback"`).
59    pub kind: String,
60    /// Function parameters.
61    pub params: Vec<ParamInfo>,
62    /// Return parameters.
63    pub returns: Vec<ParamInfo>,
64}
65
66impl FunctionSource {
67    /// Get the signature of the function, including parameter types.
68    pub fn signature(&self) -> String {
69        let name = self.name.as_deref().unwrap_or(&self.kind);
70        if self.params.is_empty() {
71            return name.to_string();
72        }
73        format!(
74            "{}({})",
75            name,
76            self.params.iter().map(|p| p.ty.as_str()).collect::<Vec<_>>().join(",")
77        )
78    }
79}
80
81/// Variable attribute relevant for doc generation.
82#[derive(Clone, Debug, PartialEq, Eq)]
83pub enum VariableAttr {
84    Constant,
85    Immutable,
86}
87
88/// Owned variable definition data.
89#[derive(Clone, Debug, PartialEq, Eq)]
90pub struct VariableSource {
91    pub name: String,
92    pub attrs: Vec<VariableAttr>,
93}
94
95/// Owned event definition data.
96#[derive(Clone, Debug, PartialEq, Eq)]
97pub struct EventSource {
98    pub name: String,
99    pub fields: Vec<ParamInfo>,
100}
101
102/// Owned error definition data.
103#[derive(Clone, Debug, PartialEq, Eq)]
104pub struct ErrorSource {
105    pub name: String,
106    pub fields: Vec<ParamInfo>,
107}
108
109/// Owned struct definition data.
110#[derive(Clone, Debug, PartialEq, Eq)]
111pub struct StructSource {
112    pub name: String,
113    pub fields: Vec<ParamInfo>,
114}
115
116/// Owned enum definition data.
117#[derive(Clone, Debug, PartialEq, Eq)]
118pub struct EnumSource {
119    pub name: String,
120    pub variants: Vec<String>,
121}
122
123/// Owned type definition data (user-defined value types).
124#[derive(Clone, Debug, PartialEq, Eq)]
125pub struct TypeSource {
126    pub name: String,
127}
128
129/// A wrapper type around owned source data extracted from the parse tree.
130#[derive(Clone, Debug, PartialEq, Eq)]
131pub enum ParseSource {
132    /// Source contract definition.
133    Contract(ContractSource),
134    /// Source function definition.
135    Function(FunctionSource),
136    /// Source variable definition.
137    Variable(VariableSource),
138    /// Source event definition.
139    Event(EventSource),
140    /// Source error definition.
141    Error(ErrorSource),
142    /// Source struct definition.
143    Struct(StructSource),
144    /// Source enum definition.
145    Enum(EnumSource),
146    /// Source type definition.
147    Type(TypeSource),
148}
149
150impl ParseSource {
151    /// Get the identity of the source.
152    pub fn ident(&self) -> String {
153        match self {
154            Self::Contract(c) => c.name.clone(),
155            Self::Variable(v) => v.name.clone(),
156            Self::Event(e) => e.name.clone(),
157            Self::Error(e) => e.name.clone(),
158            Self::Struct(s) => s.name.clone(),
159            Self::Enum(e) => e.name.clone(),
160            Self::Function(f) => f.name.clone().unwrap_or_else(|| f.kind.clone()),
161            Self::Type(t) => t.name.clone(),
162        }
163    }
164
165    /// Get the signature of the source (for functions, includes parameter types).
166    pub fn signature(&self) -> String {
167        match self {
168            Self::Function(f) => f.signature(),
169            _ => self.ident(),
170        }
171    }
172}
forge_doc/parser/source.rs

forge_doc/parser/
source.rs
