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 = 22;
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`).
55 /// Note that items can appear in multiple paths, and the one chosen is implementation
56 /// defined. Currenty, this is the full path to where the item was defined. Eg
57 /// [`String`] is currently `["alloc", "string", "String"]` and [`HashMap`] is
58 /// `["std", "collections", "hash", "map", "HashMap"]`, but this is subject to change.
59 pub path: Vec<String>,
60 /// Whether this item is a struct, trait, macro, etc.
64 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
66 /// The unique identifier of this item. Can be used to find this item in various mappings.
68 /// This can be used as a key to the `external_crates` map of [`Crate`] to see which crate
69 /// this item came from.
71 /// Some items such as impls don't have names.
72 pub name: Option<String>,
73 /// The source location of this item (absent if it came from a macro expansion or inline
75 pub span: Option<Span>,
76 /// By default all documented items are public, but you can tell rustdoc to output private items
77 /// so this field is needed to differentiate.
78 pub visibility: Visibility,
79 /// The full markdown docstring of this item. Absent if there is no documentation at all,
80 /// Some("") if there is some documentation but it is empty (EG `#[doc = ""]`).
81 pub docs: Option<String>,
82 /// 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
83 pub links: HashMap<String, Id>,
84 /// Stringified versions of the attributes on this item (e.g. `"#[inline]"`)
85 pub attrs: Vec<String>,
86 pub deprecation: Option<Deprecation>,
91 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
93 /// The path to the source file for this span relative to the path `rustdoc` was invoked with.
94 pub filename: PathBuf,
95 /// Zero indexed Line and Column of the first character of the `Span`
96 pub begin: (usize, usize),
97 /// Zero indexed Line and Column of the last character of the `Span`
98 pub end: (usize, usize),
101 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
102 pub struct Deprecation {
103 pub since: Option<String>,
104 pub note: Option<String>,
107 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
108 #[serde(rename_all = "snake_case")]
109 pub enum Visibility {
111 /// For the most part items are private by default. The exceptions are associated items of
112 /// public traits and variants of public enums.
115 /// For `pub(in path)` visibility. `parent` is the module it's restricted to and `path` is how
116 /// that module was referenced (like `"super::super"` or `"crate::foo::bar"`).
123 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
124 pub struct DynTrait {
125 /// All the traits implemented. One of them is the vtable, and the rest must be auto traits.
126 pub traits: Vec<PolyTrait>,
127 /// The lifetime of the whole dyn object
129 /// dyn Debug + 'static
134 pub lifetime: Option<String>,
137 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
138 /// A trait and potential HRTBs
139 pub struct PolyTrait {
140 #[serde(rename = "trait")]
142 /// Used for Higher-Rank Trait Bounds (HRTBs)
144 /// dyn for<'a> Fn() -> &'a i32"
149 pub generic_params: Vec<GenericParamDef>,
152 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
153 #[serde(rename_all = "snake_case")]
154 pub enum GenericArgs {
155 /// <'a, 32, B: Copy, C = u32>
156 AngleBracketed { args: Vec<GenericArg>, bindings: Vec<TypeBinding> },
158 Parenthesized { inputs: Vec<Type>, output: Option<Type> },
161 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
162 #[serde(rename_all = "snake_case")]
163 pub enum GenericArg {
170 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
171 pub struct Constant {
172 #[serde(rename = "type")]
175 pub value: Option<String>,
176 pub is_literal: bool,
179 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
180 pub struct TypeBinding {
182 pub args: GenericArgs,
183 pub binding: TypeBindingKind,
186 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
187 #[serde(rename_all = "snake_case")]
188 pub enum TypeBindingKind {
190 Constraint(Vec<GenericBound>),
193 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
194 pub struct Id(pub String);
196 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
197 #[serde(rename_all = "snake_case")]
226 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
227 #[serde(tag = "kind", content = "inner", rename_all = "snake_case")]
232 rename: Option<String>,
245 TraitAlias(TraitAlias),
255 /// `type`s from an extern block
258 /// Declarative macro_rules! macro
260 ProcMacro(ProcMacro),
262 Primitive(Primitive),
265 #[serde(rename = "type")]
267 /// e.g. `const X: usize = 5;`
268 default: Option<String>,
272 bounds: Vec<GenericBound>,
273 /// e.g. `type X = usize;`
274 default: Option<Type>,
278 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
282 /// If `true`, this module is not part of the public API, but it contains
283 /// items that are re-exported as public API.
284 pub is_stripped: bool,
287 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
289 pub generics: Generics,
290 pub fields_stripped: bool,
295 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
297 pub kind: StructKind,
298 pub generics: Generics,
302 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
303 #[serde(rename_all = "snake_case")]
304 pub enum StructKind {
305 /// A struct with no fields and no parentheses.
311 /// A struct with unnamed fields.
314 /// pub struct TupleStruct(i32);
315 /// pub struct EmptyTupleStruct();
318 /// All [`Id`]'s will point to [`ItemEnum::StructField`]. Private and
319 /// `#[doc(hidden)]` fields will be given as `None`
320 Tuple(Vec<Option<Id>>),
321 /// A struct with nammed fields.
324 /// pub struct PlainStruct { x: i32 }
325 /// pub struct EmptyPlainStruct {}
327 Plain { fields: Vec<Id>, fields_stripped: bool },
330 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
332 pub generics: Generics,
333 pub variants_stripped: bool,
334 pub variants: Vec<Id>,
338 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
339 #[serde(rename_all = "snake_case")]
340 #[serde(tag = "variant_kind", content = "variant_inner")]
342 /// A variant with no parentheses, and possible discriminant.
347 /// PlainWithDiscriminant = 1,
350 Plain(Option<Discriminant>),
351 /// A variant with unnamed fields.
353 /// Unlike most of json, `#[doc(hidden)]` fields will be given as `None`
354 /// instead of being ommited, because order matters.
358 /// TupleVariant(i32),
359 /// EmptyTupleVariant(),
362 Tuple(Vec<Option<Id>>),
363 /// A variant with named fields.
367 /// StructVariant { x: i32 },
368 /// EmptyStructVariant {},
371 Struct { fields: Vec<Id>, fields_stripped: bool },
374 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
375 pub struct Discriminant {
376 /// The expression that produced the discriminant.
378 /// Unlike `value`, this preserves the original formatting (eg suffixes,
379 /// hexadecimal, and underscores), making it unsuitable to be machine
382 /// In some cases, when the value is to complex, this may be `"{ _ }"`.
383 /// When this occurs is unstable, and may change without notice.
385 /// The numerical value of the discriminant. Stored as a string due to
386 /// JSON's poor support for large integers, and the fact that it would need
387 /// to store from [`i128::MIN`] to [`u128::MAX`].
391 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
393 #[serde(rename = "const")]
395 #[serde(rename = "unsafe")]
397 #[serde(rename = "async")]
402 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
404 // We only have a concrete listing here for stable ABI's because their are so many
405 // See rustc_ast_passes::feature_gate::PostExpansionVisitor::check_abi for the list
408 Cdecl { unwind: bool },
409 Stdcall { unwind: bool },
410 Fastcall { unwind: bool },
411 Aapcs { unwind: bool },
412 Win64 { unwind: bool },
413 SysV64 { unwind: bool },
414 System { unwind: bool },
418 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
419 pub struct Function {
421 pub generics: Generics,
425 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
428 pub generics: Generics,
433 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
434 pub struct Generics {
435 pub params: Vec<GenericParamDef>,
436 pub where_predicates: Vec<WherePredicate>,
439 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
440 pub struct GenericParamDef {
442 pub kind: GenericParamDefKind,
445 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
446 #[serde(rename_all = "snake_case")]
447 pub enum GenericParamDefKind {
449 outlives: Vec<String>,
452 bounds: Vec<GenericBound>,
453 default: Option<Type>,
454 /// This is normally `false`, which means that this generic parameter is
455 /// declared in the Rust source text.
457 /// If it is `true`, this generic parameter has been introduced by the
458 /// compiler behind the scenes.
464 /// ```ignore (pseudo-rust)
465 /// pub fn f(_: impl Trait) {}
468 /// The compiler will transform this behind the scenes to
470 /// ```ignore (pseudo-rust)
471 /// pub fn f<impl Trait: Trait>(_: impl Trait) {}
474 /// In this example, the generic parameter named `impl Trait` (and which
475 /// is bound by `Trait`) is synthetic, because it was not originally in
476 /// the Rust source text.
480 #[serde(rename = "type")]
482 default: Option<String>,
486 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
487 #[serde(rename_all = "snake_case")]
488 pub enum WherePredicate {
490 #[serde(rename = "type")]
492 bounds: Vec<GenericBound>,
493 /// Used for Higher-Rank Trait Bounds (HRTBs)
495 /// where for<'a> &'a T: Iterator,"
500 generic_params: Vec<GenericParamDef>,
504 bounds: Vec<GenericBound>,
512 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
513 #[serde(rename_all = "snake_case")]
514 pub enum GenericBound {
516 #[serde(rename = "trait")]
518 /// Used for Higher-Rank Trait Bounds (HRTBs)
520 /// where F: for<'a, 'b> Fn(&'a u8, &'b u8)
525 generic_params: Vec<GenericParamDef>,
526 modifier: TraitBoundModifier,
531 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
532 #[serde(rename_all = "snake_case")]
533 pub enum TraitBoundModifier {
539 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
540 #[serde(rename_all = "snake_case")]
546 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
547 #[serde(rename_all = "snake_case")]
548 #[serde(tag = "kind", content = "inner")]
550 /// Structs, enums, and unions
553 /// Parameterized types
555 /// Built in numberic (i*, u*, f*) types, bool, and char
557 /// `extern "ABI" fn`
558 FunctionPointer(Box<FunctionPointer>),
559 /// `(String, u32, Box<usize>)`
565 #[serde(rename = "type")]
569 /// `impl TraitA + TraitB + ...`
570 ImplTrait(Vec<GenericBound>),
573 /// `*mut u32`, `*u8`, etc.
576 #[serde(rename = "type")]
579 /// `&'a mut String`, `&str`, etc.
581 lifetime: Option<String>,
583 #[serde(rename = "type")]
586 /// `<Type as Trait>::Name` or associated types like `T::Item` where `T: Iterator`
589 args: Box<GenericArgs>,
590 self_type: Box<Type>,
591 #[serde(rename = "trait")]
596 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
600 /// Generic arguments to the type
602 /// std::borrow::Cow<'static, str>
607 pub args: Option<Box<GenericArgs>>,
610 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
611 pub struct FunctionPointer {
613 /// Used for Higher-Rank Trait Bounds (HRTBs)
615 /// for<'c> fn(val: &'c i32) -> i32
620 pub generic_params: Vec<GenericParamDef>,
624 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
626 pub inputs: Vec<(String, Type)>,
627 pub output: Option<Type>,
628 pub c_variadic: bool,
631 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
636 pub generics: Generics,
637 pub bounds: Vec<GenericBound>,
638 pub implementations: Vec<Id>,
641 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
642 pub struct TraitAlias {
643 pub generics: Generics,
644 pub params: Vec<GenericBound>,
647 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
650 pub generics: Generics,
651 pub provided_trait_methods: Vec<String>,
652 #[serde(rename = "trait")]
653 pub trait_: Option<Path>,
654 #[serde(rename = "for")]
659 pub blanket_impl: Option<Type>,
662 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
663 #[serde(rename_all = "snake_case")]
665 /// The full path being imported.
667 /// May be different from the last segment of `source` when renaming imports:
668 /// `use source as name;`
670 /// The ID of the item being imported. Will be `None` in case of re-exports of primitives:
672 /// pub use i32 as my_i32;
675 /// Whether this import uses a glob: `use source::*;`
679 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
680 pub struct ProcMacro {
682 pub helpers: Vec<String>,
685 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
686 #[serde(rename_all = "snake_case")]
688 /// A bang macro `foo!()`.
690 /// An attribute macro `#[foo]`.
692 /// A derive macro `#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]`
696 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
698 #[serde(rename = "type")]
700 pub generics: Generics,
703 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
704 pub struct OpaqueTy {
705 pub bounds: Vec<GenericBound>,
706 pub generics: Generics,
709 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
711 #[serde(rename = "type")]
717 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
718 pub struct Primitive {