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(Term),
 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: Term },
 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 pub enum Term {
 365     Type(Type),
 366     Constant(Constant),
 367 }
 368
 369 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 370 #[serde(rename_all = "snake_case")]
 371 #[serde(tag = "kind", content = "inner")]
 372 pub enum Type {
 373     /// Structs, enums, and traits
 374     ResolvedPath {
 375         name: String,
 376         id: Id,
 377         args: Option<Box<GenericArgs>>,
 378         param_names: Vec<GenericBound>,
 379     },
 380     /// Parameterized types
 381     Generic(String),
 382     /// Fixed-size numeric types (plus int/usize/float), char, arrays, slices, and tuples
 383     Primitive(String),
 384     /// `extern "ABI" fn`
 385     FunctionPointer(Box<FunctionPointer>),
 386     /// `(String, u32, Box<usize>)`
 387     Tuple(Vec<Type>),
 388     /// `[u32]`
 389     Slice(Box<Type>),
 390     /// [u32; 15]
 391     Array {
 392         #[serde(rename = "type")]
 393         type_: Box<Type>,
 394         len: String,
 395     },
 396     /// `impl TraitA + TraitB + ...`
 397     ImplTrait(Vec<GenericBound>),
 398     /// `_`
 399     Infer,
 400     /// `*mut u32`, `*u8`, etc.
 401     RawPointer {
 402         mutable: bool,
 403         #[serde(rename = "type")]
 404         type_: Box<Type>,
 405     },
 406     /// `&'a mut String`, `&str`, etc.
 407     BorrowedRef {
 408         lifetime: Option<String>,
 409         mutable: bool,
 410         #[serde(rename = "type")]
 411         type_: Box<Type>,
 412     },
 413     /// `<Type as Trait>::Name` or associated types like `T::Item` where `T: Iterator`
 414     QualifiedPath {
 415         name: String,
 416         self_type: Box<Type>,
 417         #[serde(rename = "trait")]
 418         trait_: Box<Type>,
 419     },
 420 }
 421
 422 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 423 pub struct FunctionPointer {
 424     pub decl: FnDecl,
 425     pub generic_params: Vec<GenericParamDef>,
 426     pub header: HashSet<Qualifiers>,
 427     pub abi: String,
 428 }
 429
 430 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 431 pub struct FnDecl {
 432     pub inputs: Vec<(String, Type)>,
 433     pub output: Option<Type>,
 434     pub c_variadic: bool,
 435 }
 436
 437 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 438 pub struct Trait {
 439     pub is_auto: bool,
 440     pub is_unsafe: bool,
 441     pub items: Vec<Id>,
 442     pub generics: Generics,
 443     pub bounds: Vec<GenericBound>,
 444     pub implementors: Vec<Id>,
 445 }
 446
 447 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 448 pub struct TraitAlias {
 449     pub generics: Generics,
 450     pub params: Vec<GenericBound>,
 451 }
 452
 453 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 454 pub struct Impl {
 455     pub is_unsafe: bool,
 456     pub generics: Generics,
 457     pub provided_trait_methods: Vec<String>,
 458     #[serde(rename = "trait")]
 459     pub trait_: Option<Type>,
 460     #[serde(rename = "for")]
 461     pub for_: Type,
 462     pub items: Vec<Id>,
 463     pub negative: bool,
 464     pub synthetic: bool,
 465     pub blanket_impl: Option<Type>,
 466 }
 467
 468 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 469 #[serde(rename_all = "snake_case")]
 470 pub struct Import {
 471     /// The full path being imported.
 472     pub source: String,
 473     /// May be different from the last segment of `source` when renaming imports:
 474     /// `use source as name;`
 475     pub name: String,
 476     /// The ID of the item being imported.
 477     pub id: Option<Id>, // FIXME is this actually ever None?
 478     /// Whether this import uses a glob: `use source::*;`
 479     pub glob: bool,
 480 }
 481
 482 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 483 pub struct ProcMacro {
 484     pub kind: MacroKind,
 485     pub helpers: Vec<String>,
 486 }
 487
 488 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 489 #[serde(rename_all = "snake_case")]
 490 pub enum MacroKind {
 491     /// A bang macro `foo!()`.
 492     Bang,
 493     /// An attribute macro `#[foo]`.
 494     Attr,
 495     /// A derive macro `#[derive(Foo)]`
 496     Derive,
 497 }
 498
 499 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 500 pub struct Typedef {
 501     #[serde(rename = "type")]
 502     pub type_: Type,
 503     pub generics: Generics,
 504 }
 505
 506 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 507 pub struct OpaqueTy {
 508     pub bounds: Vec<GenericBound>,
 509     pub generics: Generics,
 510 }
 511
 512 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 513 pub struct Static {
 514     #[serde(rename = "type")]
 515     pub type_: Type,
 516     pub mutable: bool,
 517     pub expr: String,
 518 }
 519
 520 /// rustdoc format-version.
 521 pub const FORMAT_VERSION: u32 = 9;
 522
 523 #[cfg(test)]
 524 mod tests;