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