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, HashSet};
7 use std::path::PathBuf;
9 use serde::{Deserialize, Serialize};
11 /// rustdoc format-version.
12 pub const FORMAT_VERSION: u32 = 10;
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, Serialize, Deserialize, PartialEq)]
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, Serialize, Deserialize, PartialEq)]
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, Serialize, Deserialize, PartialEq)]
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, Serialize, Deserialize, PartialEq)]
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, Serialize, Deserialize, PartialEq)]
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, Serialize, Deserialize, PartialEq)]
97 pub struct Deprecation {
98 pub since: Option<String>,
99 pub note: Option<String>,
102 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
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, Serialize, Deserialize, PartialEq)]
119 #[serde(rename_all = "snake_case")]
120 pub enum GenericArgs {
121 /// <'a, 32, B: Copy, C = u32>
122 AngleBracketed { args: Vec<GenericArg>, bindings: Vec<TypeBinding> },
124 Parenthesized { inputs: Vec<Type>, output: Option<Type> },
127 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
128 #[serde(rename_all = "snake_case")]
129 pub enum GenericArg {
136 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
137 pub struct Constant {
138 #[serde(rename = "type")]
141 pub value: Option<String>,
142 pub is_literal: bool,
145 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
146 pub struct TypeBinding {
148 pub binding: TypeBindingKind,
151 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
152 #[serde(rename_all = "snake_case")]
153 pub enum TypeBindingKind {
155 Constraint(Vec<GenericBound>),
158 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
159 pub struct Id(pub String);
161 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
162 #[serde(rename_all = "snake_case")]
191 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
192 #[serde(tag = "kind", content = "inner", rename_all = "snake_case")]
197 rename: Option<String>,
210 TraitAlias(TraitAlias),
220 /// `type`s from an extern block
223 /// Declarative macro_rules! macro
225 ProcMacro(ProcMacro),
227 PrimitiveType(String),
230 #[serde(rename = "type")]
232 /// e.g. `const X: usize = 5;`
233 default: Option<String>,
236 bounds: Vec<GenericBound>,
237 /// e.g. `type X = usize;`
238 default: Option<Type>,
242 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
248 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
250 pub generics: Generics,
251 pub fields_stripped: bool,
256 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
258 pub struct_type: StructType,
259 pub generics: Generics,
260 pub fields_stripped: bool,
265 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
267 pub generics: Generics,
268 pub variants_stripped: bool,
269 pub variants: Vec<Id>,
273 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
274 #[serde(rename_all = "snake_case")]
275 #[serde(tag = "variant_kind", content = "variant_inner")]
282 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
283 #[serde(rename_all = "snake_case")]
284 pub enum StructType {
291 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
292 #[serde(rename_all = "snake_case")]
293 pub enum Qualifiers {
299 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
300 pub struct Function {
302 pub generics: Generics,
303 pub header: HashSet<Qualifiers>,
307 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
310 pub generics: Generics,
311 pub header: HashSet<Qualifiers>,
316 #[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
317 pub struct Generics {
318 pub params: Vec<GenericParamDef>,
319 pub where_predicates: Vec<WherePredicate>,
322 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
323 pub struct GenericParamDef {
325 pub kind: GenericParamDefKind,
328 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
329 #[serde(rename_all = "snake_case")]
330 pub enum GenericParamDefKind {
331 Lifetime { outlives: Vec<String> },
332 Type { bounds: Vec<GenericBound>, default: Option<Type> },
333 Const { ty: Type, default: Option<String> },
336 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
337 #[serde(rename_all = "snake_case")]
338 pub enum WherePredicate {
339 BoundPredicate { ty: Type, bounds: Vec<GenericBound> },
340 RegionPredicate { lifetime: String, bounds: Vec<GenericBound> },
341 EqPredicate { lhs: Type, rhs: Term },
344 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
345 #[serde(rename_all = "snake_case")]
346 pub enum GenericBound {
348 #[serde(rename = "trait")]
351 generic_params: Vec<GenericParamDef>,
352 modifier: TraitBoundModifier,
357 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
358 #[serde(rename_all = "snake_case")]
359 pub enum TraitBoundModifier {
365 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
366 #[serde(rename_all = "snake_case")]
372 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
373 #[serde(rename_all = "snake_case")]
374 #[serde(tag = "kind", content = "inner")]
376 /// Structs, enums, and traits
380 args: Option<Box<GenericArgs>>,
381 param_names: Vec<GenericBound>,
383 /// Parameterized types
385 /// Fixed-size numeric types (plus int/usize/float), char, arrays, slices, and tuples
387 /// `extern "ABI" fn`
388 FunctionPointer(Box<FunctionPointer>),
389 /// `(String, u32, Box<usize>)`
395 #[serde(rename = "type")]
399 /// `impl TraitA + TraitB + ...`
400 ImplTrait(Vec<GenericBound>),
403 /// `*mut u32`, `*u8`, etc.
406 #[serde(rename = "type")]
409 /// `&'a mut String`, `&str`, etc.
411 lifetime: Option<String>,
413 #[serde(rename = "type")]
416 /// `<Type as Trait>::Name` or associated types like `T::Item` where `T: Iterator`
419 self_type: Box<Type>,
420 #[serde(rename = "trait")]
425 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
426 pub struct FunctionPointer {
428 pub generic_params: Vec<GenericParamDef>,
429 pub header: HashSet<Qualifiers>,
433 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
435 pub inputs: Vec<(String, Type)>,
436 pub output: Option<Type>,
437 pub c_variadic: bool,
440 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
445 pub generics: Generics,
446 pub bounds: Vec<GenericBound>,
447 pub implementors: Vec<Id>,
450 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
451 pub struct TraitAlias {
452 pub generics: Generics,
453 pub params: Vec<GenericBound>,
456 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
459 pub generics: Generics,
460 pub provided_trait_methods: Vec<String>,
461 #[serde(rename = "trait")]
462 pub trait_: Option<Type>,
463 #[serde(rename = "for")]
468 pub blanket_impl: Option<Type>,
471 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
472 #[serde(rename_all = "snake_case")]
474 /// The full path being imported.
476 /// May be different from the last segment of `source` when renaming imports:
477 /// `use source as name;`
479 /// The ID of the item being imported.
480 pub id: Option<Id>, // FIXME is this actually ever None?
481 /// Whether this import uses a glob: `use source::*;`
485 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
486 pub struct ProcMacro {
488 pub helpers: Vec<String>,
491 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
492 #[serde(rename_all = "snake_case")]
494 /// A bang macro `foo!()`.
496 /// An attribute macro `#[foo]`.
498 /// A derive macro `#[derive(Foo)]`
502 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
504 #[serde(rename = "type")]
506 pub generics: Generics,
509 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
510 pub struct OpaqueTy {
511 pub bounds: Vec<GenericBound>,
512 pub generics: Generics,
515 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
517 #[serde(rename = "type")]