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     AssocConst {
 225         #[serde(rename = "type")]
 226         type_: Type,
 227         /// e.g. `const X: usize = 5;`
 228         default: Option<String>,
 229     },
 230     AssocType {
 231         bounds: Vec<GenericBound>,
 232         /// e.g. `type X = usize;`
 233         default: Option<Type>,
 234     },
 235 }
 236
 237 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 238 pub struct Module {
 239     pub is_crate: bool,
 240     pub items: Vec<Id>,
 241 }
 242
 243 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 244 pub struct Union {
 245     pub generics: Generics,
 246     pub fields_stripped: bool,
 247     pub fields: Vec<Id>,
 248     pub impls: Vec<Id>,
 249 }
 250
 251 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 252 pub struct Struct {
 253     pub struct_type: StructType,
 254     pub generics: Generics,
 255     pub fields_stripped: bool,
 256     pub fields: Vec<Id>,
 257     pub impls: Vec<Id>,
 258 }
 259
 260 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 261 pub struct Enum {
 262     pub generics: Generics,
 263     pub variants_stripped: bool,
 264     pub variants: Vec<Id>,
 265     pub impls: Vec<Id>,
 266 }
 267
 268 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 269 #[serde(rename_all = "snake_case")]
 270 #[serde(tag = "variant_kind", content = "variant_inner")]
 271 pub enum Variant {
 272     Plain,
 273     Tuple(Vec<Type>),
 274     Struct(Vec<Id>),
 275 }
 276
 277 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 278 #[serde(rename_all = "snake_case")]
 279 pub enum StructType {
 280     Plain,
 281     Tuple,
 282     Unit,
 283 }
 284
 285 #[non_exhaustive]
 286 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash)]
 287 #[serde(rename_all = "snake_case")]
 288 pub enum Qualifiers {
 289     Const,
 290     Unsafe,
 291     Async,
 292 }
 293
 294 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 295 pub struct Function {
 296     pub decl: FnDecl,
 297     pub generics: Generics,
 298     pub header: HashSet<Qualifiers>,
 299     pub abi: String,
 300 }
 301
 302 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 303 pub struct Method {
 304     pub decl: FnDecl,
 305     pub generics: Generics,
 306     pub header: HashSet<Qualifiers>,
 307     pub abi: String,
 308     pub has_body: bool,
 309 }
 310
 311 #[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
 312 pub struct Generics {
 313     pub params: Vec<GenericParamDef>,
 314     pub where_predicates: Vec<WherePredicate>,
 315 }
 316
 317 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 318 pub struct GenericParamDef {
 319     pub name: String,
 320     pub kind: GenericParamDefKind,
 321 }
 322
 323 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 324 #[serde(rename_all = "snake_case")]
 325 pub enum GenericParamDefKind {
 326     Lifetime { outlives: Vec<String> },
 327     Type { bounds: Vec<GenericBound>, default: Option<Type> },
 328     Const { ty: Type, default: Option<String> },
 329 }
 330
 331 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 332 #[serde(rename_all = "snake_case")]
 333 pub enum WherePredicate {
 334     BoundPredicate { ty: Type, bounds: Vec<GenericBound> },
 335     RegionPredicate { lifetime: String, bounds: Vec<GenericBound> },
 336     EqPredicate { lhs: Type, rhs: Type },
 337 }
 338
 339 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 340 #[serde(rename_all = "snake_case")]
 341 pub enum GenericBound {
 342     TraitBound {
 343         #[serde(rename = "trait")]
 344         trait_: Type,
 345         /// Used for HRTBs
 346         generic_params: Vec<GenericParamDef>,
 347         modifier: TraitBoundModifier,
 348     },
 349     Outlives(String),
 350 }
 351
 352 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 353 #[serde(rename_all = "snake_case")]
 354 pub enum TraitBoundModifier {
 355     None,
 356     Maybe,
 357     MaybeConst,
 358 }
 359
 360 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 361 #[serde(rename_all = "snake_case")]
 362 #[serde(tag = "kind", content = "inner")]
 363 pub enum Type {
 364     /// Structs, enums, and traits
 365     ResolvedPath {
 366         name: String,
 367         id: Id,
 368         args: Option<Box<GenericArgs>>,
 369         param_names: Vec<GenericBound>,
 370     },
 371     /// Parameterized types
 372     Generic(String),
 373     /// Fixed-size numeric types (plus int/usize/float), char, arrays, slices, and tuples
 374     Primitive(String),
 375     /// `extern "ABI" fn`
 376     FunctionPointer(Box<FunctionPointer>),
 377     /// `(String, u32, Box<usize>)`
 378     Tuple(Vec<Type>),
 379     /// `[u32]`
 380     Slice(Box<Type>),
 381     /// [u32; 15]
 382     Array {
 383         #[serde(rename = "type")]
 384         type_: Box<Type>,
 385         len: String,
 386     },
 387     /// `impl TraitA + TraitB + ...`
 388     ImplTrait(Vec<GenericBound>),
 389     /// `!`
 390     Never,
 391     /// `_`
 392     Infer,
 393     /// `*mut u32`, `*u8`, etc.
 394     RawPointer {
 395         mutable: bool,
 396         #[serde(rename = "type")]
 397         type_: Box<Type>,
 398     },
 399     /// `&'a mut String`, `&str`, etc.
 400     BorrowedRef {
 401         lifetime: Option<String>,
 402         mutable: bool,
 403         #[serde(rename = "type")]
 404         type_: Box<Type>,
 405     },
 406     /// `<Type as Trait>::Name` or associated types like `T::Item` where `T: Iterator`
 407     QualifiedPath {
 408         name: String,
 409         self_type: Box<Type>,
 410         #[serde(rename = "trait")]
 411         trait_: Box<Type>,
 412     },
 413 }
 414
 415 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 416 pub struct FunctionPointer {
 417     pub decl: FnDecl,
 418     pub generic_params: Vec<GenericParamDef>,
 419     pub header: HashSet<Qualifiers>,
 420     pub abi: String,
 421 }
 422
 423 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 424 pub struct FnDecl {
 425     pub inputs: Vec<(String, Type)>,
 426     pub output: Option<Type>,
 427     pub c_variadic: bool,
 428 }
 429
 430 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 431 pub struct Trait {
 432     pub is_auto: bool,
 433     pub is_unsafe: bool,
 434     pub items: Vec<Id>,
 435     pub generics: Generics,
 436     pub bounds: Vec<GenericBound>,
 437     pub implementors: Vec<Id>,
 438 }
 439
 440 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 441 pub struct TraitAlias {
 442     pub generics: Generics,
 443     pub params: Vec<GenericBound>,
 444 }
 445
 446 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 447 pub struct Impl {
 448     pub is_unsafe: bool,
 449     pub generics: Generics,
 450     pub provided_trait_methods: Vec<String>,
 451     #[serde(rename = "trait")]
 452     pub trait_: Option<Type>,
 453     #[serde(rename = "for")]
 454     pub for_: Type,
 455     pub items: Vec<Id>,
 456     pub negative: bool,
 457     pub synthetic: bool,
 458     pub blanket_impl: Option<Type>,
 459 }
 460
 461 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 462 #[serde(rename_all = "snake_case")]
 463 pub struct Import {
 464     /// The full path being imported.
 465     pub source: String,
 466     /// May be different from the last segment of `source` when renaming imports:
 467     /// `use source as name;`
 468     pub name: String,
 469     /// The ID of the item being imported.
 470     pub id: Option<Id>, // FIXME is this actually ever None?
 471     /// Whether this import uses a glob: `use source::*;`
 472     pub glob: bool,
 473 }
 474
 475 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 476 pub struct ProcMacro {
 477     pub kind: MacroKind,
 478     pub helpers: Vec<String>,
 479 }
 480
 481 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 482 #[serde(rename_all = "snake_case")]
 483 pub enum MacroKind {
 484     /// A bang macro `foo!()`.
 485     Bang,
 486     /// An attribute macro `#[foo]`.
 487     Attr,
 488     /// A derive macro `#[derive(Foo)]`
 489     Derive,
 490 }
 491
 492 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 493 pub struct Typedef {
 494     #[serde(rename = "type")]
 495     pub type_: Type,
 496     pub generics: Generics,
 497 }
 498
 499 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 500 pub struct OpaqueTy {
 501     pub bounds: Vec<GenericBound>,
 502     pub generics: Generics,
 503 }
 504
 505 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
 506 pub struct Static {
 507     #[serde(rename = "type")]
 508     pub type_: Type,
 509     pub mutable: bool,
 510     pub expr: String,
 511 }
 512
 513 #[cfg(test)]
 514 mod tests;