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 /// A `Crate` is the root of the emitted JSON blob. It contains all type/documentation information
12 /// about the language items in the local crate, as well as info about external items to allow
13 /// tools to find or link to them.
14 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
16 /// The id of the root [`Module`] item of the local crate.
18 /// The version string given to `--crate-version`, if any.
19 pub crate_version: Option<String>,
20 /// Whether or not the output includes private items.
21 pub includes_private: bool,
22 /// A collection of all items in the local crate as well as some external traits and their
23 /// items that are referenced locally.
24 pub index: HashMap<Id, Item>,
25 /// Maps IDs to fully qualified paths and other info helpful for generating links.
26 pub paths: HashMap<Id, ItemSummary>,
27 /// Maps `crate_id` of items to a crate name and html_root_url if it exists.
28 pub external_crates: HashMap<u32, ExternalCrate>,
29 /// A single version number to be used in the future when making backwards incompatible changes
30 /// to the JSON output.
31 pub format_version: u32,
34 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
35 pub struct ExternalCrate {
37 pub html_root_url: Option<String>,
40 /// For external (not defined in the local crate) items, you don't get the same level of
41 /// information. This struct should contain enough to generate a link/reference to the item in
42 /// question, or can be used by a tool that takes the json output of multiple crates to find
43 /// the actual item definition with all the relevant info.
44 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
45 pub struct ItemSummary {
46 /// Can be used to look up the name and html_root_url of the crate this item came from in the
47 /// `external_crates` map.
49 /// The list of path components for the fully qualified path of this item (e.g.
50 /// `["std", "io", "lazy", "Lazy"]` for `std::io::lazy::Lazy`).
51 pub path: Vec<String>,
52 /// Whether this item is a struct, trait, macro, etc.
56 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
58 /// The unique identifier of this item. Can be used to find this item in various mappings.
60 /// This can be used as a key to the `external_crates` map of [`Crate`] to see which crate
61 /// this item came from.
63 /// Some items such as impls don't have names.
64 pub name: Option<String>,
65 /// The source location of this item (absent if it came from a macro expansion or inline
67 pub span: Option<Span>,
68 /// By default all documented items are public, but you can tell rustdoc to output private items
69 /// so this field is needed to differentiate.
70 pub visibility: Visibility,
71 /// The full markdown docstring of this item. Absent if there is no documentation at all,
72 /// Some("") if there is some documentation but it is empty (EG `#[doc = ""]`).
73 pub docs: Option<String>,
74 /// 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
75 pub links: HashMap<String, Id>,
76 /// Stringified versions of the attributes on this item (e.g. `"#[inline]"`)
77 pub attrs: Vec<String>,
78 pub deprecation: Option<Deprecation>,
83 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
85 /// The path to the source file for this span relative to the path `rustdoc` was invoked with.
86 pub filename: PathBuf,
87 /// Zero indexed Line and Column of the first character of the `Span`
88 pub begin: (usize, usize),
89 /// Zero indexed Line and Column of the last character of the `Span`
90 pub end: (usize, usize),
93 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
94 pub struct Deprecation {
95 pub since: Option<String>,
96 pub note: Option<String>,
99 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
100 #[serde(rename_all = "snake_case")]
101 pub enum Visibility {
103 /// For the most part items are private by default. The exceptions are associated items of
104 /// public traits and variants of public enums.
107 /// For `pub(in path)` visibility. `parent` is the module it's restricted to and `path` is how
108 /// that module was referenced (like `"super::super"` or `"crate::foo::bar"`).
115 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
116 #[serde(rename_all = "snake_case")]
117 pub enum GenericArgs {
118 /// <'a, 32, B: Copy, C = u32>
119 AngleBracketed { args: Vec<GenericArg>, bindings: Vec<TypeBinding> },
121 Parenthesized { inputs: Vec<Type>, output: Option<Type> },
124 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
125 #[serde(rename_all = "snake_case")]
126 pub enum GenericArg {
133 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
134 pub struct Constant {
135 #[serde(rename = "type")]
138 pub value: Option<String>,
139 pub is_literal: bool,
142 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
143 pub struct TypeBinding {
145 pub binding: TypeBindingKind,
148 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
149 #[serde(rename_all = "snake_case")]
150 pub enum TypeBindingKind {
152 Constraint(Vec<GenericBound>),
155 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
156 pub struct Id(pub String);
158 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
159 #[serde(rename_all = "snake_case")]
188 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
189 #[serde(tag = "kind", content = "inner", rename_all = "snake_case")]
194 rename: Option<String>,
207 TraitAlias(TraitAlias),
217 /// `type`s from an extern block
220 /// Declarative macro_rules! macro
222 ProcMacro(ProcMacro),
224 PrimitiveType(String),
227 #[serde(rename = "type")]
229 /// e.g. `const X: usize = 5;`
230 default: Option<String>,
233 bounds: Vec<GenericBound>,
234 /// e.g. `type X = usize;`
235 default: Option<Type>,
239 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
245 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
247 pub generics: Generics,
248 pub fields_stripped: bool,
253 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
255 pub struct_type: StructType,
256 pub generics: Generics,
257 pub fields_stripped: bool,
262 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
264 pub generics: Generics,
265 pub variants_stripped: bool,
266 pub variants: Vec<Id>,
270 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
271 #[serde(rename_all = "snake_case")]
272 #[serde(tag = "variant_kind", content = "variant_inner")]
279 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
280 #[serde(rename_all = "snake_case")]
281 pub enum StructType {
288 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
289 #[serde(rename_all = "snake_case")]
290 pub enum Qualifiers {
296 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
297 pub struct Function {
299 pub generics: Generics,
300 pub header: HashSet<Qualifiers>,
304 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
307 pub generics: Generics,
308 pub header: HashSet<Qualifiers>,
313 #[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
314 pub struct Generics {
315 pub params: Vec<GenericParamDef>,
316 pub where_predicates: Vec<WherePredicate>,
319 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
320 pub struct GenericParamDef {
322 pub kind: GenericParamDefKind,
325 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
326 #[serde(rename_all = "snake_case")]
327 pub enum GenericParamDefKind {
328 Lifetime { outlives: Vec<String> },
329 Type { bounds: Vec<GenericBound>, default: Option<Type> },
330 Const { ty: Type, default: Option<String> },
333 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
334 #[serde(rename_all = "snake_case")]
335 pub enum WherePredicate {
336 BoundPredicate { ty: Type, bounds: Vec<GenericBound> },
337 RegionPredicate { lifetime: String, bounds: Vec<GenericBound> },
338 EqPredicate { lhs: Type, rhs: Type },
341 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
342 #[serde(rename_all = "snake_case")]
343 pub enum GenericBound {
345 #[serde(rename = "trait")]
348 generic_params: Vec<GenericParamDef>,
349 modifier: TraitBoundModifier,
354 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
355 #[serde(rename_all = "snake_case")]
356 pub enum TraitBoundModifier {
362 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
363 #[serde(rename_all = "snake_case")]
364 #[serde(tag = "kind", content = "inner")]
366 /// Structs, enums, and traits
370 args: Option<Box<GenericArgs>>,
371 param_names: Vec<GenericBound>,
373 /// Parameterized types
375 /// Fixed-size numeric types (plus int/usize/float), char, arrays, slices, and tuples
377 /// `extern "ABI" fn`
378 FunctionPointer(Box<FunctionPointer>),
379 /// `(String, u32, Box<usize>)`
385 #[serde(rename = "type")]
389 /// `impl TraitA + TraitB + ...`
390 ImplTrait(Vec<GenericBound>),
395 /// `*mut u32`, `*u8`, etc.
398 #[serde(rename = "type")]
401 /// `&'a mut String`, `&str`, etc.
403 lifetime: Option<String>,
405 #[serde(rename = "type")]
408 /// `<Type as Trait>::Name` or associated types like `T::Item` where `T: Iterator`
411 self_type: Box<Type>,
412 #[serde(rename = "trait")]
417 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
418 pub struct FunctionPointer {
420 pub generic_params: Vec<GenericParamDef>,
421 pub header: HashSet<Qualifiers>,
425 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
427 pub inputs: Vec<(String, Type)>,
428 pub output: Option<Type>,
429 pub c_variadic: bool,
432 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
437 pub generics: Generics,
438 pub bounds: Vec<GenericBound>,
439 pub implementors: Vec<Id>,
442 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
443 pub struct TraitAlias {
444 pub generics: Generics,
445 pub params: Vec<GenericBound>,
448 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
451 pub generics: Generics,
452 pub provided_trait_methods: Vec<String>,
453 #[serde(rename = "trait")]
454 pub trait_: Option<Type>,
455 #[serde(rename = "for")]
460 pub blanket_impl: Option<Type>,
463 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
464 #[serde(rename_all = "snake_case")]
466 /// The full path being imported.
468 /// May be different from the last segment of `source` when renaming imports:
469 /// `use source as name;`
471 /// The ID of the item being imported.
472 pub id: Option<Id>, // FIXME is this actually ever None?
473 /// Whether this import uses a glob: `use source::*;`
477 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
478 pub struct ProcMacro {
480 pub helpers: Vec<String>,
483 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
484 #[serde(rename_all = "snake_case")]
486 /// A bang macro `foo!()`.
488 /// An attribute macro `#[foo]`.
490 /// A derive macro `#[derive(Foo)]`
494 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
496 #[serde(rename = "type")]
498 pub generics: Generics,
501 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
502 pub struct OpaqueTy {
503 pub bounds: Vec<GenericBound>,
504 pub generics: Generics,
507 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
509 #[serde(rename = "type")]