src/rustdoc-json-types/lib.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::collections::HashMap;
   7 use std::path::PathBuf;
   8
   9 use serde::{Deserialize, Serialize};
  10
  11 /// rustdoc format-version.
  12 pub const FORMAT_VERSION: u32 = 11;
  13
  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)]
  18 pub struct Crate {
  19     /// The id of the root [`Module`] item of the local crate.
  20     pub root: Id,
  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,
  35 }
  36
  37 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
  38 pub struct ExternalCrate {
  39     pub name: String,
  40     pub html_root_url: Option<String>,
  41 }
  42
  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.
  51     pub crate_id: u32,
  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.
  56     pub kind: ItemKind,
  57 }
  58
  59 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
  60 pub struct Item {
  61     /// The unique identifier of this item. Can be used to find this item in various mappings.
  62     pub id: Id,
  63     /// This can be used as a key to the `external_crates` map of [`Crate`] to see which crate
  64     /// this item came from.
  65     pub crate_id: u32,
  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
  69     /// assembly).
  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>,
  82     #[serde(flatten)]
  83     pub inner: ItemEnum,
  84 }
  85
  86 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
  87 pub struct Span {
  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),
  94 }
  95
  96 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
  97 pub struct Deprecation {
  98     pub since: Option<String>,
  99     pub note: Option<String>,
 100 }
 101
 102 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 103 #[serde(rename_all = "snake_case")]
 104 pub enum Visibility {
 105     Public,
 106     /// For the most part items are private by default. The exceptions are associated items of
 107     /// public traits and variants of public enums.
 108     Default,
 109     Crate,
 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"`).
 112     Restricted {
 113         parent: Id,
 114         path: String,
 115     },
 116 }
 117
 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> },
 123     /// Fn(A, B) -> C
 124     Parenthesized { inputs: Vec<Type>, output: Option<Type> },
 125 }
 126
 127 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 128 #[serde(rename_all = "snake_case")]
 129 pub enum GenericArg {
 130     Lifetime(String),
 131     Type(Type),
 132     Const(Constant),
 133     Infer,
 134 }
 135
 136 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 137 pub struct Constant {
 138     #[serde(rename = "type")]
 139     pub type_: Type,
 140     pub expr: String,
 141     pub value: Option<String>,
 142     pub is_literal: bool,
 143 }
 144
 145 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 146 pub struct TypeBinding {
 147     pub name: String,
 148     pub binding: TypeBindingKind,
 149 }
 150
 151 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 152 #[serde(rename_all = "snake_case")]
 153 pub enum TypeBindingKind {
 154     Equality(Term),
 155     Constraint(Vec<GenericBound>),
 156 }
 157
 158 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 159 pub struct Id(pub String);
 160
 161 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 162 #[serde(rename_all = "snake_case")]
 163 pub enum ItemKind {
 164     Module,
 165     ExternCrate,
 166     Import,
 167     Struct,
 168     StructField,
 169     Union,
 170     Enum,
 171     Variant,
 172     Function,
 173     Typedef,
 174     OpaqueTy,
 175     Constant,
 176     Trait,
 177     TraitAlias,
 178     Method,
 179     Impl,
 180     Static,
 181     ForeignType,
 182     Macro,
 183     ProcAttribute,
 184     ProcDerive,
 185     AssocConst,
 186     AssocType,
 187     Primitive,
 188     Keyword,
 189 }
 190
 191 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 192 #[serde(tag = "kind", content = "inner", rename_all = "snake_case")]
 193 pub enum ItemEnum {
 194     Module(Module),
 195     ExternCrate {
 196         name: String,
 197         rename: Option<String>,
 198     },
 199     Import(Import),
 200
 201     Union(Union),
 202     Struct(Struct),
 203     StructField(Type),
 204     Enum(Enum),
 205     Variant(Variant),
 206
 207     Function(Function),
 208
 209     Trait(Trait),
 210     TraitAlias(TraitAlias),
 211     Method(Method),
 212     Impl(Impl),
 213
 214     Typedef(Typedef),
 215     OpaqueTy(OpaqueTy),
 216     Constant(Constant),
 217
 218     Static(Static),
 219
 220     /// `type`s from an extern block
 221     ForeignType,
 222
 223     /// Declarative macro_rules! macro
 224     Macro(String),
 225     ProcMacro(ProcMacro),
 226
 227     PrimitiveType(String),
 228
 229     AssocConst {
 230         #[serde(rename = "type")]
 231         type_: Type,
 232         /// e.g. `const X: usize = 5;`
 233         default: Option<String>,
 234     },
 235     AssocType {
 236         bounds: Vec<GenericBound>,
 237         /// e.g. `type X = usize;`
 238         default: Option<Type>,
 239     },
 240 }
 241
 242 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 243 pub struct Module {
 244     pub is_crate: bool,
 245     pub items: Vec<Id>,
 246 }
 247
 248 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 249 pub struct Union {
 250     pub generics: Generics,
 251     pub fields_stripped: bool,
 252     pub fields: Vec<Id>,
 253     pub impls: Vec<Id>,
 254 }
 255
 256 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 257 pub struct Struct {
 258     pub struct_type: StructType,
 259     pub generics: Generics,
 260     pub fields_stripped: bool,
 261     pub fields: Vec<Id>,
 262     pub impls: Vec<Id>,
 263 }
 264
 265 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 266 pub struct Enum {
 267     pub generics: Generics,
 268     pub variants_stripped: bool,
 269     pub variants: Vec<Id>,
 270     pub impls: Vec<Id>,
 271 }
 272
 273 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 274 #[serde(rename_all = "snake_case")]
 275 #[serde(tag = "variant_kind", content = "variant_inner")]
 276 pub enum Variant {
 277     Plain,
 278     Tuple(Vec<Type>),
 279     Struct(Vec<Id>),
 280 }
 281
 282 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 283 #[serde(rename_all = "snake_case")]
 284 pub enum StructType {
 285     Plain,
 286     Tuple,
 287     Unit,
 288 }
 289
 290 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
 291 pub struct Header {
 292     #[serde(rename = "const")]
 293     pub const_: bool,
 294     #[serde(rename = "unsafe")]
 295     pub unsafe_: bool,
 296     #[serde(rename = "async")]
 297     pub async_: bool,
 298     pub abi: Abi,
 299 }
 300
 301 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
 302 pub enum Abi {
 303     // We only have a concrete listing here for stable ABI's because their are so many
 304     // See rustc_ast_passes::feature_gate::PostExpansionVisitor::check_abi for the list
 305     Rust,
 306     C { unwind: bool },
 307     Cdecl { unwind: bool },
 308     Stdcall { unwind: bool },
 309     Fastcall { unwind: bool },
 310     Aapcs { unwind: bool },
 311     Win64 { unwind: bool },
 312     SysV64 { unwind: bool },
 313     System { unwind: bool },
 314     Other(String),
 315 }
 316
 317 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 318 pub struct Function {
 319     pub decl: FnDecl,
 320     pub generics: Generics,
 321     pub header: Header,
 322 }
 323
 324 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 325 pub struct Method {
 326     pub decl: FnDecl,
 327     pub generics: Generics,
 328     pub header: Header,
 329     pub has_body: bool,
 330 }
 331
 332 #[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
 333 pub struct Generics {
 334     pub params: Vec<GenericParamDef>,
 335     pub where_predicates: Vec<WherePredicate>,
 336 }
 337
 338 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 339 pub struct GenericParamDef {
 340     pub name: String,
 341     pub kind: GenericParamDefKind,
 342 }
 343
 344 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 345 #[serde(rename_all = "snake_case")]
 346 pub enum GenericParamDefKind {
 347     Lifetime { outlives: Vec<String> },
 348     Type { bounds: Vec<GenericBound>, default: Option<Type> },
 349     Const { ty: Type, default: Option<String> },
 350 }
 351
 352 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 353 #[serde(rename_all = "snake_case")]
 354 pub enum WherePredicate {
 355     BoundPredicate { ty: Type, bounds: Vec<GenericBound> },
 356     RegionPredicate { lifetime: String, bounds: Vec<GenericBound> },
 357     EqPredicate { lhs: Type, rhs: Term },
 358 }
 359
 360 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 361 #[serde(rename_all = "snake_case")]
 362 pub enum GenericBound {
 363     TraitBound {
 364         #[serde(rename = "trait")]
 365         trait_: Type,
 366         /// Used for HRTBs
 367         generic_params: Vec<GenericParamDef>,
 368         modifier: TraitBoundModifier,
 369     },
 370     Outlives(String),
 371 }
 372
 373 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 374 #[serde(rename_all = "snake_case")]
 375 pub enum TraitBoundModifier {
 376     None,
 377     Maybe,
 378     MaybeConst,
 379 }
 380
 381 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 382 #[serde(rename_all = "snake_case")]
 383 pub enum Term {
 384     Type(Type),
 385     Constant(Constant),
 386 }
 387
 388 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 389 #[serde(rename_all = "snake_case")]
 390 #[serde(tag = "kind", content = "inner")]
 391 pub enum Type {
 392     /// Structs, enums, and traits
 393     ResolvedPath {
 394         name: String,
 395         id: Id,
 396         args: Option<Box<GenericArgs>>,
 397         param_names: Vec<GenericBound>,
 398     },
 399     /// Parameterized types
 400     Generic(String),
 401     /// Fixed-size numeric types (plus int/usize/float), char, arrays, slices, and tuples
 402     Primitive(String),
 403     /// `extern "ABI" fn`
 404     FunctionPointer(Box<FunctionPointer>),
 405     /// `(String, u32, Box<usize>)`
 406     Tuple(Vec<Type>),
 407     /// `[u32]`
 408     Slice(Box<Type>),
 409     /// [u32; 15]
 410     Array {
 411         #[serde(rename = "type")]
 412         type_: Box<Type>,
 413         len: String,
 414     },
 415     /// `impl TraitA + TraitB + ...`
 416     ImplTrait(Vec<GenericBound>),
 417     /// `_`
 418     Infer,
 419     /// `*mut u32`, `*u8`, etc.
 420     RawPointer {
 421         mutable: bool,
 422         #[serde(rename = "type")]
 423         type_: Box<Type>,
 424     },
 425     /// `&'a mut String`, `&str`, etc.
 426     BorrowedRef {
 427         lifetime: Option<String>,
 428         mutable: bool,
 429         #[serde(rename = "type")]
 430         type_: Box<Type>,
 431     },
 432     /// `<Type as Trait>::Name` or associated types like `T::Item` where `T: Iterator`
 433     QualifiedPath {
 434         name: String,
 435         self_type: Box<Type>,
 436         #[serde(rename = "trait")]
 437         trait_: Box<Type>,
 438     },
 439 }
 440
 441 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 442 pub struct FunctionPointer {
 443     pub decl: FnDecl,
 444     pub generic_params: Vec<GenericParamDef>,
 445     pub header: Header,
 446 }
 447
 448 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 449 pub struct FnDecl {
 450     pub inputs: Vec<(String, Type)>,
 451     pub output: Option<Type>,
 452     pub c_variadic: bool,
 453 }
 454
 455 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 456 pub struct Trait {
 457     pub is_auto: bool,
 458     pub is_unsafe: bool,
 459     pub items: Vec<Id>,
 460     pub generics: Generics,
 461     pub bounds: Vec<GenericBound>,
 462     pub implementors: Vec<Id>,
 463 }
 464
 465 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 466 pub struct TraitAlias {
 467     pub generics: Generics,
 468     pub params: Vec<GenericBound>,
 469 }
 470
 471 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 472 pub struct Impl {
 473     pub is_unsafe: bool,
 474     pub generics: Generics,
 475     pub provided_trait_methods: Vec<String>,
 476     #[serde(rename = "trait")]
 477     pub trait_: Option<Type>,
 478     #[serde(rename = "for")]
 479     pub for_: Type,
 480     pub items: Vec<Id>,
 481     pub negative: bool,
 482     pub synthetic: bool,
 483     pub blanket_impl: Option<Type>,
 484 }
 485
 486 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 487 #[serde(rename_all = "snake_case")]
 488 pub struct Import {
 489     /// The full path being imported.
 490     pub source: String,
 491     /// May be different from the last segment of `source` when renaming imports:
 492     /// `use source as name;`
 493     pub name: String,
 494     /// The ID of the item being imported.
 495     pub id: Option<Id>, // FIXME is this actually ever None?
 496     /// Whether this import uses a glob: `use source::*;`
 497     pub glob: bool,
 498 }
 499
 500 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 501 pub struct ProcMacro {
 502     pub kind: MacroKind,
 503     pub helpers: Vec<String>,
 504 }
 505
 506 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 507 #[serde(rename_all = "snake_case")]
 508 pub enum MacroKind {
 509     /// A bang macro `foo!()`.
 510     Bang,
 511     /// An attribute macro `#[foo]`.
 512     Attr,
 513     /// A derive macro `#[derive(Foo)]`
 514     Derive,
 515 }
 516
 517 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 518 pub struct Typedef {
 519     #[serde(rename = "type")]
 520     pub type_: Type,
 521     pub generics: Generics,
 522 }
 523
 524 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 525 pub struct OpaqueTy {
 526     pub bounds: Vec<GenericBound>,
 527     pub generics: Generics,
 528 }
 529
 530 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 531 pub struct Static {
 532     #[serde(rename = "type")]
 533     pub type_: Type,
 534     pub mutable: bool,
 535     pub expr: String,
 536 }
 537
 538 #[cfg(test)]
 539 mod tests;