cargo_docs_md/source/
types.rs

1//! Types for representing parsed source code information.
2//!
3//! These types complement rustdoc JSON by providing information
4//! that is only available from parsing source code directly.
5
6use std::path::PathBuf;
7
8/// Information about a parsed function, including its body.
9#[derive(Debug, Clone)]
10pub struct FunctionInfo {
11    /// The function name.
12    pub name: String,
13
14    /// Full module path (e.g., `crate::module::submodule`).
15    pub module_path: String,
16
17    /// The function signature as a string.
18    pub signature: String,
19
20    /// The function body as source code.
21    pub body: String,
22
23    /// Whether this function is public.
24    pub is_public: bool,
25
26    /// Doc comments extracted from `///` or `//!` attributes.
27    pub doc_comments: Vec<String>,
28
29    /// Source file where this function is defined.
30    pub source_file: PathBuf,
31
32    /// Line number where the function starts.
33    pub line_number: usize,
34}
35
36/// Information about a parsed struct.
37#[derive(Debug, Clone)]
38pub struct StructInfo {
39    /// The struct name.
40    pub name: String,
41
42    /// Full module path.
43    pub module_path: String,
44
45    /// The full struct definition as source code.
46    pub definition: String,
47
48    /// Whether this struct is public.
49    pub is_public: bool,
50
51    /// Doc comments.
52    pub doc_comments: Vec<String>,
53
54    /// Source file location.
55    pub source_file: PathBuf,
56
57    /// Line number.
58    pub line_number: usize,
59
60    /// Field information (for struct fields).
61    pub fields: Vec<FieldInfo>,
62}
63
64/// Information about a struct or enum field.
65#[derive(Debug, Clone)]
66pub struct FieldInfo {
67    /// Field name (None for tuple struct fields).
68    pub name: Option<String>,
69
70    /// Field type as a string.
71    pub ty: String,
72
73    /// Whether this field is public.
74    pub is_public: bool,
75
76    /// Doc comments for this field.
77    pub doc_comments: Vec<String>,
78}
79
80/// Information about a parsed enum.
81#[derive(Debug, Clone)]
82pub struct EnumInfo {
83    /// The enum name.
84    pub name: String,
85
86    /// Full module path.
87    pub module_path: String,
88
89    /// The full enum definition as source code.
90    pub definition: String,
91
92    /// Whether this enum is public.
93    pub is_public: bool,
94
95    /// Doc comments.
96    pub doc_comments: Vec<String>,
97
98    /// Source file location.
99    pub source_file: PathBuf,
100
101    /// Line number.
102    pub line_number: usize,
103
104    /// Variant information.
105    pub variants: Vec<VariantInfo>,
106}
107
108/// Information about an enum variant.
109#[derive(Debug, Clone)]
110pub struct VariantInfo {
111    /// Variant name.
112    pub name: String,
113
114    /// Doc comments for this variant.
115    pub doc_comments: Vec<String>,
116
117    /// Fields (for tuple or struct variants).
118    pub fields: Vec<FieldInfo>,
119}
120
121/// Information about a parsed trait.
122#[derive(Debug, Clone)]
123pub struct TraitInfo {
124    /// The trait name.
125    pub name: String,
126
127    /// Full module path.
128    pub module_path: String,
129
130    /// The full trait definition as source code.
131    pub definition: String,
132
133    /// Whether this trait is public.
134    pub is_public: bool,
135
136    /// Doc comments.
137    pub doc_comments: Vec<String>,
138
139    /// Source file location.
140    pub source_file: PathBuf,
141
142    /// Line number.
143    pub line_number: usize,
144}
145
146/// Information about an impl block.
147#[derive(Debug, Clone)]
148pub struct ImplInfo {
149    /// The type being implemented for (e.g., `MyStruct`).
150    pub self_ty: String,
151
152    /// The trait being implemented (if any).
153    pub trait_name: Option<String>,
154
155    /// Full module path where this impl is defined.
156    pub module_path: String,
157
158    /// Methods in this impl block.
159    pub methods: Vec<FunctionInfo>,
160
161    /// Source file location.
162    pub source_file: PathBuf,
163
164    /// Line number.
165    pub line_number: usize,
166}
167
168/// Information about a constant.
169#[derive(Debug, Clone)]
170pub struct ConstInfo {
171    /// The constant name.
172    pub name: String,
173
174    /// Full module path.
175    pub module_path: String,
176
177    /// The type of the constant.
178    pub ty: String,
179
180    /// The value expression as source code.
181    pub value: String,
182
183    /// Whether this constant is public.
184    pub is_public: bool,
185
186    /// Doc comments.
187    pub doc_comments: Vec<String>,
188
189    /// Source file location.
190    pub source_file: PathBuf,
191
192    /// Line number.
193    pub line_number: usize,
194}
195
196/// Information about a static variable.
197#[derive(Debug, Clone)]
198pub struct StaticInfo {
199    /// The static name.
200    pub name: String,
201
202    /// Full module path.
203    pub module_path: String,
204
205    /// The type of the static.
206    pub ty: String,
207
208    /// The value expression as source code.
209    pub value: String,
210
211    /// Whether this static is mutable.
212    pub is_mutable: bool,
213
214    /// Whether this static is public.
215    pub is_public: bool,
216
217    /// Doc comments.
218    pub doc_comments: Vec<String>,
219
220    /// Source file location.
221    pub source_file: PathBuf,
222
223    /// Line number.
224    pub line_number: usize,
225}
226
227/// Information about a type alias.
228#[derive(Debug, Clone)]
229pub struct TypeAliasInfo {
230    /// The type alias name.
231    pub name: String,
232
233    /// Full module path.
234    pub module_path: String,
235
236    /// The aliased type as a string.
237    pub aliased_type: String,
238
239    /// Whether this type alias is public.
240    pub is_public: bool,
241
242    /// Doc comments.
243    pub doc_comments: Vec<String>,
244
245    /// Source file location.
246    pub source_file: PathBuf,
247
248    /// Line number.
249    pub line_number: usize,
250}
251
252/// Information about a macro definition.
253#[derive(Debug, Clone)]
254pub struct MacroInfo {
255    /// The macro name.
256    pub name: String,
257
258    /// Full module path.
259    pub module_path: String,
260
261    /// The full macro definition as source code.
262    pub definition: String,
263
264    /// Doc comments.
265    pub doc_comments: Vec<String>,
266
267    /// Source file location.
268    pub source_file: PathBuf,
269
270    /// Line number.
271    pub line_number: usize,
272}
273
274/// Aggregated source information for an entire crate.
275#[derive(Debug, Default)]
276pub struct CrateSource {
277    /// Crate name.
278    pub name: String,
279
280    /// Crate version (from Cargo.toml).
281    pub version: String,
282
283    /// Root path of the crate source.
284    pub root_path: PathBuf,
285
286    /// All parsed functions (including methods).
287    pub functions: Vec<FunctionInfo>,
288
289    /// All parsed structs.
290    pub structs: Vec<StructInfo>,
291
292    /// All parsed enums.
293    pub enums: Vec<EnumInfo>,
294
295    /// All parsed traits.
296    pub traits: Vec<TraitInfo>,
297
298    /// All parsed impl blocks.
299    pub impls: Vec<ImplInfo>,
300
301    /// All parsed constants.
302    pub constants: Vec<ConstInfo>,
303
304    /// All parsed statics.
305    pub statics: Vec<StaticInfo>,
306
307    /// All parsed type aliases.
308    pub type_aliases: Vec<TypeAliasInfo>,
309
310    /// All parsed macro definitions.
311    pub macros: Vec<MacroInfo>,
312}
313
314impl CrateSource {
315    /// Create a new empty `CrateSource`.
316    #[must_use]
317    pub fn new(name: String, version: String, root_path: PathBuf) -> Self {
318        Self {
319            name,
320            version,
321            root_path,
322            ..Default::default()
323        }
324    }
325
326    /// Look up a function by its full path.
327    #[must_use]
328    pub fn find_function(&self, path: &str) -> Option<&FunctionInfo> {
329        self.functions.iter().find(|f| {
330            let full_path = format!("{}::{}", f.module_path, f.name);
331            full_path == path
332        })
333    }
334
335    /// Look up a struct by its full path.
336    #[must_use]
337    pub fn find_struct(&self, path: &str) -> Option<&StructInfo> {
338        self.structs.iter().find(|s| {
339            let full_path = format!("{}::{}", s.module_path, s.name);
340            full_path == path
341        })
342    }
343
344    /// Look up an enum by its full path.
345    #[must_use]
346    pub fn find_enum(&self, path: &str) -> Option<&EnumInfo> {
347        self.enums.iter().find(|e| {
348            let full_path = format!("{}::{}", e.module_path, e.name);
349            full_path == path
350        })
351    }
352
353    /// Look up a trait by its full path.
354    #[must_use]
355    pub fn find_trait(&self, path: &str) -> Option<&TraitInfo> {
356        self.traits.iter().find(|t| {
357            let full_path = format!("{}::{}", t.module_path, t.name);
358            full_path == path
359        })
360    }
361
362    /// Look up a constant by its full path.
363    #[must_use]
364    pub fn find_const(&self, path: &str) -> Option<&ConstInfo> {
365        self.constants.iter().find(|c| {
366            let full_path = format!("{}::{}", c.module_path, c.name);
367            full_path == path
368        })
369    }
370
371    /// Look up a static by its full path.
372    #[must_use]
373    pub fn find_static(&self, path: &str) -> Option<&StaticInfo> {
374        self.statics.iter().find(|s| {
375            let full_path = format!("{}::{}", s.module_path, s.name);
376            full_path == path
377        })
378    }
379
380    /// Get all private items (functions, structs, etc.) in a module.
381    #[must_use]
382    pub fn private_items_in_module(&self, module_path: &str) -> Vec<PrivateItem<'_>> {
383        let mut items = Vec::new();
384
385        for f in &self.functions {
386            if !f.is_public && f.module_path == module_path {
387                items.push(PrivateItem::Function(f));
388            }
389        }
390
391        for s in &self.structs {
392            if !s.is_public && s.module_path == module_path {
393                items.push(PrivateItem::Struct(s));
394            }
395        }
396
397        for e in &self.enums {
398            if !e.is_public && e.module_path == module_path {
399                items.push(PrivateItem::Enum(e));
400            }
401        }
402
403        items
404    }
405}
406
407/// A reference to a private item for rendering.
408#[derive(Debug)]
409pub enum PrivateItem<'a> {
410    /// A private function.
411    Function(&'a FunctionInfo),
412
413    /// A private struct.
414    Struct(&'a StructInfo),
415
416    /// A private enum.
417    Enum(&'a EnumInfo),
418
419    /// A private constant.
420    Const(&'a ConstInfo),
421
422    /// A private type alias.
423    TypeAlias(&'a TypeAliasInfo),
424}
cargo_docs_md/source/types.rs

cargo_docs_md/source/
types.rs
