rune/doc/
context.rs

Help
1use crate::alloc::prelude::*;
2use crate::alloc::{self, String, Vec};
3use crate::compile::context::ContextMeta;
4use crate::compile::meta;
5use crate::doc::{Visitor, VisitorData};
6use crate::item::{ComponentRef, IntoComponent};
7use crate::runtime::ConstValue;
8use crate::runtime::Protocol;
9use crate::{Hash, Item, ItemBuf};
10
11#[derive(Debug, Clone, Copy)]
12pub(crate) enum MetaSource<'a> {
13    /// Meta came from context.
14    Context,
15    /// Meta came from source.
16    Source(#[allow(unused)] &'a Item),
17}
18
19#[derive(Debug, Clone, Copy)]
20pub(crate) struct Meta<'a> {
21    /// Kind of the meta item.
22    pub(crate) kind: Kind<'a>,
23    /// Item of the meta.
24    pub(crate) item: &'a Item,
25    /// Type hash for the meta item.
26    pub(crate) hash: Hash,
27    /// The meta source.
28    #[allow(unused)]
29    pub(crate) source: MetaSource<'a>,
30    /// Indicates if the item is deprecated.
31    pub(crate) deprecated: Option<&'a str>,
32    /// Documentation for the meta item.
33    pub(crate) docs: &'a [String],
34}
35
36#[derive(Debug, Clone, Copy)]
37pub(crate) struct Function<'a> {
38    pub(crate) is_async: bool,
39    pub(crate) is_test: bool,
40    pub(crate) is_bench: bool,
41    pub(crate) signature: Signature,
42    pub(crate) arguments: Option<&'a [meta::DocArgument]>,
43    pub(crate) return_type: &'a meta::DocType,
44}
45
46/// The kind of an associated function.
47#[derive(Debug)]
48pub(crate) enum AssocFnKind<'a> {
49    /// A protocol function implemented on the type itself.
50    Protocol(&'static Protocol),
51    /// A field function with the given protocol.
52    FieldFn(&'static Protocol, &'a str),
53    /// An index function with the given protocol.
54    IndexFn(&'static Protocol, usize),
55    /// The instance function refers to the given named instance fn.
56    Method(&'a Item, &'a str, Signature),
57}
58
59/// Information on an associated function.
60#[derive(Debug)]
61pub(crate) struct AssocVariant<'a> {
62    /// Name of variant.
63    pub(crate) name: &'a str,
64    /// Documentation for variant.
65    pub(crate) docs: &'a [String],
66}
67
68/// Information on an associated function.
69#[derive(Debug)]
70pub(crate) struct AssocFn<'a> {
71    pub(crate) kind: AssocFnKind<'a>,
72    pub(crate) trait_hash: Option<Hash>,
73    pub(crate) is_async: bool,
74    pub(crate) arguments: Option<&'a [meta::DocArgument]>,
75    pub(crate) return_type: &'a meta::DocType,
76    /// Generic instance parameters for function.
77    pub(crate) parameter_types: &'a [Hash],
78    pub(crate) deprecated: Option<&'a str>,
79    pub(crate) docs: &'a [String],
80}
81
82/// Information on an associated item.
83#[derive(Debug)]
84pub(crate) enum Assoc<'a> {
85    /// A variant,
86    Variant(AssocVariant<'a>),
87    /// An associated function.
88    Fn(AssocFn<'a>),
89}
90
91#[derive(Debug, Clone, Copy)]
92pub(crate) enum Kind<'a> {
93    Unsupported,
94    Type,
95    Struct,
96    Variant,
97    Enum,
98    Macro,
99    Function(Function<'a>),
100    Const(#[allow(unused)] &'a ConstValue),
101    Module,
102    Trait,
103}
104
105#[derive(Debug, Clone, Copy)]
106pub(crate) enum Signature {
107    Function,
108    Instance,
109}
110
111/// Build context for documentation.
112///
113/// Provides a unified API for querying information about known types.
114pub(crate) struct Context<'a> {
115    context: Option<&'a crate::Context>,
116    visitors: &'a [Visitor],
117}
118
119impl<'a> Context<'a> {
120    pub(crate) fn new(context: Option<&'a crate::Context>, visitors: &'a [Visitor]) -> Self {
121        Self { context, visitors }
122    }
123
124    /// Iterate over all types associated with the given hash.
125    pub(crate) fn associated(&self, hash: Hash) -> impl Iterator<Item = Hash> + '_ {
126        let visitors = self
127            .visitors
128            .iter()
129            .flat_map(move |v| {
130                v.associated
131                    .get(&hash)
132                    .map(Vec::as_slice)
133                    .unwrap_or_default()
134            })
135            .copied();
136
137        let context = self
138            .context
139            .into_iter()
140            .flat_map(move |c| c.associated(hash));
141
142        visitors.chain(context)
143    }
144
145    pub(crate) fn associated_meta(&self, hash: Hash) -> impl Iterator<Item = Assoc<'a>> + '_ {
146        let visitors = self
147            .visitors
148            .iter()
149            .flat_map(move |v| visitor_to_associated(v, hash));
150
151        let context = self
152            .context
153            .into_iter()
154            .flat_map(move |c| context_to_associated(c, hash));
155
156        visitors.chain(context)
157    }
158
159    /// Iterate over all traits associated with the given hash.
160    pub(crate) fn traits(&self, hash: Hash) -> impl Iterator<Item = Hash> + 'a {
161        self.context.into_iter().flat_map(move |c| c.traits(hash))
162    }
163
164    /// Iterate over known child components of the given name.
165    pub(crate) fn iter_components<I>(
166        &self,
167        iter: I,
168    ) -> alloc::Result<impl Iterator<Item = (MetaSource<'a>, ComponentRef<'a>)> + 'a>
169    where
170        I: 'a + Clone + IntoIterator,
171        I::Item: IntoComponent,
172    {
173        let mut out = Vec::new();
174
175        if let Some(context) = self.context {
176            for c in context.iter_components(iter.clone())? {
177                out.try_push((MetaSource::Context, c))?;
178            }
179        }
180
181        for v in self.visitors {
182            for c in v.names.iter_components(iter.clone())? {
183                out.try_push((MetaSource::Source(&v.base), c))?;
184            }
185        }
186
187        Ok(out.into_iter())
188    }
189
190    /// Get all matching meta items by hash.
191    pub(crate) fn meta_by_hash(&self, hash: Hash) -> alloc::Result<Vec<Meta<'a>>> {
192        let mut out = Vec::new();
193
194        for visitor in self.visitors {
195            if let Some(data) = visitor.get_by_hash(hash) {
196                out.try_push(visitor_meta_to_meta(&visitor.base, data))?;
197            }
198        }
199
200        if let Some(context) = self.context {
201            for meta in context.lookup_meta_by_hash(hash) {
202                out.try_extend(self.context_meta_to_meta(meta))?;
203            }
204        }
205
206        Ok(out)
207    }
208
209    /// Lookup all meta matching the given item.
210    pub(crate) fn meta(&self, item: &Item) -> alloc::Result<Vec<Meta<'a>>> {
211        let mut out = Vec::new();
212
213        for visitor in self.visitors {
214            if let Some(data) = visitor.get(item) {
215                out.try_push(visitor_meta_to_meta(&visitor.base, data))?;
216            }
217        }
218
219        if let Some(context) = self.context {
220            for meta in context.lookup_meta(item).into_iter().flatten() {
221                out.try_extend(self.context_meta_to_meta(meta))?;
222            }
223        }
224
225        Ok(out)
226    }
227
228    fn context_meta_to_meta(&self, meta: &'a ContextMeta) -> Option<Meta<'a>> {
229        let item = meta.item.as_deref()?;
230
231        let kind = match &meta.kind {
232            meta::Kind::Type { .. } => Kind::Type,
233            meta::Kind::Struct {
234                enum_hash: Hash::EMPTY,
235                ..
236            } => Kind::Struct,
237            meta::Kind::Struct { .. } => Kind::Variant,
238            meta::Kind::Enum { .. } => Kind::Enum,
239            meta::Kind::Function {
240                associated: None,
241                signature: f,
242                is_test,
243                is_bench,
244                ..
245            } => Kind::Function(Function {
246                is_async: f.is_async,
247                is_test: *is_test,
248                is_bench: *is_bench,
249                signature: Signature::Function,
250                arguments: f.arguments.as_deref(),
251                return_type: &f.return_type,
252            }),
253            meta::Kind::Function {
254                associated: Some(..),
255                signature: f,
256                is_test,
257                is_bench,
258                ..
259            } => Kind::Function(Function {
260                is_async: f.is_async,
261                is_test: *is_test,
262                is_bench: *is_bench,
263                signature: Signature::Instance,
264                arguments: f.arguments.as_deref(),
265                return_type: &f.return_type,
266            }),
267            meta::Kind::Const => {
268                let const_value = self.context?.get_const_value(meta.hash)?;
269                Kind::Const(const_value)
270            }
271            meta::Kind::Macro => Kind::Macro,
272            meta::Kind::Module => Kind::Module,
273            meta::Kind::Trait => Kind::Trait,
274            _ => Kind::Unsupported,
275        };
276
277        Some(Meta {
278            kind,
279            source: MetaSource::Context,
280            item,
281            hash: meta.hash,
282            deprecated: meta.deprecated.as_deref(),
283            docs: meta.docs.lines(),
284        })
285    }
286
287    /// Iterate over known modules.
288    pub(crate) fn iter_modules(&self) -> impl IntoIterator<Item = alloc::Result<ItemBuf>> + '_ {
289        let visitors = self
290            .visitors
291            .iter()
292            .flat_map(|v| v.base.as_crate().map(ItemBuf::with_crate));
293
294        let contexts = self
295            .context
296            .into_iter()
297            .flat_map(|c| c.iter_crates().map(ItemBuf::with_crate));
298
299        visitors.chain(contexts)
300    }
301}
302
303fn visitor_to_associated(visitor: &Visitor, hash: Hash) -> impl Iterator<Item = Assoc<'_>> + '_ {
304    let associated = visitor.associated.get(&hash).into_iter();
305
306    associated.flat_map(move |a| {
307        a.iter().flat_map(move |hash| {
308            let data = visitor.data.get(hash)?;
309
310            let (associated, trait_hash, signature) = match data.kind.as_ref()? {
311                meta::Kind::Function {
312                    associated,
313                    trait_hash,
314                    signature,
315                    ..
316                } => (associated, trait_hash, signature),
317                meta::Kind::Struct { enum_hash, .. } if *enum_hash != Hash::EMPTY => {
318                    return Some(Assoc::Variant(AssocVariant {
319                        name: data.item.last()?.as_str()?,
320                        docs: &data.docs,
321                    }));
322                }
323                _ => return None,
324            };
325
326            let kind = match associated {
327                Some(meta::AssociatedKind::Instance(name)) => {
328                    AssocFnKind::Method(&data.item, name.as_ref(), Signature::Instance)
329                }
330                None => AssocFnKind::Method(
331                    &data.item,
332                    data.item.last()?.as_str()?,
333                    Signature::Function,
334                ),
335                _ => return None,
336            };
337
338            Some(Assoc::Fn(AssocFn {
339                kind,
340                trait_hash: *trait_hash,
341                is_async: signature.is_async,
342                arguments: signature.arguments.as_deref(),
343                return_type: &signature.return_type,
344                parameter_types: &[],
345                deprecated: data.deprecated.as_deref(),
346                docs: &data.docs,
347            }))
348        })
349    })
350}
351
352fn context_to_associated(context: &crate::Context, hash: Hash) -> Option<Assoc<'_>> {
353    let meta = context.lookup_meta_by_hash(hash).next()?;
354
355    match meta.kind {
356        meta::Kind::Struct { enum_hash, .. } if enum_hash != Hash::EMPTY => {
357            let name = meta.item.as_deref()?.last()?.as_str()?;
358
359            Some(Assoc::Variant(AssocVariant {
360                name,
361                docs: meta.docs.lines(),
362            }))
363        }
364        meta::Kind::Function {
365            associated: Some(ref associated),
366            trait_hash,
367            ref parameter_types,
368            ref signature,
369            ..
370        } => {
371            let kind = match *associated {
372                meta::AssociatedKind::Protocol(protocol) => AssocFnKind::Protocol(protocol),
373                meta::AssociatedKind::FieldFn(protocol, ref field) => {
374                    AssocFnKind::FieldFn(protocol, field)
375                }
376                meta::AssociatedKind::IndexFn(protocol, index) => {
377                    AssocFnKind::IndexFn(protocol, index)
378                }
379                meta::AssociatedKind::Instance(ref name) => {
380                    AssocFnKind::Method(meta.item.as_ref()?, name, Signature::Instance)
381                }
382            };
383
384            Some(Assoc::Fn(AssocFn {
385                kind,
386                trait_hash,
387                is_async: signature.is_async,
388                arguments: signature.arguments.as_deref(),
389                return_type: &signature.return_type,
390                parameter_types: &parameter_types[..],
391                deprecated: meta.deprecated.as_deref(),
392                docs: meta.docs.lines(),
393            }))
394        }
395        meta::Kind::Function {
396            associated: None,
397            trait_hash,
398            ref signature,
399            ..
400        } => {
401            let item = meta.item.as_deref()?;
402            let name = item.last()?.as_str()?;
403            let kind = AssocFnKind::Method(item, name, Signature::Function);
404
405            Some(Assoc::Fn(AssocFn {
406                kind,
407                trait_hash,
408                is_async: signature.is_async,
409                arguments: signature.arguments.as_deref(),
410                return_type: &signature.return_type,
411                parameter_types: &[],
412                deprecated: meta.deprecated.as_deref(),
413                docs: meta.docs.lines(),
414            }))
415        }
416        ref _kind => {
417            tracing::warn!(kind = ?_kind, "Unsupported associated type");
418            None
419        }
420    }
421}
422
423fn visitor_meta_to_meta<'a>(base: &'a Item, data: &'a VisitorData) -> Meta<'a> {
424    let kind = match &data.kind {
425        Some(meta::Kind::Type { .. }) => Kind::Type,
426        Some(meta::Kind::Struct {
427            enum_hash: Hash::EMPTY,
428            ..
429        }) => Kind::Struct,
430        Some(meta::Kind::Struct { .. }) => Kind::Variant,
431        Some(meta::Kind::Enum { .. }) => Kind::Enum,
432        Some(meta::Kind::Function {
433            associated,
434            signature: f,
435            is_test,
436            is_bench,
437            ..
438        }) => Kind::Function(Function {
439            is_async: f.is_async,
440            is_test: *is_test,
441            is_bench: *is_bench,
442            signature: match associated {
443                Some(..) => Signature::Instance,
444                None => Signature::Function,
445            },
446            arguments: f.arguments.as_deref(),
447            return_type: &f.return_type,
448        }),
449        Some(meta::Kind::Module) => Kind::Module,
450        _ => Kind::Unsupported,
451    };
452
453    Meta {
454        source: MetaSource::Source(base),
455        item: &data.item,
456        hash: data.hash,
457        deprecated: None,
458        docs: data.docs.as_slice(),
459        kind,
460    }
461}
rune/doc/context.rs

rune/doc/
context.rs
