1 //! Rustdoc's JSON output interface
3 //! These types are the public API exposed through the `--output-format json` flag. The [`Crate`]
4 //! struct is the root of the JSON blob and all other items are contained within.
6 use std::collections::HashMap;
7 use std::path::PathBuf;
9 use serde::{Deserialize, Serialize};
11 /// rustdoc format-version.
12 pub const FORMAT_VERSION: u32 = 21;
14 /// A `Crate` is the root of the emitted JSON blob. It contains all type/documentation information
15 /// about the language items in the local crate, as well as info about external items to allow
16 /// tools to find or link to them.
17 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
19 /// The id of the root [`Module`] item of the local crate.
21 /// The version string given to `--crate-version`, if any.
22 pub crate_version: Option<String>,
23 /// Whether or not the output includes private items.
24 pub includes_private: bool,
25 /// A collection of all items in the local crate as well as some external traits and their
26 /// items that are referenced locally.
27 pub index: HashMap<Id, Item>,
28 /// Maps IDs to fully qualified paths and other info helpful for generating links.
29 pub paths: HashMap<Id, ItemSummary>,
30 /// Maps `crate_id` of items to a crate name and html_root_url if it exists.
31 pub external_crates: HashMap<u32, ExternalCrate>,
32 /// A single version number to be used in the future when making backwards incompatible changes
33 /// to the JSON output.
34 pub format_version: u32,
37 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
38 pub struct ExternalCrate {
40 pub html_root_url: Option<String>,
43 /// For external (not defined in the local crate) items, you don't get the same level of
44 /// information. This struct should contain enough to generate a link/reference to the item in
45 /// question, or can be used by a tool that takes the json output of multiple crates to find
46 /// the actual item definition with all the relevant info.
47 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
48 pub struct ItemSummary {
49 /// Can be used to look up the name and html_root_url of the crate this item came from in the
50 /// `external_crates` map.
52 /// The list of path components for the fully qualified path of this item (e.g.
53 /// `["std", "io", "lazy", "Lazy"]` for `std::io::lazy::Lazy`).
54 pub path: Vec<String>,
55 /// Whether this item is a struct, trait, macro, etc.
59 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
61 /// The unique identifier of this item. Can be used to find this item in various mappings.
63 /// This can be used as a key to the `external_crates` map of [`Crate`] to see which crate
64 /// this item came from.
66 /// Some items such as impls don't have names.
67 pub name: Option<String>,
68 /// The source location of this item (absent if it came from a macro expansion or inline
70 pub span: Option<Span>,
71 /// By default all documented items are public, but you can tell rustdoc to output private items
72 /// so this field is needed to differentiate.
73 pub visibility: Visibility,
74 /// The full markdown docstring of this item. Absent if there is no documentation at all,
75 /// Some("") if there is some documentation but it is empty (EG `#[doc = ""]`).
76 pub docs: Option<String>,
77 /// 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
78 pub links: HashMap<String, Id>,
79 /// Stringified versions of the attributes on this item (e.g. `"#[inline]"`)
80 pub attrs: Vec<String>,
81 pub deprecation: Option<Deprecation>,
86 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
88 /// The path to the source file for this span relative to the path `rustdoc` was invoked with.
89 pub filename: PathBuf,
90 /// Zero indexed Line and Column of the first character of the `Span`
91 pub begin: (usize, usize),
92 /// Zero indexed Line and Column of the last character of the `Span`
93 pub end: (usize, usize),
96 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
97 pub struct Deprecation {
98 pub since: Option<String>,
99 pub note: Option<String>,
102 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
103 #[serde(rename_all = "snake_case")]
104 pub enum Visibility {
106 /// For the most part items are private by default. The exceptions are associated items of
107 /// public traits and variants of public enums.
110 /// For `pub(in path)` visibility. `parent` is the module it's restricted to and `path` is how
111 /// that module was referenced (like `"super::super"` or `"crate::foo::bar"`).
118 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
119 pub struct DynTrait {
120 /// All the traits implemented. One of them is the vtable, and the rest must be auto traits.
121 pub traits: Vec<PolyTrait>,
122 /// The lifetime of the whole dyn object
124 /// dyn Debug + 'static
129 pub lifetime: Option<String>,
132 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
133 /// A trait and potential HRTBs
134 pub struct PolyTrait {
135 #[serde(rename = "trait")]
137 /// Used for Higher-Rank Trait Bounds (HRTBs)
139 /// dyn for<'a> Fn() -> &'a i32"
144 pub generic_params: Vec<GenericParamDef>,
147 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
148 #[serde(rename_all = "snake_case")]
149 pub enum GenericArgs {
150 /// <'a, 32, B: Copy, C = u32>
151 AngleBracketed { args: Vec<GenericArg>, bindings: Vec<TypeBinding> },
153 Parenthesized { inputs: Vec<Type>, output: Option<Type> },
156 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
157 #[serde(rename_all = "snake_case")]
158 pub enum GenericArg {
165 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
166 pub struct Constant {
167 #[serde(rename = "type")]
170 pub value: Option<String>,
171 pub is_literal: bool,
174 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
175 pub struct TypeBinding {
177 pub args: GenericArgs,
178 pub binding: TypeBindingKind,
181 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
182 #[serde(rename_all = "snake_case")]
183 pub enum TypeBindingKind {
185 Constraint(Vec<GenericBound>),
188 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
189 pub struct Id(pub String);
191 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
192 #[serde(rename_all = "snake_case")]
221 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
222 #[serde(tag = "kind", content = "inner", rename_all = "snake_case")]
227 rename: Option<String>,
240 TraitAlias(TraitAlias),
250 /// `type`s from an extern block
253 /// Declarative macro_rules! macro
255 ProcMacro(ProcMacro),
257 PrimitiveType(String),
260 #[serde(rename = "type")]
262 /// e.g. `const X: usize = 5;`
263 default: Option<String>,
267 bounds: Vec<GenericBound>,
268 /// e.g. `type X = usize;`
269 default: Option<Type>,
273 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
277 /// If `true`, this module is not part of the public API, but it contains
278 /// items that are re-exported as public API.
279 pub is_stripped: bool,
282 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
284 pub generics: Generics,
285 pub fields_stripped: bool,
290 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
292 pub kind: StructKind,
293 pub generics: Generics,
297 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
298 #[serde(rename_all = "snake_case")]
299 pub enum StructKind {
300 /// A struct with no fields and no parentheses.
306 /// A struct with unnamed fields.
309 /// pub struct TupleStruct(i32);
310 /// pub struct EmptyTupleStruct();
313 /// All [`Id`]'s will point to [`ItemEnum::StructField`]. Private and
314 /// `#[doc(hidden)]` fields will be given as `None`
315 Tuple(Vec<Option<Id>>),
316 /// A struct with nammed fields.
319 /// pub struct PlainStruct { x: i32 }
320 /// pub struct EmptyPlainStruct {}
322 Plain { fields: Vec<Id>, fields_stripped: bool },
325 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
327 pub generics: Generics,
328 pub variants_stripped: bool,
329 pub variants: Vec<Id>,
333 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
334 #[serde(rename_all = "snake_case")]
335 #[serde(tag = "variant_kind", content = "variant_inner")]
337 /// A variant with no parentheses, and possible discriminant.
342 /// PlainWithDiscriminant = 1,
345 Plain(Option<Discriminant>),
346 /// A variant with unnamed fields.
348 /// Unlike most of json, `#[doc(hidden)]` fields will be given as `None`
349 /// instead of being ommited, because order matters.
353 /// TupleVariant(i32),
354 /// EmptyTupleVariant(),
357 Tuple(Vec<Option<Id>>),
358 /// A variant with named fields.
362 /// StructVariant { x: i32 },
363 /// EmptyStructVariant {},
366 Struct { fields: Vec<Id>, fields_stripped: bool },
369 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
370 pub struct Discriminant {
371 /// The expression that produced the discriminant.
373 /// Unlike `value`, this preserves the original formatting (eg suffixes,
374 /// hexadecimal, and underscores), making it unsuitable to be machine
377 /// In some cases, when the value is to complex, this may be `"{ _ }"`.
378 /// When this occurs is unstable, and may change without notice.
380 /// The numerical value of the discriminant. Stored as a string due to
381 /// JSON's poor support for large integers, and the fact that it would need
382 /// to store from [`i128::MIN`] to [`u128::MAX`].
386 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
388 #[serde(rename = "const")]
390 #[serde(rename = "unsafe")]
392 #[serde(rename = "async")]
397 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
399 // We only have a concrete listing here for stable ABI's because their are so many
400 // See rustc_ast_passes::feature_gate::PostExpansionVisitor::check_abi for the list
403 Cdecl { unwind: bool },
404 Stdcall { unwind: bool },
405 Fastcall { unwind: bool },
406 Aapcs { unwind: bool },
407 Win64 { unwind: bool },
408 SysV64 { unwind: bool },
409 System { unwind: bool },
413 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
414 pub struct Function {
416 pub generics: Generics,
420 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
423 pub generics: Generics,
428 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
429 pub struct Generics {
430 pub params: Vec<GenericParamDef>,
431 pub where_predicates: Vec<WherePredicate>,
434 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
435 pub struct GenericParamDef {
437 pub kind: GenericParamDefKind,
440 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
441 #[serde(rename_all = "snake_case")]
442 pub enum GenericParamDefKind {
444 outlives: Vec<String>,
447 bounds: Vec<GenericBound>,
448 default: Option<Type>,
449 /// This is normally `false`, which means that this generic parameter is
450 /// declared in the Rust source text.
452 /// If it is `true`, this generic parameter has been introduced by the
453 /// compiler behind the scenes.
459 /// ```ignore (pseudo-rust)
460 /// pub fn f(_: impl Trait) {}
463 /// The compiler will transform this behind the scenes to
465 /// ```ignore (pseudo-rust)
466 /// pub fn f<impl Trait: Trait>(_: impl Trait) {}
469 /// In this example, the generic parameter named `impl Trait` (and which
470 /// is bound by `Trait`) is synthetic, because it was not originally in
471 /// the Rust source text.
475 #[serde(rename = "type")]
477 default: Option<String>,
481 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
482 #[serde(rename_all = "snake_case")]
483 pub enum WherePredicate {
485 #[serde(rename = "type")]
487 bounds: Vec<GenericBound>,
488 /// Used for Higher-Rank Trait Bounds (HRTBs)
490 /// where for<'a> &'a T: Iterator,"
495 generic_params: Vec<GenericParamDef>,
499 bounds: Vec<GenericBound>,
507 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
508 #[serde(rename_all = "snake_case")]
509 pub enum GenericBound {
511 #[serde(rename = "trait")]
513 /// Used for Higher-Rank Trait Bounds (HRTBs)
515 /// where F: for<'a, 'b> Fn(&'a u8, &'b u8)
520 generic_params: Vec<GenericParamDef>,
521 modifier: TraitBoundModifier,
526 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
527 #[serde(rename_all = "snake_case")]
528 pub enum TraitBoundModifier {
534 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
535 #[serde(rename_all = "snake_case")]
541 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
542 #[serde(rename_all = "snake_case")]
543 #[serde(tag = "kind", content = "inner")]
545 /// Structs, enums, and unions
548 /// Parameterized types
550 /// Built in numberic (i*, u*, f*) types, bool, and char
552 /// `extern "ABI" fn`
553 FunctionPointer(Box<FunctionPointer>),
554 /// `(String, u32, Box<usize>)`
560 #[serde(rename = "type")]
564 /// `impl TraitA + TraitB + ...`
565 ImplTrait(Vec<GenericBound>),
568 /// `*mut u32`, `*u8`, etc.
571 #[serde(rename = "type")]
574 /// `&'a mut String`, `&str`, etc.
576 lifetime: Option<String>,
578 #[serde(rename = "type")]
581 /// `<Type as Trait>::Name` or associated types like `T::Item` where `T: Iterator`
584 args: Box<GenericArgs>,
585 self_type: Box<Type>,
586 #[serde(rename = "trait")]
591 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
595 /// Generic arguments to the type
597 /// std::borrow::Cow<'static, str>
602 pub args: Option<Box<GenericArgs>>,
605 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
606 pub struct FunctionPointer {
608 /// Used for Higher-Rank Trait Bounds (HRTBs)
610 /// for<'c> fn(val: &'c i32) -> i32
615 pub generic_params: Vec<GenericParamDef>,
619 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
621 pub inputs: Vec<(String, Type)>,
622 pub output: Option<Type>,
623 pub c_variadic: bool,
626 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
631 pub generics: Generics,
632 pub bounds: Vec<GenericBound>,
633 pub implementations: Vec<Id>,
636 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
637 pub struct TraitAlias {
638 pub generics: Generics,
639 pub params: Vec<GenericBound>,
642 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
645 pub generics: Generics,
646 pub provided_trait_methods: Vec<String>,
647 #[serde(rename = "trait")]
648 pub trait_: Option<Path>,
649 #[serde(rename = "for")]
654 pub blanket_impl: Option<Type>,
657 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
658 #[serde(rename_all = "snake_case")]
660 /// The full path being imported.
662 /// May be different from the last segment of `source` when renaming imports:
663 /// `use source as name;`
665 /// The ID of the item being imported. Will be `None` in case of re-exports of primitives:
667 /// pub use i32 as my_i32;
670 /// Whether this import uses a glob: `use source::*;`
674 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
675 pub struct ProcMacro {
677 pub helpers: Vec<String>,
680 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
681 #[serde(rename_all = "snake_case")]
683 /// A bang macro `foo!()`.
685 /// An attribute macro `#[foo]`.
687 /// A derive macro `#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]`
691 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
693 #[serde(rename = "type")]
695 pub generics: Generics,
698 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
699 pub struct OpaqueTy {
700 pub bounds: Vec<GenericBound>,
701 pub generics: Generics,
704 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
706 #[serde(rename = "type")]