diff --git a/src/rustdoc-json-types/lib.rs b/src/rustdoc-json-types/lib.rs index 68030493e9cfd..8c625cee89ce1 100644 --- a/src/rustdoc-json-types/lib.rs +++ b/src/rustdoc-json-types/lib.rs @@ -3,6 +3,8 @@ //! These types are the public API exposed through the `--output-format json` flag. The [`Crate`] //! struct is the root of the JSON blob and all other items are contained within. +#![warn(missing_docs)] + use rustc_hash::FxHashMap; use serde::{Deserialize, Serialize}; use std::path::PathBuf; @@ -33,9 +35,12 @@ pub struct Crate { pub format_version: u32, } +/// Metadata of a crate, either the same crate on which `rustdoc` was invoked, or its dependency. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct ExternalCrate { + /// The name of the crate. pub name: String, + /// The root URL at which the crate's documentation lives. pub html_root_url: Option, } @@ -60,6 +65,9 @@ pub struct ItemSummary { pub kind: ItemKind, } +/// An Item represents anything that can hold documentation - modules, structs, enums, functions, +/// traits, type aliases, and more. The `Item` data type holds fields that can apply to any of these, +/// and leaves kind-specific details (like function args or enum variants) to the `inner` field. #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] pub struct Item { /// The unique identifier of this item. Can be used to find this item in various mappings. @@ -82,10 +90,13 @@ pub struct Item { pub links: FxHashMap, /// Stringified versions of the attributes on this item (e.g. `"#[inline]"`) pub attrs: Vec, + /// Information about the Item’s deprecation, if present. pub deprecation: Option, + /// The type-specific fields describing this Item. pub inner: ItemEnum, } +/// A range of source code. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Span { /// The path to the source file for this span relative to the path `rustdoc` was invoked with. @@ -96,28 +107,37 @@ pub struct Span { pub end: (usize, usize), } +/// Information about the deprecation of an API entry. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Deprecation { + /// Usually a version number when this Item first became deprecated. pub since: Option, + /// The reason for deprecation and/or what alternatives to use. pub note: Option, } +/// Visibility of an API entry. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum Visibility { + /// Explicitly public visibility set with `pub`. Public, /// For the most part items are private by default. The exceptions are associated items of /// public traits and variants of public enums. Default, + /// Explicitly crate-wide visibility set with `pub(crate)` Crate, - /// For `pub(in path)` visibility. `parent` is the module it's restricted to and `path` is how - /// that module was referenced (like `"super::super"` or `"crate::foo::bar"`). + /// For `pub(in path)` visibility. Restricted { + /// ID of the module to which this visibility restricts items. parent: Id, + /// The path with which `parent` was referenced + /// (like `"super::super"` or `"crate::foo::bar"`). path: String, }, } +/// Dynamic trait object type (`dyn Trait`). #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct DynTrait { /// All the traits implemented. One of them is the vtable, and the rest must be auto traits. @@ -132,9 +152,10 @@ pub struct DynTrait { pub lifetime: Option, } -#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] /// A trait and potential HRTBs +#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct PolyTrait { + /// The path to the trait. #[serde(rename = "trait")] pub trait_: Path, /// Used for Higher-Rank Trait Bounds (HRTBs) @@ -147,42 +168,110 @@ pub struct PolyTrait { pub generic_params: Vec, } +/// A set of generic parameters provided to a path segment, e.g. +/// +/// ```text +/// std::option::Option::::None +/// ^^^^^ +/// ``` #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum GenericArgs { - /// <'a, 32, B: Copy, C = u32> - AngleBracketed { args: Vec, bindings: Vec }, - /// Fn(A, B) -> C - Parenthesized { inputs: Vec, output: Option }, + /// `<'a, 32, B: Copy, C = u32>` + AngleBracketed { + /// The list of each argument on this type. + /// ```text + /// <'a, 32, B: Copy, C = u32> + /// ^^^^^^ + /// ``` + args: Vec, + /// Associated type or constant bindings (e.g. `Item=i32` or `Item: Clone`) for this type. + bindings: Vec, + }, + /// `Fn(A, B) -> C` + Parenthesized { + /// The input types, enclosed in parentheses. + inputs: Vec, + /// The output type provided after the `->`, if present. + output: Option, + }, } +/// One argument in a list of generic arguments to a path segment. +/// See [`GenericArgs`]. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum GenericArg { + /// A lifetime argument. + /// ```text + /// std::borrow::Cow<'static, str> + /// ^^^^^^^ + /// ``` Lifetime(String), + /// A type argument. + /// ```text + /// std::borrow::Cow<'static, str> + /// ^^^ + /// ``` Type(Type), + /// A constant as a generic argument. + /// ```text + /// core::array::IntoIter + /// ^^^^^^^^^^^^^^ + /// ``` Const(Constant), + /// A generic argument that's explicitly set to be inferred. + /// ```text + /// std::vec::Vec::<_>::new() + /// ^ + /// ``` Infer, } +/// A constant. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Constant { + /// The stringified expression of this constant. Note that its mapping to the original + /// source code is unstable and it's not guaranteed that it'll match the source code. pub expr: String, + /// The value of the evaluated expression for this constant, which is only computed for numeric + /// types. pub value: Option, + /// Whether this constant is a bool, numeric, string, or char literal. pub is_literal: bool, } +/// Describes a constraint applied to an associated type/constant, e.g. +/// ```text +/// IntoIterator +/// ^^^^^^^^^^ ^^^^^^^^^^^^^^^ +/// ``` #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct TypeBinding { + /// The name of the associated type/constant. pub name: String, + /// Arguments provided to the associated type/constant. pub args: GenericArgs, + /// The constraint applied to the associated type/constant. pub binding: TypeBindingKind, } +/// The way in which an associate type/constant is bound. +/// See [`TypeBinding`]. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum TypeBindingKind { + /// The required value/type is specified exactly. e.g. + /// ```text + /// Iterator + /// ^^^^^^^^^^ + /// ``` Equality(Term), + /// The type is required to satisfy a set of bounds. + /// ```text + /// Iterator + /// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + /// ``` Constraint(Vec), } @@ -201,115 +290,212 @@ pub enum TypeBindingKind { // FIXME(aDotInTheVoid): Consider making this non-public in rustdoc-types. pub struct Id(pub String); +/// The fundamental kind of an item. Unlike [`ItemEnum`], this does not carry any aditional info. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum ItemKind { + /// A module declaration, e.g. `mod foo;` or `mod foo {}` Module, + /// A crate imported via the `extern crate` syntax. ExternCrate, + /// An import of 1 or more items into scope, using the `use` keyword. Import, + /// A `struct` declaration. Struct, + /// A field of a struct. StructField, + /// A `union` declaration. Union, + /// An `enum` declaration. Enum, + /// A variant of a struct. Variant, + /// A function declaration, e.g. `fn f() {}` Function, + /// A type alias declaration, e.g. `type Pig = std::borrow::Cow<'static, str>;` TypeAlias, + #[allow(missing_docs)] OpaqueTy, + /// The declaration of a constant, e.g. `const GREETING: &str = "Hi :3";` Constant, + /// A `trait` declaration. Trait, + /// A trait alias declaration, e.g. `trait Int = Add + Sub + Mul + Div;` + /// See https://github.com/rust-lang/rust/issues/41517 TraitAlias, + /// An implementation. Impl, + /// A declaration of a `static`. Static, + /// `type`s from an `extern` block. + /// See https://github.com/rust-lang/rust/issues/43467 ForeignType, + /// A macro declaration. + /// Corresponds to either `ItemEnum::Macro(_)` + /// or `ItemEnum::ProcMacro(ProcMacro { kind: MacroKind::Bang })` Macro, + /// A procedural macro attribute. + /// Corresponds to `ItemEnum::ProcMacro(ProcMacro { kind: MacroKind::Attr })` ProcAttribute, + /// A procedural macro usable in the `#[derive()]` attribute. + /// Corresponds to `ItemEnum::ProcMacro(ProcMacro { kind: MacroKind::Derive })` ProcDerive, + /// An associated constant of a trait or a type. AssocConst, + /// An associated type of a trait or a type. AssocType, + /// A primitive type, e.g. `u32`. Items of this kind only come from the core library. Primitive, + /// A keyword declaration. Items of this kind only come from the come library and exist solely + /// to carry documentation for the respective keywords. Keyword, } +/// Specific fields of an item. +/// See [`Item`]. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum ItemEnum { + /// A module declaration, e.g. `mod foo;` or `mod foo {}` Module(Module), + /// A crate imported via the `extern crate` syntax. ExternCrate { + /// The name of the imported crate. name: String, + /// If the crate is renamed, this is its name in the namespace. rename: Option, }, + /// An import of 1 or more items into scope, using the `use` keyword. Import(Import), + /// A `union` declaration. Union(Union), + /// A `struct` declaration. Struct(Struct), + /// A field of a struct. StructField(Type), + /// An `enum` declaration. Enum(Enum), + /// A variant of a struct. Variant(Variant), + /// A function declaration (including methods and other associated functions) Function(Function), + /// A `trait` declaration. Trait(Trait), + /// A trait alias declaration, e.g. `trait Int = Add + Sub + Mul + Div;` + /// See https://github.com/rust-lang/rust/issues/41517 TraitAlias(TraitAlias), + /// An implementation. Impl(Impl), + /// A type alias declaration, e.g. `type Pig = std::borrow::Cow<'static, str>;` TypeAlias(TypeAlias), + #[allow(missing_docs)] OpaqueTy(OpaqueTy), + /// The declaration of a constant, e.g. `const GREETING: &str = "Hi :3";` Constant { + /// The type of the constant. #[serde(rename = "type")] type_: Type, + /// The declared constant itself. #[serde(rename = "const")] const_: Constant, }, + /// A declaration of a `static`. Static(Static), - /// `type`s from an extern block + /// `type`s from an `extern` block. + /// See https://github.com/rust-lang/rust/issues/43467 ForeignType, - /// Declarative macro_rules! macro + /// A macro_rules! declarative macro. Contains a single string with the source + /// representation of the macro with the patterns stripped. Macro(String), + /// A procedural macro. ProcMacro(ProcMacro), + /// A primitive type, e.g. `u32`. Items of this kind only come from the core library. Primitive(Primitive), + /// An associated constant of a trait or a type. AssocConst { + /// The type of the constant. #[serde(rename = "type")] type_: Type, - /// e.g. `const X: usize = 5;` + /// The stringified expression for the default value, if provided, e.g. + /// ```rust + /// const X: usize = 640 * 1024; + /// // ^^^^^^^^^^ + /// ``` default: Option, }, + /// An associated type of a trait or a type. AssocType { + /// The generic arguments and where clauses on ahis associated type. generics: Generics, + /// The bounds for this associated type. e.g. + /// ```rust + /// trait IntoIterator { + /// type Item; + /// type IntoIter: Iterator; + /// // ^^^^^^^^^^^^^^^^^^^^^^^^^^^ + /// } + /// ``` bounds: Vec, - /// e.g. `type X = usize;` + /// The default for this type, if provided, e.g. + /// ```rust + /// type X = usize; + /// // ^^^^^ + /// ``` default: Option, }, } +/// A module declaration, e.g. `mod foo;` or `mod foo {}`. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Module { + /// Whether this is the root item of a crate. + /// This item doesn't correspond to any construction in the source code and is generated by the + /// compiler. pub is_crate: bool, + /// Items declared inside this crate. pub items: Vec, /// If `true`, this module is not part of the public API, but it contains /// items that are re-exported as public API. pub is_stripped: bool, } +/// A `union`. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Union { + /// The generic arguments and where clauses on this union. pub generics: Generics, + /// Whether any fields have been removed from the result, due to being private or hidden. pub fields_stripped: bool, + /// The list of fields in the union. + /// All of the corresponding [`Item`]s are of kind [`ItemEnum::StructField`]. pub fields: Vec, + /// All impls (both of traits and inherent) for this union. + /// All of the corresponding [`Item`]s are of kind [`ItemEnum::Impl`]. pub impls: Vec, } +/// A structure. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Struct { + /// The kind of struct. pub kind: StructKind, + /// The generic arguments and where clauses on this union. pub generics: Generics, + /// All impls (both of traits and inherent) for this struct. + /// All of the corresponding [`Item`]s are of kind [`ItemEnum::Impl`]. pub impls: Vec, } +/// The kind of a struct and the data specific to it, e.g. fields. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum StructKind { @@ -321,13 +507,14 @@ pub enum StructKind { Unit, /// A struct with unnamed fields. /// + /// All [`Id`]'s will point to [`ItemEnum::StructField`]. + /// Unlike most of JSON, private and `#[doc(hidden)]` fields will be given as `None` + /// instead of being omitted, because order matters. + /// /// ```rust /// pub struct TupleStruct(i32); /// pub struct EmptyTupleStruct(); /// ``` - /// - /// All [`Id`]'s will point to [`ItemEnum::StructField`]. Private and - /// `#[doc(hidden)]` fields will be given as `None` Tuple(Vec>), /// A struct with named fields. /// @@ -335,17 +522,29 @@ pub enum StructKind { /// pub struct PlainStruct { x: i32 } /// pub struct EmptyPlainStruct {} /// ``` - Plain { fields: Vec, fields_stripped: bool }, + Plain { + /// The list of fields in the struct. + /// All of the corresponding [`Item`]s are of kind [`ItemEnum::StructField`]. + fields: Vec, + /// Whether any fields have been removed from the result, due to being private or hidden. + fields_stripped: bool, + }, } +/// An enumeration. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Enum { + /// Information about the type parameters and `where` clauses of the enum. pub generics: Generics, + /// Whether any variants have been removed from the result, due to being private or hidden. pub variants_stripped: bool, + /// List of the IDs of the variants. pub variants: Vec, + /// Implementations for the enum. pub impls: Vec, } +/// A variant of an enum. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Variant { /// Whether the variant is plain, a tuple-like, or struct-like. Contains the fields. @@ -354,6 +553,7 @@ pub struct Variant { pub discriminant: Option, } +/// The kind of an enum variant and the data specific to it, e.g. fields. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum VariantKind { @@ -368,7 +568,8 @@ pub enum VariantKind { Plain, /// A variant with unnamed fields. /// - /// Unlike most of json, `#[doc(hidden)]` fields will be given as `None` + /// All [`Id`]'s will point to [`ItemEnum::StructField`]. + /// Unlike most of JSON, `#[doc(hidden)]` fields will be given as `None` /// instead of being omitted, because order matters. /// /// ```rust @@ -386,9 +587,16 @@ pub enum VariantKind { /// EmptyStructVariant {}, /// } /// ``` - Struct { fields: Vec, fields_stripped: bool }, + Struct { + /// The list of variants in the enum. + /// All of the corresponding [`Item`]s are of kind [`ItemEnum::Variant`]. + fields: Vec, + /// Whether any variants have been removed from the result, due to being private or hidden. + fields_stripped: bool, + }, } +/// The value that distinguishes a variant in an enum from other variants. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Discriminant { /// The expression that produced the discriminant. @@ -406,62 +614,142 @@ pub struct Discriminant { pub value: String, } +/// A set of fundamental properties of a function. +/// See [`FnDecl`] #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Header { + /// Can this function be called at compile-time? #[serde(rename = "const")] pub const_: bool, + /// Is this function unsafe? #[serde(rename = "unsafe")] pub unsafe_: bool, + /// Is this function async? #[serde(rename = "async")] pub async_: bool, + /// The calling convention used by the function. pub abi: Abi, } +/// The calling convention used by a function. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub enum Abi { // We only have a concrete listing here for stable ABI's because their are so many // See rustc_ast_passes::feature_gate::PostExpansionVisitor::check_abi for the list + /// The default ABI, but that can also be written explicitly with `extern "Rust"`. Rust, - C { unwind: bool }, - Cdecl { unwind: bool }, - Stdcall { unwind: bool }, - Fastcall { unwind: bool }, - Aapcs { unwind: bool }, - Win64 { unwind: bool }, - SysV64 { unwind: bool }, - System { unwind: bool }, + /// Can be specified as `extern "C"` or, as a shorthand, just `extern`. + C { + /// If this is `true`, the ABI was specified as `extern "C-unwind"`. + unwind: bool, + }, + /// Can be specified as `extern "cdecl"`. + Cdecl { + /// If this is `true`, the ABI was specified as `extern "cdecl-unwind"` + unwind: bool, + }, + /// Can be specified as `extern "stdcall"`. + Stdcall { + /// If this is `true`, the ABI was specified as `extern "stdcall-unwind"`. + unwind: bool, + }, + /// Can be specified as `extern "fastcall"`. + Fastcall { + /// If this is `true`, the ABI was specified as `extern "fastcall-unwind"`. + unwind: bool, + }, + /// Can be specified as `extern "aapcs"`. + Aapcs { + /// If this is `true`, the ABI was specified as `extern "aapcs-unwind"`. + unwind: bool, + }, + /// Can be specified as `extern "win64"`. + Win64 { + /// If this is `true`, the ABI was specified as `extern "win64-unwind"`. + unwind: bool, + }, + /// Can be specifed as `extern "sysv64"`. + SysV64 { + /// If this is `true`, the ABI was specified as `extern "sysv64-unwind"`. + unwind: bool, + }, + /// Can be specified as `extern "system"`. + System { + /// If this is `true`, the ABI was specified as `extern "system-unwind"`. + unwind: bool, + }, + /// Any other ABI, including unstable ones. Other(String), } -/// Represents a function (including methods and other associated functions) +/// A function declaration (including methods and other associated functions). #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Function { + /// Information about the function signature, or declaration. pub decl: FnDecl, + /// Information about the function’s type parameters and `where` clauses. pub generics: Generics, + /// Information about core properties of the function, e.g. whether it's `const`, its ABI, etc. pub header: Header, + /// Whether the function has a body, i.e. an implementation. pub has_body: bool, } +/// Generic parameters accepted by an item and `where` clauses imposed on it and the parameters. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Generics { + /// A list of generic parameter definitions (e.g. ``). pub params: Vec, + /// A list of where predicates (e.g. `where T: Iterator, T::Item: Copy`). pub where_predicates: Vec, } +/// One generic parameter accepted by an item. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct GenericParamDef { + /// Name of the parameter. + /// ```rust + /// fn f<'resource, Resource>(x: &'resource Resource) {} + /// // ^^^^^^^^ ^^^^^^^^ + /// ``` pub name: String, + /// The kind of the parameter and data specific to a particular parameter kind, e.g. type + /// bounds. pub kind: GenericParamDefKind, } +/// The kind of a generic parameter. +/// See [`GenericParamDef`]. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum GenericParamDefKind { + /// Denotes a lifetime parameter. Lifetime { + /// Lifetimes that this lifetime parameter is require to outlive. + /// + /// ```rust + /// fn f<'a, 'b, 'resource: 'a + 'b>(a: &'a str, b: &'b str, res: &'resource str) {} + /// // ^^^^^^^ + /// ``` outlives: Vec, }, + + /// Denotes a type parameter. Type { + /// Bounds applied directly to the type. Note that the bounds from `where` clauses + /// that constrain this parameter won't appear here. + /// + /// ```rust + /// fn default2() -> [T; 2] where T: Clone { todo!() } + /// // ^^^^^^^ + /// ``` bounds: Vec, + /// The default type for this parameter, if provided, e.g. + /// + /// ```rust + /// trait PartialEq {} + /// // ^^^^ + /// ``` default: Option, /// This is normally `false`, which means that this generic parameter is /// declared in the Rust source text. @@ -488,43 +776,75 @@ pub enum GenericParamDefKind { /// the Rust source text. synthetic: bool, }, + + /// Denotes a constant parameter. Const { + /// The type of the constant as declared. #[serde(rename = "type")] type_: Type, + /// The stringified expression for the default value, if provided. It's not guaranteed that + /// it'll match the actual source code for the default value. default: Option, }, } +/// One `where` clause. +/// ```rust +/// fn default() -> T where T: Default { T::default() } +/// // ^^^^^^^^^^ +/// ``` #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum WherePredicate { + /// A type is expected to comply with a set of bounds BoundPredicate { + /// The type that's being constrained. + /// + /// ```rust + /// fn f(x: T) where for<'a> &'a T: Iterator {} + /// // ^ + /// ``` #[serde(rename = "type")] type_: Type, + /// The set of bounds that constrain the type. + /// + /// ```rust + /// fn f(x: T) where for<'a> &'a T: Iterator {} + /// // ^^^^^^^^ + /// ``` bounds: Vec, /// Used for Higher-Rank Trait Bounds (HRTBs) - /// ```text - /// where for<'a> &'a T: Iterator," - /// ^^^^^^^ - /// | - /// this part + /// ```rust + /// fn f(x: T) where for<'a> &'a T: Iterator {} + /// // ^^^^^^^ /// ``` generic_params: Vec, }, + + /// A lifetime is expected to outlive other lifetimes. RegionPredicate { + /// The name of the lifetime. lifetime: String, + /// The lifetimes that must be encompassed by the lifetime. bounds: Vec, }, + + /// A type must exactly equal another type. EqPredicate { + /// The left side of the equation. lhs: Type, + /// The right side of the equation. rhs: Term, }, } +/// Either a trait bound or a lifetime constraint. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum GenericBound { + /// A trait bound. TraitBound { + /// The full path to the trait. #[serde(rename = "trait")] trait_: Path, /// Used for Higher-Rank Trait Bounds (HRTBs) @@ -535,77 +855,138 @@ pub enum GenericBound { /// this part /// ``` generic_params: Vec, + /// The context for which a trait is supposed to be used, e.g. `const modifier: TraitBoundModifier, }, + /// A lifetime bound, e.g. + /// ```rust + /// fn f<'a, T>(x: &'a str, y: &T) where T: 'a {} + /// // ^^^ + /// ``` Outlives(String), } +/// A set of modifiers applied to a trait. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum TraitBoundModifier { + /// Marks the absence of a modifier. None, + /// Indicates that the trait bound relaxes a trait bound applied to a parameter by default, + /// e.g. `T: Sized?`, the `Sized` trait is required for all generic type parameters by default + /// unless specified otherwise with this modifier. Maybe, + /// Indicates that the trait bound must be applicable in both a run-time and a compile-time + /// context. MaybeConst, } +/// Either a type or a constant, usually stored as the right-hand side of an equation in places like +/// [`TypeBinding`] #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum Term { + /// A type. + /// + /// ```rust + /// fn f(x: impl IntoIterator) {} + /// // ^^^ + /// ``` Type(Type), + /// A constant. + /// + /// ```ignore (incomplete feature in the snippet) + /// trait Foo { + /// const BAR: usize; + /// } + /// + /// fn f(x: impl Foo) {} + /// // ^^ + /// ``` Constant(Constant), } +/// A type. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum Type { - /// Structs, enums, and unions + /// Structs, enums, unions, etc., e.g. `std::option::Option` ResolvedPath(Path), + /// Dynamic trait object type (`dyn Trait`). DynTrait(DynTrait), - /// Parameterized types + /// Parameterized types. The contained string is the name of the parameter. Generic(String), - /// Built in numeric (i*, u*, f*) types, bool, and char + /// Built-in types, such as the integers, floating-point numbers, `bool`, and `char`. Primitive(String), - /// `extern "ABI" fn` + /// A function pointer type, e.g. `fn(u32) -> u32`, `extern "C" fn() -> *const u8` FunctionPointer(Box), - /// `(String, u32, Box)` + /// A tuple type, e.g. `(String, u32, Box)` Tuple(Vec), - /// `[u32]` + /// An unsized slice type, e.g. `[u32]`. Slice(Box), - /// [u32; 15] + /// An array type, e.g. `[u32; 15]` Array { + /// The type of the contained element. #[serde(rename = "type")] type_: Box, + /// The stringified expression that is the length of the array. Keep in mind that it's not + /// guaranteed to match the actual source code of the expression. len: String, }, - /// `u32 is 1..` + /// A pattern type, e.g. `u32 is 1..` + /// See https://github.com/rust-lang/rust/issues/123646 Pat { + /// The base type, e.g. the `u32` in `u32 is 1..` #[serde(rename = "type")] type_: Box, #[doc(hidden)] __pat_unstable_do_not_use: String, }, - /// `impl TraitA + TraitB + ...` + /// An opaque type that satisfies a set of bounds, `impl TraitA + TraitB + ...` ImplTrait(Vec), - /// `_` + /// A type that's left to be inferred, `_` Infer, - /// `*mut u32`, `*u8`, etc. + /// A raw pointer type, e.g. `*mut u32`, `*const u8`, etc. RawPointer { + /// This is `true` for `*mut _` and `false` for `*const _`. mutable: bool, + /// The type of the pointee. #[serde(rename = "type")] type_: Box, }, /// `&'a mut String`, `&str`, etc. BorrowedRef { + /// The name of the lifetime of the reference, if provided. lifetime: Option, + /// This is `true` for `&mut _` and `false` for `&_` mutable: bool, + /// The type of the pointee. #[serde(rename = "type")] type_: Box, }, /// Associated types like `::Name` and `T::Item` where /// `T: Iterator` or inherent associated types like `Struct::Name`. QualifiedPath { + /// The name of the associated type in the parent type. + /// + /// ```ignore (incomplete expresssion) + /// as Iterator>::Item + /// // ^^^^ + /// ``` name: String, + /// The generic parameters provided to the associated type. + /// + /// ```ignore (incomplete expression) + /// as BetterIterator>::Item<'static> + /// // ^^^^^^^^^ + /// ``` args: Box, + /// The type with which this type is associated. + /// + /// ```ignore (incomplete expression) + /// as Iterator>::Item + /// // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + /// ``` self_type: Box, /// `None` iff this is an *inherent* associated type. #[serde(rename = "trait")] @@ -613,34 +994,48 @@ pub enum Type { }, } +/// A type that has a simple path to it. This is the kind of type of structs, unions, enums, etc. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Path { + /// The name of the type as declared, e.g. in + /// + /// ```rust + /// mod foo { + /// struct Bar; + /// } + /// ``` + /// + /// for `foo::Bar`, this field will be `Bar`. pub name: String, + /// The ID of the type. pub id: Id, - /// Generic arguments to the type - /// ```test + /// Generic arguments to the type. + /// + /// ```ignore (incomplete expression) /// std::borrow::Cow<'static, str> - /// ^^^^^^^^^^^^^^ - /// | - /// this part + /// // ^^^^^^^^^^^^^^ /// ``` pub args: Option>, } +/// A type that is a function pointer. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct FunctionPointer { + /// The signature of the function. pub decl: FnDecl, /// Used for Higher-Rank Trait Bounds (HRTBs) - /// ```text - /// for<'c> fn(val: &'c i32) -> i32 - /// ^^^^^^^ - /// | - /// this part + /// + /// ```ignore (incomplete expression) + /// for<'c> fn(val: &'c i32) -> i32 + /// // ^^^^^^^ /// ``` pub generic_params: Vec, + /// The core properties of the function, such as its calling convention, whether it is unsafe, + /// etc. pub header: Header, } +/// The signature of a function. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct FnDecl { /// List of argument names and their type. @@ -648,42 +1043,85 @@ pub struct FnDecl { /// Note that not all names will be valid identifiers, as some of /// them may be patterns. pub inputs: Vec<(String, Type)>, + /// The output type, if specified. pub output: Option, + /// Whether the function accepts an arbitrary amount of trailing arguments the C way. + /// ```text + /// fn printf(fmt: &str, ...); + /// ``` pub c_variadic: bool, } +/// A `trait` declaration. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Trait { + /// Whether the trait is marked `auto` and is thus implemented automatically + /// for all aplicable types. pub is_auto: bool, + /// Whether the trait is marked as `unsafe`. pub is_unsafe: bool, + /// Whether the trait is [object safe](https://doc.rust-lang.org/reference/items/traits.html#object-safety). pub is_object_safe: bool, + /// Items that can/must be implemented by the implementations. pub items: Vec, + /// Information about the type parameters and `where` clauses of the trait. pub generics: Generics, + /// Constraints that must be met by the implementor of the trait. pub bounds: Vec, + /// The implementations of the trait. pub implementations: Vec, } +/// A trait alias declaration, e.g. `trait Int = Add + Sub + Mul + Div;` +/// See https://github.com/rust-lang/rust/issues/41517 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct TraitAlias { + /// Information about the type parameters and `where` clauses of the alias. pub generics: Generics, + /// The bounds that are associated with the alias. pub params: Vec, } +/// An implementation. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Impl { + /// Whether this impl is for an unsafe trait. pub is_unsafe: bool, + /// Information about the impl’s type parameters and `where` clauses. pub generics: Generics, + /// The list of names for all provided methods in this impl block. This is provided for + /// ease of access if you don’t need more information from the items field. + /// + /// For example, for this impl of the [`PartialEq`] trait: + /// ```rust + /// struct Foo; + /// + /// impl PartialEq for Foo { + /// fn eq(&self, other: &Self) -> bool { todo!() } + /// } + /// ``` + /// This field will be `["eq"]` pub provided_trait_methods: Vec, + /// The trait being implemented or `None` if the impl is “inherent”, which means + /// `impl Struct {}` as opposed to `impl Trait for Struct {}`. #[serde(rename = "trait")] pub trait_: Option, + /// The type that the impl block is for. #[serde(rename = "for")] pub for_: Type, + /// The list of associated items contained in this impl block. pub items: Vec, + /// Whether this is a negative impl (e.g. `!Sized` or `!Send`). pub negative: bool, + /// Whether this is an impl that’s implied by the compiler + /// (for autotraits, e.g. `Send` or `Sync`). pub synthetic: bool, + /// The name of the generic parameter used for the blanket impl, if this impl was produced by + /// one. For example, for `impl Into for T` this field would be `"T"`. pub blanket_impl: Option, } +/// An import of an item into scope. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub struct Import { @@ -701,12 +1139,18 @@ pub struct Import { pub glob: bool, } +/// A procedural macro. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct ProcMacro { + /// How this macro is supposed to be called: `foo!()`, `#[foo]` or `#[derive(foo)]` pub kind: MacroKind, + /// Helped attributes defined by a macro to be used inside it. Defined only be attribute & + /// derive macros. pub helpers: Vec, } +/// The way a procedural macro is declared to be used. +/// See [`ProcMacro`] #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum MacroKind { @@ -718,30 +1162,42 @@ pub enum MacroKind { Derive, } +/// A type alias declaration, e.g. `type Pig = std::borrow::Cow<'static, str>;` #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct TypeAlias { + /// The type referred to by this alias. #[serde(rename = "type")] pub type_: Type, + /// Information about the type parameters and `where` clauses of the alias. pub generics: Generics, } +#[allow(missing_docs)] #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct OpaqueTy { pub bounds: Vec, pub generics: Generics, } +/// A global variable declaration. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Static { + /// The type of the static. #[serde(rename = "type")] pub type_: Type, + /// This is `true` for mutable statics, declared as `static mut X: T = f();` pub mutable: bool, + /// The stringified expression for the initial value. It's not guaranteed that + /// it'll match the actual source code for the initial value. pub expr: String, } +/// A primitive type declaration. Declarations of this kind can only come from the core library. #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Primitive { + /// The name of the library. pub name: String, + /// The implementations, inherent and of traits, on the primitive type. pub impls: Vec, }