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, HashSet};
   7 use std::path::PathBuf;
   8
   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: 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,
  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 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>,
  79     #[serde(flatten)]
  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 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 100 #[serde(rename_all = "snake_case")]
 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 #[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> },
 120     /// Fn(A, B) -> C
 121     Parenthesized { inputs: Vec<Type>, output: Option<Type> },
 122 }
 123
 124 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 125 #[serde(rename_all = "snake_case")]
 126 pub enum GenericArg {
 127     Lifetime(String),
 128     Type(Type),
 129     Const(Constant),
 130     Infer,
 131 }
 132
 133 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 134 pub struct Constant {
 135     #[serde(rename = "type")]
 136     pub type_: Type,
 137     pub expr: String,
 138     pub value: Option<String>,
 139     pub is_literal: bool,
 140 }
 141
 142 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 143 pub struct TypeBinding {
 144     pub name: String,
 145     pub binding: TypeBindingKind,
 146 }
 147
 148 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 149 #[serde(rename_all = "snake_case")]
 150 pub enum TypeBindingKind {
 151     Equality(Type),
 152     Constraint(Vec<GenericBound>),
 153 }
 154
 155 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 156 pub struct Id(pub String);
 157
 158 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 159 #[serde(rename_all = "snake_case")]
 160 pub enum ItemKind {
 161     Module,
 162     ExternCrate,
 163     Import,
 164     Struct,
 165     StructField,
 166     Union,
 167     Enum,
 168     Variant,
 169     Function,
 170     Typedef,
 171     OpaqueTy,
 172     Constant,
 173     Trait,
 174     TraitAlias,
 175     Method,
 176     Impl,
 177     Static,
 178     ForeignType,
 179     Macro,
 180     ProcAttribute,
 181     ProcDerive,
 182     AssocConst,
 183     AssocType,
 184     Primitive,
 185     Keyword,
 186 }
 187
 188 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 189 #[serde(tag = "kind", content = "inner", rename_all = "snake_case")]
 190 pub enum ItemEnum {
 191     Module(Module),
 192     ExternCrate {
 193         name: String,
 194         rename: Option<String>,
 195     },
 196     Import(Import),
 197
 198     Union(Union),
 199     Struct(Struct),
 200     StructField(Type),
 201     Enum(Enum),
 202     Variant(Variant),
 203
 204     Function(Function),
 205
 206     Trait(Trait),
 207     TraitAlias(TraitAlias),
 208     Method(Method),
 209     Impl(Impl),
 210
 211     Typedef(Typedef),
 212     OpaqueTy(OpaqueTy),
 213     Constant(Constant),
 214
 215     Static(Static),
 216
 217     /// `type`s from an extern block
 218     ForeignType,
 219
 220     /// Declarative macro_rules! macro
 221     Macro(String),
 222     ProcMacro(ProcMacro),
 223
 224     PrimitiveType(String),
 225
 226     AssocConst {
 227         #[serde(rename = "type")]
 228         type_: Type,
 229         /// e.g. `const X: usize = 5;`
 230         default: Option<String>,
 231     },
 232     AssocType {
 233         bounds: Vec<GenericBound>,
 234         /// e.g. `type X = usize;`
 235         default: Option<Type>,
 236     },
 237 }
 238
 239 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 240 pub struct Module {
 241     pub is_crate: bool,
 242     pub items: Vec<Id>,
 243 }
 244
 245 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 246 pub struct Union {
 247     pub generics: Generics,
 248     pub fields_stripped: bool,
 249     pub fields: Vec<Id>,
 250     pub impls: Vec<Id>,
 251 }
 252
 253 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 254 pub struct Struct {
 255     pub struct_type: StructType,
 256     pub generics: Generics,
 257     pub fields_stripped: bool,
 258     pub fields: Vec<Id>,
 259     pub impls: Vec<Id>,
 260 }
 261
 262 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 263 pub struct Enum {
 264     pub generics: Generics,
 265     pub variants_stripped: bool,
 266     pub variants: Vec<Id>,
 267     pub impls: Vec<Id>,
 268 }
 269
 270 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 271 #[serde(rename_all = "snake_case")]
 272 #[serde(tag = "variant_kind", content = "variant_inner")]
 273 pub enum Variant {
 274     Plain,
 275     Tuple(Vec<Type>),
 276     Struct(Vec<Id>),
 277 }
 278
 279 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 280 #[serde(rename_all = "snake_case")]
 281 pub enum StructType {
 282     Plain,
 283     Tuple,
 284     Unit,
 285 }
 286
 287 #[non_exhaustive]
 288 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
 289 #[serde(rename_all = "snake_case")]
 290 pub enum Qualifiers {
 291     Const,
 292     Unsafe,
 293     Async,
 294 }
 295
 296 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 297 pub struct Function {
 298     pub decl: FnDecl,
 299     pub generics: Generics,
 300     pub header: HashSet<Qualifiers>,
 301     pub abi: String,
 302 }
 303
 304 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 305 pub struct Method {
 306     pub decl: FnDecl,
 307     pub generics: Generics,
 308     pub header: HashSet<Qualifiers>,
 309     pub abi: String,
 310     pub has_body: bool,
 311 }
 312
 313 #[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
 314 pub struct Generics {
 315     pub params: Vec<GenericParamDef>,
 316     pub where_predicates: Vec<WherePredicate>,
 317 }
 318
 319 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 320 pub struct GenericParamDef {
 321     pub name: String,
 322     pub kind: GenericParamDefKind,
 323 }
 324
 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> },
 331 }
 332
 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 },
 339 }
 340
 341 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 342 #[serde(rename_all = "snake_case")]
 343 pub enum GenericBound {
 344     TraitBound {
 345         #[serde(rename = "trait")]
 346         trait_: Type,
 347         /// Used for HRTBs
 348         generic_params: Vec<GenericParamDef>,
 349         modifier: TraitBoundModifier,
 350     },
 351     Outlives(String),
 352 }
 353
 354 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 355 #[serde(rename_all = "snake_case")]
 356 pub enum TraitBoundModifier {
 357     None,
 358     Maybe,
 359     MaybeConst,
 360 }
 361
 362 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 363 #[serde(rename_all = "snake_case")]
 364 #[serde(tag = "kind", content = "inner")]
 365 pub enum Type {
 366     /// Structs, enums, and traits
 367     ResolvedPath {
 368         name: String,
 369         id: Id,
 370         args: Option<Box<GenericArgs>>,
 371         param_names: Vec<GenericBound>,
 372     },
 373     /// Parameterized types
 374     Generic(String),
 375     /// Fixed-size numeric types (plus int/usize/float), char, arrays, slices, and tuples
 376     Primitive(String),
 377     /// `extern "ABI" fn`
 378     FunctionPointer(Box<FunctionPointer>),
 379     /// `(String, u32, Box<usize>)`
 380     Tuple(Vec<Type>),
 381     /// `[u32]`
 382     Slice(Box<Type>),
 383     /// [u32; 15]
 384     Array {
 385         #[serde(rename = "type")]
 386         type_: Box<Type>,
 387         len: String,
 388     },
 389     /// `impl TraitA + TraitB + ...`
 390     ImplTrait(Vec<GenericBound>),
 391     /// `!`
 392     Never,
 393     /// `_`
 394     Infer,
 395     /// `*mut u32`, `*u8`, etc.
 396     RawPointer {
 397         mutable: bool,
 398         #[serde(rename = "type")]
 399         type_: Box<Type>,
 400     },
 401     /// `&'a mut String`, `&str`, etc.
 402     BorrowedRef {
 403         lifetime: Option<String>,
 404         mutable: bool,
 405         #[serde(rename = "type")]
 406         type_: Box<Type>,
 407     },
 408     /// `<Type as Trait>::Name` or associated types like `T::Item` where `T: Iterator`
 409     QualifiedPath {
 410         name: String,
 411         self_type: Box<Type>,
 412         #[serde(rename = "trait")]
 413         trait_: Box<Type>,
 414     },
 415 }
 416
 417 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 418 pub struct FunctionPointer {
 419     pub decl: FnDecl,
 420     pub generic_params: Vec<GenericParamDef>,
 421     pub header: HashSet<Qualifiers>,
 422     pub abi: String,
 423 }
 424
 425 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 426 pub struct FnDecl {
 427     pub inputs: Vec<(String, Type)>,
 428     pub output: Option<Type>,
 429     pub c_variadic: bool,
 430 }
 431
 432 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 433 pub struct Trait {
 434     pub is_auto: bool,
 435     pub is_unsafe: bool,
 436     pub items: Vec<Id>,
 437     pub generics: Generics,
 438     pub bounds: Vec<GenericBound>,
 439     pub implementors: Vec<Id>,
 440 }
 441
 442 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 443 pub struct TraitAlias {
 444     pub generics: Generics,
 445     pub params: Vec<GenericBound>,
 446 }
 447
 448 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 449 pub struct Impl {
 450     pub is_unsafe: bool,
 451     pub generics: Generics,
 452     pub provided_trait_methods: Vec<String>,
 453     #[serde(rename = "trait")]
 454     pub trait_: Option<Type>,
 455     #[serde(rename = "for")]
 456     pub for_: Type,
 457     pub items: Vec<Id>,
 458     pub negative: bool,
 459     pub synthetic: bool,
 460     pub blanket_impl: Option<Type>,
 461 }
 462
 463 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 464 #[serde(rename_all = "snake_case")]
 465 pub struct Import {
 466     /// The full path being imported.
 467     pub source: String,
 468     /// May be different from the last segment of `source` when renaming imports:
 469     /// `use source as name;`
 470     pub name: String,
 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::*;`
 474     pub glob: bool,
 475 }
 476
 477 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 478 pub struct ProcMacro {
 479     pub kind: MacroKind,
 480     pub helpers: Vec<String>,
 481 }
 482
 483 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 484 #[serde(rename_all = "snake_case")]
 485 pub enum MacroKind {
 486     /// A bang macro `foo!()`.
 487     Bang,
 488     /// An attribute macro `#[foo]`.
 489     Attr,
 490     /// A derive macro `#[derive(Foo)]`
 491     Derive,
 492 }
 493
 494 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 495 pub struct Typedef {
 496     #[serde(rename = "type")]
 497     pub type_: Type,
 498     pub generics: Generics,
 499 }
 500
 501 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 502 pub struct OpaqueTy {
 503     pub bounds: Vec<GenericBound>,
 504     pub generics: Generics,
 505 }
 506
 507 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 508 pub struct Static {
 509     #[serde(rename = "type")]
 510     pub type_: Type,
 511     pub mutable: bool,
 512     pub expr: String,
 513 }
 514
 515 #[cfg(test)]
 516 mod tests;