src/librustdoc/json/types.rs

   1 //! Rustdoc's JSON output interface
   2 //!
   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.
   5
   6 use std::path::PathBuf;
   7
   8 use rustc_data_structures::fx::FxHashMap;
   9 use serde::{Deserialize, Serialize};
  10
  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)]
  15 pub struct Crate {
  16     /// The id of the root [`Module`] item of the local crate.
  17     pub root: Id,
  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: FxHashMap<Id, Item>,
  25     /// Maps IDs to fully qualified paths and other info helpful for generating links.
  26     pub paths: FxHashMap<Id, ItemSummary>,
  27     /// Maps `crate_id` of items to a crate name and html_root_url if it exists.
  28     pub external_crates: FxHashMap<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,
  32 }
  33
  34 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
  35 pub struct ExternalCrate {
  36     pub name: String,
  37     pub html_root_url: Option<String>,
  38 }
  39
  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.
  48     pub crate_id: u32,
  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.
  53     pub kind: ItemKind,
  54 }
  55
  56 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
  57 pub struct Item {
  58     /// The unique identifier of this item. Can be used to find this item in various mappings.
  59     pub id: Id,
  60     /// This can be used as a key to the `external_crates` map of [`Crate`] to see which crate
  61     /// this item came from.
  62     pub crate_id: u32,
  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
  66     /// assembly).
  67     pub source: 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.
  72     pub docs: String,
  73     /// 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
  74     pub links: FxHashMap<String, Id>,
  75     /// Stringified versions of the attributes on this item (e.g. `"#[inline]"`)
  76     pub attrs: Vec<String>,
  77     pub deprecation: Option<Deprecation>,
  78     pub kind: ItemKind,
  79     pub inner: ItemEnum,
  80 }
  81
  82 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
  83 pub struct Span {
  84     /// The path to the source file for this span relative to the path `rustdoc` was invoked with.
  85     pub filename: PathBuf,
  86     /// Zero indexed Line and Column of the first character of the `Span`
  87     pub begin: (usize, usize),
  88     /// Zero indexed Line and Column of the last character of the `Span`
  89     pub end: (usize, usize),
  90 }
  91
  92 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
  93 pub struct Deprecation {
  94     pub since: Option<String>,
  95     pub note: Option<String>,
  96 }
  97
  98 #[serde(rename_all = "snake_case")]
  99 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 100 pub enum Visibility {
 101     Public,
 102     /// For the most part items are private by default. The exceptions are associated items of
 103     /// public traits and variants of public enums.
 104     Default,
 105     Crate,
 106     /// For `pub(in path)` visibility. `parent` is the module it's restricted to and `path` is how
 107     /// that module was referenced (like `"super::super"` or `"crate::foo::bar"`).
 108     Restricted {
 109         parent: Id,
 110         path: String,
 111     },
 112 }
 113
 114 #[serde(rename_all = "snake_case")]
 115 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 116 pub enum GenericArgs {
 117     /// <'a, 32, B: Copy, C = u32>
 118     AngleBracketed { args: Vec<GenericArg>, bindings: Vec<TypeBinding> },
 119     /// Fn(A, B) -> C
 120     Parenthesized { inputs: Vec<Type>, output: Option<Type> },
 121 }
 122
 123 #[serde(rename_all = "snake_case")]
 124 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 125 pub enum GenericArg {
 126     Lifetime(String),
 127     Type(Type),
 128     Const(Constant),
 129 }
 130
 131 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 132 pub struct Constant {
 133     #[serde(rename = "type")]
 134     pub type_: Type,
 135     pub expr: String,
 136     pub value: Option<String>,
 137     pub is_literal: bool,
 138 }
 139
 140 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 141 pub struct TypeBinding {
 142     pub name: String,
 143     pub binding: TypeBindingKind,
 144 }
 145
 146 #[serde(rename_all = "snake_case")]
 147 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 148 pub enum TypeBindingKind {
 149     Equality(Type),
 150     Constraint(Vec<GenericBound>),
 151 }
 152
 153 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 154 pub struct Id(pub String);
 155
 156 #[serde(rename_all = "snake_case")]
 157 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 158 pub enum ItemKind {
 159     Module,
 160     ExternCrate,
 161     Import,
 162     Struct,
 163     StructField,
 164     Union,
 165     Enum,
 166     Variant,
 167     Function,
 168     Typedef,
 169     OpaqueTy,
 170     Constant,
 171     Trait,
 172     TraitAlias,
 173     Method,
 174     Impl,
 175     Static,
 176     ForeignType,
 177     Macro,
 178     ProcAttribute,
 179     ProcDerive,
 180     AssocConst,
 181     AssocType,
 182     Primitive,
 183     Keyword,
 184 }
 185
 186 #[serde(untagged)]
 187 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 188 pub enum ItemEnum {
 189     ModuleItem(Module),
 190     ExternCrateItem {
 191         name: String,
 192         rename: Option<String>,
 193     },
 194     ImportItem(Import),
 195
 196     StructItem(Struct),
 197     StructFieldItem(Type),
 198     EnumItem(Enum),
 199     VariantItem(Variant),
 200
 201     FunctionItem(Function),
 202
 203     TraitItem(Trait),
 204     TraitAliasItem(TraitAlias),
 205     MethodItem(Method),
 206     ImplItem(Impl),
 207
 208     TypedefItem(Typedef),
 209     OpaqueTyItem(OpaqueTy),
 210     ConstantItem(Constant),
 211
 212     StaticItem(Static),
 213
 214     /// `type`s from an extern block
 215     ForeignTypeItem,
 216
 217     /// Declarative macro_rules! macro
 218     MacroItem(String),
 219     ProcMacroItem(ProcMacro),
 220
 221     AssocConstItem {
 222         #[serde(rename = "type")]
 223         type_: Type,
 224         /// e.g. `const X: usize = 5;`
 225         default: Option<String>,
 226     },
 227     AssocTypeItem {
 228         bounds: Vec<GenericBound>,
 229         /// e.g. `type X = usize;`
 230         default: Option<Type>,
 231     },
 232 }
 233
 234 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 235 pub struct Module {
 236     pub is_crate: bool,
 237     pub items: Vec<Id>,
 238 }
 239
 240 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 241 pub struct Struct {
 242     pub struct_type: StructType,
 243     pub generics: Generics,
 244     pub fields_stripped: bool,
 245     pub fields: Vec<Id>,
 246     pub impls: Vec<Id>,
 247 }
 248
 249 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 250 pub struct Enum {
 251     pub generics: Generics,
 252     pub variants_stripped: bool,
 253     pub variants: Vec<Id>,
 254     pub impls: Vec<Id>,
 255 }
 256
 257 #[serde(rename_all = "snake_case")]
 258 #[serde(tag = "variant_kind", content = "variant_inner")]
 259 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 260 pub enum Variant {
 261     Plain,
 262     Tuple(Vec<Type>),
 263     Struct(Vec<Id>),
 264 }
 265
 266 #[serde(rename_all = "snake_case")]
 267 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 268 pub enum StructType {
 269     Plain,
 270     Tuple,
 271     Unit,
 272 }
 273
 274 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 275 pub struct Function {
 276     pub decl: FnDecl,
 277     pub generics: Generics,
 278     pub header: String,
 279     pub abi: String,
 280 }
 281
 282 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 283 pub struct Method {
 284     pub decl: FnDecl,
 285     pub generics: Generics,
 286     pub header: String,
 287     pub has_body: bool,
 288 }
 289
 290 #[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
 291 pub struct Generics {
 292     pub params: Vec<GenericParamDef>,
 293     pub where_predicates: Vec<WherePredicate>,
 294 }
 295
 296 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 297 pub struct GenericParamDef {
 298     pub name: String,
 299     pub kind: GenericParamDefKind,
 300 }
 301
 302 #[serde(rename_all = "snake_case")]
 303 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 304 pub enum GenericParamDefKind {
 305     Lifetime,
 306     Type { bounds: Vec<GenericBound>, default: Option<Type> },
 307     Const(Type),
 308 }
 309
 310 #[serde(rename_all = "snake_case")]
 311 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 312 pub enum WherePredicate {
 313     BoundPredicate { ty: Type, bounds: Vec<GenericBound> },
 314     RegionPredicate { lifetime: String, bounds: Vec<GenericBound> },
 315     EqPredicate { lhs: Type, rhs: Type },
 316 }
 317
 318 #[serde(rename_all = "snake_case")]
 319 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 320 pub enum GenericBound {
 321     TraitBound {
 322         #[serde(rename = "trait")]
 323         trait_: Type,
 324         /// Used for HRTBs
 325         generic_params: Vec<GenericParamDef>,
 326         modifier: TraitBoundModifier,
 327     },
 328     Outlives(String),
 329 }
 330
 331 #[serde(rename_all = "snake_case")]
 332 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 333 pub enum TraitBoundModifier {
 334     None,
 335     Maybe,
 336     MaybeConst,
 337 }
 338
 339 #[serde(rename_all = "snake_case")]
 340 #[serde(tag = "kind", content = "inner")]
 341 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 342 pub enum Type {
 343     /// Structs, enums, and traits
 344     ResolvedPath {
 345         name: String,
 346         id: Id,
 347         args: Option<Box<GenericArgs>>,
 348         param_names: Vec<GenericBound>,
 349     },
 350     /// Parameterized types
 351     Generic(String),
 352     /// Fixed-size numeric types (plus int/usize/float), char, arrays, slices, and tuples
 353     Primitive(String),
 354     /// `extern "ABI" fn`
 355     FunctionPointer(Box<FunctionPointer>),
 356     /// `(String, u32, Box<usize>)`
 357     Tuple(Vec<Type>),
 358     /// `[u32]`
 359     Slice(Box<Type>),
 360     /// [u32; 15]
 361     Array {
 362         #[serde(rename = "type")]
 363         type_: Box<Type>,
 364         len: String,
 365     },
 366     /// `impl TraitA + TraitB + ...`
 367     ImplTrait(Vec<GenericBound>),
 368     /// `!`
 369     Never,
 370     /// `_`
 371     Infer,
 372     /// `*mut u32`, `*u8`, etc.
 373     RawPointer {
 374         mutable: bool,
 375         #[serde(rename = "type")]
 376         type_: Box<Type>,
 377     },
 378     /// `&'a mut String`, `&str`, etc.
 379     BorrowedRef {
 380         lifetime: Option<String>,
 381         mutable: bool,
 382         #[serde(rename = "type")]
 383         type_: Box<Type>,
 384     },
 385     /// `<Type as Trait>::Name` or associated types like `T::Item` where `T: Iterator`
 386     QualifiedPath {
 387         name: String,
 388         self_type: Box<Type>,
 389         #[serde(rename = "trait")]
 390         trait_: Box<Type>,
 391     },
 392 }
 393
 394 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 395 pub struct FunctionPointer {
 396     pub is_unsafe: bool,
 397     pub generic_params: Vec<GenericParamDef>,
 398     pub decl: FnDecl,
 399     pub abi: String,
 400 }
 401
 402 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 403 pub struct FnDecl {
 404     pub inputs: Vec<(String, Type)>,
 405     pub output: Option<Type>,
 406     pub c_variadic: bool,
 407 }
 408
 409 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 410 pub struct Trait {
 411     pub is_auto: bool,
 412     pub is_unsafe: bool,
 413     pub items: Vec<Id>,
 414     pub generics: Generics,
 415     pub bounds: Vec<GenericBound>,
 416     pub implementors: Vec<Id>,
 417 }
 418
 419 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 420 pub struct TraitAlias {
 421     pub generics: Generics,
 422     pub params: Vec<GenericBound>,
 423 }
 424
 425 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 426 pub struct Impl {
 427     pub is_unsafe: bool,
 428     pub generics: Generics,
 429     pub provided_trait_methods: Vec<String>,
 430     #[serde(rename = "trait")]
 431     pub trait_: Option<Type>,
 432     #[serde(rename = "for")]
 433     pub for_: Type,
 434     pub items: Vec<Id>,
 435     pub negative: bool,
 436     pub synthetic: bool,
 437     pub blanket_impl: Option<Type>,
 438 }
 439
 440 #[serde(rename_all = "snake_case")]
 441 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 442 pub struct Import {
 443     /// The full path being imported.
 444     pub span: String,
 445     /// May be different from the last segment of `source` when renaming imports:
 446     /// `use source as name;`
 447     pub name: String,
 448     /// The ID of the item being imported.
 449     pub id: Option<Id>, // FIXME is this actually ever None?
 450     /// Whether this import uses a glob: `use source::*;`
 451     pub glob: bool,
 452 }
 453
 454 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 455 pub struct ProcMacro {
 456     pub kind: MacroKind,
 457     pub helpers: Vec<String>,
 458 }
 459
 460 #[serde(rename_all = "snake_case")]
 461 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 462 pub enum MacroKind {
 463     /// A bang macro `foo!()`.
 464     Bang,
 465     /// An attribute macro `#[foo]`.
 466     Attr,
 467     /// A derive macro `#[derive(Foo)]`
 468     Derive,
 469 }
 470
 471 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 472 pub struct Typedef {
 473     #[serde(rename = "type")]
 474     pub type_: Type,
 475     pub generics: Generics,
 476 }
 477
 478 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 479 pub struct OpaqueTy {
 480     pub bounds: Vec<GenericBound>,
 481     pub generics: Generics,
 482 }
 483
 484 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 485 pub struct Static {
 486     #[serde(rename = "type")]
 487     pub type_: Type,
 488     pub mutable: bool,
 489     pub expr: String,
 490 }