rustdoc_json_types_fork/
lib.rs

1// See https://raw.githubusercontent.com/rust-lang/rust/1.57.0/src/rustdoc-json-types/lib.rs
2
3//! Rustdoc's JSON output interface
4//!
5//! These types are the public API exposed through the `--output-format json` flag. The [`Crate`]
6//! struct is the root of the JSON blob and all other items are contained within.
7
8use std::collections::{HashMap, HashSet};
9use std::path::PathBuf;
10
11use serde::{Deserialize, Serialize};
12
13/// A `Crate` is the root of the emitted JSON blob. It contains all type/documentation information
14/// about the language items in the local crate, as well as info about external items to allow
15/// tools to find or link to them.
16#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
17pub struct Crate {
18    /// The id of the root [`Module`] item of the local crate.
19    pub root: Id,
20    /// The version string given to `--crate-version`, if any.
21    pub crate_version: Option<String>,
22    /// Whether or not the output includes private items.
23    pub includes_private: bool,
24    /// A collection of all items in the local crate as well as some external traits and their
25    /// items that are referenced locally.
26    pub index: HashMap<Id, Item>,
27    /// Maps IDs to fully qualified paths and other info helpful for generating links.
28    pub paths: HashMap<Id, ItemSummary>,
29    /// Maps `crate_id` of items to a crate name and html_root_url if it exists.
30    pub external_crates: HashMap<u32, ExternalCrate>,
31    /// A single version number to be used in the future when making backwards incompatible changes
32    /// to the JSON output.
33    pub format_version: u32,
34}
35
36#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
37pub struct ExternalCrate {
38    pub name: String,
39    pub html_root_url: Option<String>,
40}
41
42/// For external (not defined in the local crate) items, you don't get the same level of
43/// information. This struct should contain enough to generate a link/reference to the item in
44/// question, or can be used by a tool that takes the json output of multiple crates to find
45/// the actual item definition with all the relevant info.
46#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
47pub struct ItemSummary {
48    /// Can be used to look up the name and html_root_url of the crate this item came from in the
49    /// `external_crates` map.
50    pub crate_id: u32,
51    /// The list of path components for the fully qualified path of this item (e.g.
52    /// `["std", "io", "lazy", "Lazy"]` for `std::io::lazy::Lazy`).
53    pub path: Vec<String>,
54    /// Whether this item is a struct, trait, macro, etc.
55    pub kind: ItemKind,
56}
57
58#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
59pub struct Item {
60    /// The unique identifier of this item. Can be used to find this item in various mappings.
61    pub id: Id,
62    /// This can be used as a key to the `external_crates` map of [`Crate`] to see which crate
63    /// this item came from.
64    pub crate_id: u32,
65    /// Some items such as impls don't have names.
66    pub name: Option<String>,
67    /// The source location of this item (absent if it came from a macro expansion or inline
68    /// assembly).
69    pub span: Option<Span>,
70    /// By default all documented items are public, but you can tell rustdoc to output private items
71    /// so this field is needed to differentiate.
72    pub visibility: Visibility,
73    /// The full markdown docstring of this item. Absent if there is no documentation at all,
74    /// Some("") if there is some documentation but it is empty (EG `#[doc = ""]`).
75    pub docs: Option<String>,
76    /// This mapping resolves [intra-doc links](https://github.com/rust-lang/rfcs/blob/master/text/1946-intra-rustdoc-links.md) from the docstring to their IDs
77    pub links: HashMap<String, Id>,
78    /// Stringified versions of the attributes on this item (e.g. `"#[inline]"`)
79    pub attrs: Vec<String>,
80    pub deprecation: Option<Deprecation>,
81    #[serde(flatten)]
82    pub inner: ItemEnum,
83}
84
85#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
86pub struct Span {
87    /// The path to the source file for this span relative to the path `rustdoc` was invoked with.
88    pub filename: PathBuf,
89    /// Zero indexed Line and Column of the first character of the `Span`
90    pub begin: (usize, usize),
91    /// Zero indexed Line and Column of the last character of the `Span`
92    pub end: (usize, usize),
93}
94
95#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
96pub struct Deprecation {
97    pub since: Option<String>,
98    pub note: Option<String>,
99}
100
101#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
102#[serde(rename_all = "snake_case")]
103pub enum Visibility {
104    Public,
105    /// For the most part items are private by default. The exceptions are associated items of
106    /// public traits and variants of public enums.
107    Default,
108    Crate,
109    /// For `pub(in path)` visibility. `parent` is the module it's restricted to and `path` is how
110    /// that module was referenced (like `"super::super"` or `"crate::foo::bar"`).
111    Restricted {
112        parent: Id,
113        path: String,
114    },
115}
116
117#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
118#[serde(rename_all = "snake_case")]
119pub enum GenericArgs {
120    /// <'a, 32, B: Copy, C = u32>
121    AngleBracketed {
122        args: Vec<GenericArg>,
123        bindings: Vec<TypeBinding>,
124    },
125    /// Fn(A, B) -> C
126    Parenthesized {
127        inputs: Vec<Type>,
128        output: Option<Type>,
129    },
130}
131
132#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
133#[serde(rename_all = "snake_case")]
134pub enum GenericArg {
135    Lifetime(String),
136    Type(Type),
137    Const(Constant),
138    Infer,
139}
140
141#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
142pub struct Constant {
143    #[serde(rename = "type")]
144    pub type_: Type,
145    pub expr: String,
146    pub value: Option<String>,
147    pub is_literal: bool,
148}
149
150#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
151pub struct TypeBinding {
152    pub name: String,
153    pub binding: TypeBindingKind,
154}
155
156#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
157#[serde(rename_all = "snake_case")]
158pub enum TypeBindingKind {
159    Equality(Type),
160    Constraint(Vec<GenericBound>),
161}
162
163#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
164pub struct Id(pub String);
165
166#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
167#[serde(rename_all = "snake_case")]
168pub enum ItemKind {
169    Module,
170    ExternCrate,
171    Import,
172    Struct,
173    StructField,
174    Union,
175    Enum,
176    Variant,
177    Function,
178    Typedef,
179    OpaqueTy,
180    Constant,
181    Trait,
182    TraitAlias,
183    Method,
184    Impl,
185    Static,
186    ForeignType,
187    Macro,
188    ProcAttribute,
189    ProcDerive,
190    AssocConst,
191    AssocType,
192    Primitive,
193    Keyword,
194}
195
196#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
197#[serde(tag = "kind", content = "inner", rename_all = "snake_case")]
198pub enum ItemEnum {
199    Module(Module),
200    ExternCrate {
201        name: String,
202        rename: Option<String>,
203    },
204    Import(Import),
205
206    Union(Union),
207    Struct(Struct),
208    StructField(Type),
209    Enum(Enum),
210    Variant(Variant),
211
212    Function(Function),
213
214    Trait(Trait),
215    TraitAlias(TraitAlias),
216    Method(Method),
217    Impl(Impl),
218
219    Typedef(Typedef),
220    OpaqueTy(OpaqueTy),
221    Constant(Constant),
222
223    Static(Static),
224
225    /// `type`s from an extern block
226    ForeignType,
227
228    /// Declarative macro_rules! macro
229    Macro(String),
230    ProcMacro(ProcMacro),
231
232    PrimitiveType(String),
233
234    AssocConst {
235        #[serde(rename = "type")]
236        type_: Type,
237        /// e.g. `const X: usize = 5;`
238        default: Option<String>,
239    },
240    AssocType {
241        bounds: Vec<GenericBound>,
242        /// e.g. `type X = usize;`
243        default: Option<Type>,
244    },
245}
246
247#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
248pub struct Module {
249    pub is_crate: bool,
250    pub items: Vec<Id>,
251}
252
253#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
254pub struct Union {
255    pub generics: Generics,
256    pub fields_stripped: bool,
257    pub fields: Vec<Id>,
258    pub impls: Vec<Id>,
259}
260
261#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
262pub struct Struct {
263    pub struct_type: StructType,
264    pub generics: Generics,
265    pub fields_stripped: bool,
266    pub fields: Vec<Id>,
267    pub impls: Vec<Id>,
268}
269
270#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
271pub struct Enum {
272    pub generics: Generics,
273    pub variants_stripped: bool,
274    pub variants: Vec<Id>,
275    pub impls: Vec<Id>,
276}
277
278#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
279#[serde(rename_all = "snake_case")]
280#[serde(tag = "variant_kind", content = "variant_inner")]
281pub enum Variant {
282    Plain,
283    Tuple(Vec<Type>),
284    Struct(Vec<Id>),
285}
286
287#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
288#[serde(rename_all = "snake_case")]
289pub enum StructType {
290    Plain,
291    Tuple,
292    Unit,
293}
294
295#[non_exhaustive]
296#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
297#[serde(rename_all = "snake_case")]
298pub enum Qualifiers {
299    Const,
300    Unsafe,
301    Async,
302}
303
304#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
305pub struct Function {
306    pub decl: FnDecl,
307    pub generics: Generics,
308    pub header: HashSet<Qualifiers>,
309    pub abi: String,
310}
311
312#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
313pub struct Method {
314    pub decl: FnDecl,
315    pub generics: Generics,
316    pub header: HashSet<Qualifiers>,
317    pub abi: String,
318    pub has_body: bool,
319}
320
321#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
322pub struct Generics {
323    pub params: Vec<GenericParamDef>,
324    pub where_predicates: Vec<WherePredicate>,
325}
326
327#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
328pub struct GenericParamDef {
329    pub name: String,
330    pub kind: GenericParamDefKind,
331}
332
333#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
334#[serde(rename_all = "snake_case")]
335pub enum GenericParamDefKind {
336    Lifetime {
337        outlives: Vec<String>,
338    },
339    Type {
340        bounds: Vec<GenericBound>,
341        default: Option<Type>,
342    },
343    Const {
344        ty: Type,
345        default: Option<String>,
346    },
347}
348
349#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
350#[serde(rename_all = "snake_case")]
351pub enum WherePredicate {
352    BoundPredicate {
353        ty: Type,
354        bounds: Vec<GenericBound>,
355    },
356    RegionPredicate {
357        lifetime: String,
358        bounds: Vec<GenericBound>,
359    },
360    EqPredicate {
361        lhs: Type,
362        rhs: Type,
363    },
364}
365
366#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
367#[serde(rename_all = "snake_case")]
368pub enum GenericBound {
369    TraitBound {
370        #[serde(rename = "trait")]
371        trait_: Type,
372        /// Used for HRTBs
373        generic_params: Vec<GenericParamDef>,
374        modifier: TraitBoundModifier,
375    },
376    Outlives(String),
377}
378
379#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
380#[serde(rename_all = "snake_case")]
381pub enum TraitBoundModifier {
382    None,
383    Maybe,
384    MaybeConst,
385}
386
387#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
388#[serde(rename_all = "snake_case")]
389#[serde(tag = "kind", content = "inner")]
390pub enum Type {
391    /// Structs, enums, and traits
392    ResolvedPath {
393        name: String,
394        id: Id,
395        args: Option<Box<GenericArgs>>,
396        param_names: Vec<GenericBound>,
397    },
398    /// Parameterized types
399    Generic(String),
400    /// Fixed-size numeric types (plus int/usize/float), char, arrays, slices, and tuples
401    Primitive(String),
402    /// `extern "ABI" fn`
403    FunctionPointer(Box<FunctionPointer>),
404    /// `(String, u32, Box<usize>)`
405    Tuple(Vec<Type>),
406    /// `[u32]`
407    Slice(Box<Type>),
408    /// [u32; 15]
409    Array {
410        #[serde(rename = "type")]
411        type_: Box<Type>,
412        len: String,
413    },
414    /// `impl TraitA + TraitB + ...`
415    ImplTrait(Vec<GenericBound>),
416    /// `_`
417    Infer,
418    /// `*mut u32`, `*u8`, etc.
419    RawPointer {
420        mutable: bool,
421        #[serde(rename = "type")]
422        type_: Box<Type>,
423    },
424    /// `&'a mut String`, `&str`, etc.
425    BorrowedRef {
426        lifetime: Option<String>,
427        mutable: bool,
428        #[serde(rename = "type")]
429        type_: Box<Type>,
430    },
431    /// `<Type as Trait>::Name` or associated types like `T::Item` where `T: Iterator`
432    QualifiedPath {
433        name: String,
434        self_type: Box<Type>,
435        #[serde(rename = "trait")]
436        trait_: Box<Type>,
437    },
438}
439
440#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
441pub struct FunctionPointer {
442    pub decl: FnDecl,
443    pub generic_params: Vec<GenericParamDef>,
444    pub header: HashSet<Qualifiers>,
445    pub abi: String,
446}
447
448#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
449pub struct FnDecl {
450    pub inputs: Vec<(String, Type)>,
451    pub output: Option<Type>,
452    pub c_variadic: bool,
453}
454
455#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
456pub struct Trait {
457    pub is_auto: bool,
458    pub is_unsafe: bool,
459    pub items: Vec<Id>,
460    pub generics: Generics,
461    pub bounds: Vec<GenericBound>,
462    pub implementors: Vec<Id>,
463}
464
465#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
466pub struct TraitAlias {
467    pub generics: Generics,
468    pub params: Vec<GenericBound>,
469}
470
471#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
472pub struct Impl {
473    pub is_unsafe: bool,
474    pub generics: Generics,
475    pub provided_trait_methods: Vec<String>,
476    #[serde(rename = "trait")]
477    pub trait_: Option<Type>,
478    #[serde(rename = "for")]
479    pub for_: Type,
480    pub items: Vec<Id>,
481    pub negative: bool,
482    pub synthetic: bool,
483    pub blanket_impl: Option<Type>,
484}
485
486#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
487#[serde(rename_all = "snake_case")]
488pub struct Import {
489    /// The full path being imported.
490    pub source: String,
491    /// May be different from the last segment of `source` when renaming imports:
492    /// `use source as name;`
493    pub name: String,
494    /// The ID of the item being imported.
495    pub id: Option<Id>, // FIXME is this actually ever None?
496    /// Whether this import uses a glob: `use source::*;`
497    pub glob: bool,
498}
499
500#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
501pub struct ProcMacro {
502    pub kind: MacroKind,
503    pub helpers: Vec<String>,
504}
505
506#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
507#[serde(rename_all = "snake_case")]
508pub enum MacroKind {
509    /// A bang macro `foo!()`.
510    Bang,
511    /// An attribute macro `#[foo]`.
512    Attr,
513    /// A derive macro `#[derive(Foo)]`
514    Derive,
515}
516
517#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
518pub struct Typedef {
519    #[serde(rename = "type")]
520    pub type_: Type,
521    pub generics: Generics,
522}
523
524#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
525pub struct OpaqueTy {
526    pub bounds: Vec<GenericBound>,
527    pub generics: Generics,
528}
529
530#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
531pub struct Static {
532    #[serde(rename = "type")]
533    pub type_: Type,
534    pub mutable: bool,
535    pub expr: String,
536}
537
538/// rustdoc format-version.
539pub const FORMAT_VERSION: u32 = 9;
540
541//#[cfg(test)]
542//mod tests;
rustdoc_json_types_fork/lib.rs

rustdoc_json_types_fork/
lib.rs
