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