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//! # Feature Flags
7//!
8//! ## `rustc-hash`
9//!
10//! We expose a `rustc-hash` feature, disabled by default. This feature switches the
11//! [`std::collections::HashMap`] for [`rustc_hash::FxHashMap`] to improve the performance of said
12//! `HashMap` in specific situations.
13//!
14//! `cargo-semver-checks` for example, saw a [-3% improvement][1] when benchmarking using the
15//! `aws_sdk_ec2` JSON output (~500MB of JSON). As always, we recommend measuring the impact before
16//! turning this feature on, as [`FxHashMap`][2] only concerns itself with hash speed, and may
17//! increase the number of collisions.
18//!
19//! ## `rkyv_0_8`
20//!
21//! We expose a `rkyv_0_8` feature, disabled by default. When enabled, it derives `rkyv`'s
22//! [`Archive`][3], [`Serialize`][4] and [`Deserialize`][5] traits for all types in this crate.
23//! Furthermore, it exposes the corresponding `Archived*` types (e.g. `ArchivedId` for [`Id`]).
24//!
25//! `rkyv` lets you works with JSON output without paying the deserialization cost _upfront_,
26//! thanks to [zero-copy deserialization][6].
27//! You can perform various types of analyses on the `Archived*` version of the relevant types,
28//! incurring the full deserialization cost only for the subset of items you actually need.
29//!
30//! [1]: https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/rustc-hash.20and.20performance.20of.20rustdoc-types/near/474855731
31//! [2]: https://crates.io/crates/rustc-hash
32//! [3]: https://docs.rs/rkyv/0.8.15/rkyv/trait.Archive.html
33//! [4]: https://docs.rs/rkyv/0.8.15/rkyv/trait.Serialize.html
34//! [5]: https://docs.rs/rkyv/0.8.15/rkyv/trait.Deserialize.html
35//! [6]: https://rkyv.org/zero-copy-deserialization.html
36
37// # On `rkyv` Derives
38//
39// In most cases, it's enough to add `#[derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize)]`
40// on top of a type to derive the relevant `rkyv` traits.
41//
42// There are a few exceptions, though, where more complex macro options are required.
43// The following sections break down the patterns that are showcased by `rkyv'`s
44// [JSON schema example](https://github.com/rkyv/rkyv/blob/985b0230a0b9cb9fce4a4ee9facb6af148e27c8e/rkyv/examples/json_like_schema.rs).
45//
46// ## Recursive Types
47//
48// Let's look at the `Type` enum as an example. It stores a `Box<Type>` in its `Slice` variant.
49// A "vanilla" `rkyv` annotation will cause an overflow in the compiler when
50// building the crate, since the bounds generated by the macro will be self-referential and thus
51// trap the compiler into a never-ending loop.
52//
53// To prevent this issue, `#[rkyv(omit_bounds)]` must be added to the relevant field.
54//
55// ## Co-Recursive Types
56//
57// The same problem occurs if a type is co-recursive—i.e. it doesn't _directly_ store a pointer
58// to another instance of the same type, but one of its fields does, transitively.
59//
60// For example, let's look at `Path`:
61//
62// - `Path` has a field of type `Option<Box<GenericArgs>>`
63// - One of the variants in `GenericArgs` has a field of type `Vec<GenericArg>`
64// - One of the variants of `GenericArg` has a field of type `Type`
65// - `Type::ResolvedPath` stores a `Path` instance
66//
67// The same logic of the recursive case applies here: we must use `#[rkyv(omit_bounds)]` to break the cycle.
68//
69// ## Additional Bounds
70//
71// Whenever `#[rkyv(omit_bounds)]` is added to a field or variant, `rkyv` omits _all_ traits bounds for that
72// field in the generated impl. This may result in compilation errors due to insufficient bounds in the
73// generated code.
74//
75// To add _some_ bounds back, `rkyv` exposes four knobs:
76//
77// - `#[rkyv(archive_bounds(..))]` to add predicates to all generated impls
78// - `#[rkyv(serialize_bounds(..))]` to add predicates to just the `Serialize` impl
79// - `#[rkyv(deserialize_bounds(..))]` to add predicates to just the `Deserialize` impl
80// - `#[rkyv(bytecheck(bounds(..)))]` to add predicates to just the `CheckBytes` impl
81//
82// In particular, we use the following annotations in this crate:
83//
84// - `serialize_bounds(__S: rkyv::ser::Writer + rkyv::ser::Allocator, __S::Error: rkyv::rancor::Source)` for serializing
85// variable-length types like `Vec<T>`. `rkyv`'s zero-copy format requires the serializer to be able
86// to write bytes (`Writer`) and allocate scratch space (`Allocator`) for these types
87// ([`rkyv`'s `Vec` impl bounds](https://docs.rs/rkyv/0.8.15/rkyv/trait.Serialize.html#impl-Serialize%3CS%3E-for-Vec%3CT%3E)).
88// The `Error: Source` bound lets error types compose.
89// - `deserialize_bounds(__D::Error: rkyv::rancor::Source)` so that errors from deserializing fields behind
90// `omit_bounds` (e.g. `Box<T>`, `Vec<T>`) can compose via the `Source` trait.
91// - `bytecheck(bounds(__C: rkyv::validation::ArchiveContext, __C::Error: rkyv::rancor::Source))` for validating
92// archived data. Checking that bytes represent a valid archived value requires an `ArchiveContext` that tracks
93// validation state (e.g. subtree ranges, to prevent overlapping/out-of-bounds archived data).
94
95#[cfg(not(feature = "rustc-hash"))]
96use std::collections::HashMap;
97use std::path::PathBuf;
98
99#[cfg(feature = "rustc-hash")]
100use rustc_hash::FxHashMap as HashMap;
101use serde_derive::{Deserialize, Serialize};
102
103pub type FxHashMap<K, V> = HashMap<K, V>; // re-export for use in src/librustdoc
104
105/// The version of JSON output that this crate represents.
106///
107/// This integer is incremented with every breaking change to the API,
108/// and is returned along with the JSON blob as [`Crate::format_version`].
109/// Consuming code should assert that this value matches the format version(s) that it supports.
110//
111// WARNING: When you update `FORMAT_VERSION`, please also update the "Latest feature" line with a
112// description of the change. This minimizes the risk of two concurrent PRs changing
113// `FORMAT_VERSION` from N to N+1 and git merging them without conflicts; the "Latest feature" line
114// will instead cause conflicts. See #94591 for more. (This paragraph and the "Latest feature" line
115// are deliberately not in a doc comment, because they need not be in public docs.)
116//
117// Latest feature: Add `ExternCrate::path`.
118pub const FORMAT_VERSION: u32 = 57;
119
120/// The root of the emitted JSON blob.
121///
122/// It contains all type/documentation information
123/// about the language items in the local crate, as well as info about external items to allow
124/// tools to find or link to them.
125#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
126#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
127#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
128pub struct Crate {
129 /// The id of the root [`Module`] item of the local crate.
130 pub root: Id,
131 /// The version string given to `--crate-version`, if any.
132 pub crate_version: Option<String>,
133 /// Whether or not the output includes private items.
134 pub includes_private: bool,
135 /// A collection of all items in the local crate as well as some external traits and their
136 /// items that are referenced locally.
137 pub index: HashMap<Id, Item>,
138 /// Maps IDs to fully qualified paths and other info helpful for generating links.
139 pub paths: HashMap<Id, ItemSummary>,
140 /// Maps `crate_id` of items to a crate name and html_root_url if it exists.
141 pub external_crates: HashMap<u32, ExternalCrate>,
142 /// Information about the target for which this documentation was generated
143 pub target: Target,
144 /// A single version number to be used in the future when making backwards incompatible changes
145 /// to the JSON output.
146 pub format_version: u32,
147}
148
149/// Information about a target
150#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
151#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
152#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
153pub struct Target {
154 /// The target triple for which this documentation was generated
155 pub triple: String,
156 /// A list of features valid for use in `#[target_feature]` attributes
157 /// for the target where this rustdoc JSON was generated.
158 pub target_features: Vec<TargetFeature>,
159}
160
161/// Information about a target feature.
162///
163/// Rust target features are used to influence code generation, especially around selecting
164/// instructions which are not universally supported by the target architecture.
165///
166/// Target features are commonly enabled by the [`#[target_feature]` attribute][1] to influence code
167/// generation for a particular function, and less commonly enabled by compiler options like
168/// `-Ctarget-feature` or `-Ctarget-cpu`. Targets themselves automatically enable certain target
169/// features by default, for example because the target's ABI specification requires saving specific
170/// registers which only exist in an architectural extension.
171///
172/// Target features can imply other target features: for example, x86-64 `avx2` implies `avx`, and
173/// aarch64 `sve2` implies `sve`, since both of these architectural extensions depend on their
174/// predecessors.
175///
176/// Target features can be probed at compile time by [`#[cfg(target_feature)]`][2] or `cfg!(…)`
177/// conditional compilation to determine whether a target feature is enabled in a particular
178/// context.
179///
180/// [1]: https://doc.rust-lang.org/stable/reference/attributes/codegen.html#the-target_feature-attribute
181/// [2]: https://doc.rust-lang.org/reference/conditional-compilation.html#target_feature
182#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
183#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
184#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
185pub struct TargetFeature {
186 /// The name of this target feature.
187 pub name: String,
188 /// Other target features which are implied by this target feature, if any.
189 pub implies_features: Vec<String>,
190 /// If this target feature is unstable, the name of the associated language feature gate.
191 pub unstable_feature_gate: Option<String>,
192 /// Whether this feature is globally enabled for this compilation session.
193 ///
194 /// Target features can be globally enabled implicitly as a result of the target's definition.
195 /// For example, x86-64 hardware floating point ABIs require saving x87 and SSE2 registers,
196 /// which in turn requires globally enabling the `x87` and `sse2` target features so that the
197 /// generated machine code conforms to the target's ABI.
198 ///
199 /// Target features can also be globally enabled explicitly as a result of compiler flags like
200 /// [`-Ctarget-feature`][1] or [`-Ctarget-cpu`][2].
201 ///
202 /// [1]: https://doc.rust-lang.org/beta/rustc/codegen-options/index.html#target-feature
203 /// [2]: https://doc.rust-lang.org/beta/rustc/codegen-options/index.html#target-cpu
204 pub globally_enabled: bool,
205}
206
207/// Metadata of a crate, either the same crate on which `rustdoc` was invoked, or its dependency.
208#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
209#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
210#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
211pub struct ExternalCrate {
212 /// The name of the crate.
213 ///
214 /// Note: This is the [*crate* name][crate-name], which may not be the same as the
215 /// [*package* name][package-name]. For example, for <https://crates.io/crates/regex-syntax>,
216 /// this field will be `regex_syntax` (which uses an `_`, not a `-`).
217 ///
218 /// [crate-name]: https://doc.rust-lang.org/stable/cargo/reference/cargo-targets.html#the-name-field
219 /// [package-name]: https://doc.rust-lang.org/stable/cargo/reference/manifest.html#the-name-field
220 pub name: String,
221 /// The root URL at which the crate's documentation lives.
222 pub html_root_url: Option<String>,
223
224 /// A path from where this crate was loaded.
225 ///
226 /// This will typically be a `.rlib` or `.rmeta`. It can be used to determine which crate
227 /// this was in terms of whatever build-system invoked rustc.
228 #[cfg_attr(feature = "rkyv_0_8", rkyv(with = rkyv::with::AsString))]
229 pub path: PathBuf,
230}
231
232/// Information about an external (not defined in the local crate) [`Item`].
233///
234/// For external items, you don't get the same level of
235/// information. This struct should contain enough to generate a link/reference to the item in
236/// question, or can be used by a tool that takes the json output of multiple crates to find
237/// the actual item definition with all the relevant info.
238#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
239#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
240#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
241pub struct ItemSummary {
242 /// Can be used to look up the name and html_root_url of the crate this item came from in the
243 /// `external_crates` map.
244 pub crate_id: u32,
245 /// The list of path components for the fully qualified path of this item (e.g.
246 /// `["std", "io", "lazy", "Lazy"]` for `std::io::lazy::Lazy`).
247 ///
248 /// Note that items can appear in multiple paths, and the one chosen is implementation
249 /// defined. Currently, this is the full path to where the item was defined. Eg
250 /// [`String`] is currently `["alloc", "string", "String"]` and [`HashMap`][`std::collections::HashMap`]
251 /// is `["std", "collections", "hash", "map", "HashMap"]`, but this is subject to change.
252 pub path: Vec<String>,
253 /// Whether this item is a struct, trait, macro, etc.
254 pub kind: ItemKind,
255}
256
257/// Anything that can hold documentation - modules, structs, enums, functions, traits, etc.
258///
259/// The `Item` data type holds fields that can apply to any of these,
260/// and leaves kind-specific details (like function args or enum variants) to the `inner` field.
261#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
262#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
263#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
264pub struct Item {
265 /// The unique identifier of this item. Can be used to find this item in various mappings.
266 pub id: Id,
267 /// This can be used as a key to the `external_crates` map of [`Crate`] to see which crate
268 /// this item came from.
269 pub crate_id: u32,
270 /// Some items such as impls don't have names.
271 pub name: Option<String>,
272 /// The source location of this item (absent if it came from a macro expansion or inline
273 /// assembly).
274 pub span: Option<Span>,
275 /// By default all documented items are public, but you can tell rustdoc to output private items
276 /// so this field is needed to differentiate.
277 pub visibility: Visibility,
278 /// The full markdown docstring of this item. Absent if there is no documentation at all,
279 /// Some("") if there is some documentation but it is empty (EG `#[doc = ""]`).
280 pub docs: Option<String>,
281 /// 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
282 pub links: HashMap<String, Id>,
283 /// Attributes on this item.
284 ///
285 /// Does not include `#[deprecated]` attributes: see the [`Self::deprecation`] field instead.
286 ///
287 /// Attributes appear in pretty-printed Rust form, regardless of their formatting
288 /// in the original source code. For example:
289 /// - `#[non_exhaustive]` and `#[must_use]` are represented as themselves.
290 /// - `#[no_mangle]` and `#[export_name]` are also represented as themselves.
291 /// - `#[repr(C)]` and other reprs also appear as themselves,
292 /// though potentially with a different order: e.g. `repr(i8, C)` may become `repr(C, i8)`.
293 /// Multiple repr attributes on the same item may be combined into an equivalent single attr.
294 pub attrs: Vec<Attribute>,
295 /// Information about the item’s deprecation, if present.
296 pub deprecation: Option<Deprecation>,
297 /// The type-specific fields describing this item.
298 pub inner: ItemEnum,
299}
300
301#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
302#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
303#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
304#[serde(rename_all = "snake_case")]
305/// An attribute, e.g. `#[repr(C)]`
306///
307/// This doesn't include:
308/// - `#[doc = "Doc Comment"]` or `/// Doc comment`. These are in [`Item::docs`] instead.
309/// - `#[deprecated]`. These are in [`Item::deprecation`] instead.
310pub enum Attribute {
311 /// `#[non_exhaustive]`
312 NonExhaustive,
313
314 /// `#[must_use]`
315 MustUse { reason: Option<String> },
316
317 /// `#[macro_export]`
318 MacroExport,
319
320 /// `#[export_name = "name"]`
321 ExportName(String),
322
323 /// `#[link_section = "name"]`
324 LinkSection(String),
325
326 /// `#[automatically_derived]`
327 AutomaticallyDerived,
328
329 /// `#[repr]`
330 Repr(AttributeRepr),
331
332 /// `#[no_mangle]`
333 NoMangle,
334
335 /// #[target_feature(enable = "feature1", enable = "feature2")]
336 TargetFeature { enable: Vec<String> },
337
338 /// Something else.
339 ///
340 /// Things here are explicitly *not* covered by the [`FORMAT_VERSION`]
341 /// constant, and may change without bumping the format version.
342 ///
343 /// As an implementation detail, this is currently either:
344 /// 1. A HIR debug printing, like `"#[attr = Optimize(Speed)]"`
345 /// 2. The attribute as it appears in source form, like
346 /// `"#[optimize(speed)]"`.
347 Other(String),
348}
349
350#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
351#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
352#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
353/// The contents of a `#[repr(...)]` attribute.
354///
355/// Used in [`Attribute::Repr`].
356pub struct AttributeRepr {
357 /// The representation, e.g. `#[repr(C)]`, `#[repr(transparent)]`
358 pub kind: ReprKind,
359
360 /// Alignment in bytes, if explicitly specified by `#[repr(align(...)]`.
361 pub align: Option<u64>,
362 /// Alignment in bytes, if explicitly specified by `#[repr(packed(...)]]`.
363 pub packed: Option<u64>,
364
365 /// The integer type for an enum descriminant, if explicitly specified.
366 ///
367 /// e.g. `"i32"`, for `#[repr(C, i32)]`
368 pub int: Option<String>,
369}
370
371#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
372#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
373#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
374#[serde(rename_all = "snake_case")]
375/// The kind of `#[repr]`.
376///
377/// See [AttributeRepr::kind]`.
378pub enum ReprKind {
379 /// `#[repr(Rust)]`
380 ///
381 /// Also the default.
382 Rust,
383 /// `#[repr(C)]`
384 C,
385 /// `#[repr(transparent)]
386 Transparent,
387 /// `#[repr(simd)]`
388 Simd,
389}
390
391/// A range of source code.
392#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
393#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
394#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
395pub struct Span {
396 /// The path to the source file for this span relative to the path `rustdoc` was invoked with.
397 #[cfg_attr(feature = "rkyv_0_8", rkyv(with = rkyv::with::AsString))]
398 pub filename: PathBuf,
399 /// One indexed Line and Column of the first character of the `Span`.
400 pub begin: (usize, usize),
401 /// One indexed Line and Column of the last character of the `Span`.
402 pub end: (usize, usize),
403}
404
405/// Information about the deprecation of an [`Item`].
406#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
407#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
408#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
409pub struct Deprecation {
410 /// Usually a version number when this [`Item`] first became deprecated.
411 pub since: Option<String>,
412 /// The reason for deprecation and/or what alternatives to use.
413 pub note: Option<String>,
414}
415
416/// Visibility of an [`Item`].
417#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
418#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
419#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
420#[serde(rename_all = "snake_case")]
421pub enum Visibility {
422 /// Explicitly public visibility set with `pub`.
423 Public,
424 /// For the most part items are private by default. The exceptions are associated items of
425 /// public traits and variants of public enums.
426 Default,
427 /// Explicitly crate-wide visibility set with `pub(crate)`
428 Crate,
429 /// For `pub(in path)` visibility.
430 Restricted {
431 /// ID of the module to which this visibility restricts items.
432 parent: Id,
433 /// The path with which [`parent`] was referenced
434 /// (like `super::super` or `crate::foo::bar`).
435 ///
436 /// [`parent`]: Visibility::Restricted::parent
437 path: String,
438 },
439}
440
441/// Dynamic trait object type (`dyn Trait`).
442#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
443#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
444#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
445pub struct DynTrait {
446 /// All the traits implemented. One of them is the vtable, and the rest must be auto traits.
447 pub traits: Vec<PolyTrait>,
448 /// The lifetime of the whole dyn object
449 /// ```text
450 /// dyn Debug + 'static
451 /// ^^^^^^^
452 /// |
453 /// this part
454 /// ```
455 pub lifetime: Option<String>,
456}
457
458/// A trait and potential HRTBs
459#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
460#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
461#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
462pub struct PolyTrait {
463 /// The path to the trait.
464 #[serde(rename = "trait")]
465 pub trait_: Path,
466 /// Used for Higher-Rank Trait Bounds (HRTBs)
467 /// ```text
468 /// dyn for<'a> Fn() -> &'a i32"
469 /// ^^^^^^^
470 /// ```
471 pub generic_params: Vec<GenericParamDef>,
472}
473
474/// A set of generic arguments provided to a path segment, e.g.
475///
476/// ```text
477/// std::option::Option<u32>
478/// ^^^^^
479/// ```
480#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
481#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
482#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
483#[cfg_attr(feature = "rkyv_0_8", rkyv(serialize_bounds(
484 __S: rkyv::ser::Writer + rkyv::ser::Allocator,
485 __S::Error: rkyv::rancor::Source,
486)))]
487#[cfg_attr(feature = "rkyv_0_8", rkyv(deserialize_bounds(
488 __D::Error: rkyv::rancor::Source,
489)))]
490#[cfg_attr(feature = "rkyv_0_8", rkyv(bytecheck(bounds(
491 __C: rkyv::validation::ArchiveContext,
492))))]
493#[serde(rename_all = "snake_case")]
494pub enum GenericArgs {
495 /// `<'a, 32, B: Copy, C = u32>`
496 AngleBracketed {
497 /// The list of each argument on this type.
498 /// ```text
499 /// <'a, 32, B: Copy, C = u32>
500 /// ^^^^^^
501 /// ```
502 args: Vec<GenericArg>,
503 /// Associated type or constant bindings (e.g. `Item=i32` or `Item: Clone`) for this type.
504 constraints: Vec<AssocItemConstraint>,
505 },
506 /// `Fn(A, B) -> C`
507 Parenthesized {
508 /// The input types, enclosed in parentheses.
509 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
510 inputs: Vec<Type>,
511 /// The output type provided after the `->`, if present.
512 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
513 output: Option<Type>,
514 },
515 /// `T::method(..)`
516 ReturnTypeNotation,
517}
518
519/// One argument in a list of generic arguments to a path segment.
520///
521/// Part of [`GenericArgs`].
522#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
523#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
524#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
525#[serde(rename_all = "snake_case")]
526pub enum GenericArg {
527 /// A lifetime argument.
528 /// ```text
529 /// std::borrow::Cow<'static, str>
530 /// ^^^^^^^
531 /// ```
532 Lifetime(String),
533 /// A type argument.
534 /// ```text
535 /// std::borrow::Cow<'static, str>
536 /// ^^^
537 /// ```
538 Type(Type),
539 /// A constant as a generic argument.
540 /// ```text
541 /// core::array::IntoIter<u32, { 640 * 1024 }>
542 /// ^^^^^^^^^^^^^^
543 /// ```
544 Const(Constant),
545 /// A generic argument that's explicitly set to be inferred.
546 /// ```text
547 /// std::vec::Vec::<_>
548 /// ^
549 /// ```
550 Infer,
551}
552
553/// A constant.
554#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
555#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
556#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
557pub struct Constant {
558 /// The stringified expression of this constant. Note that its mapping to the original
559 /// source code is unstable and it's not guaranteed that it'll match the source code.
560 pub expr: String,
561 /// The value of the evaluated expression for this constant, which is only computed for numeric
562 /// types.
563 pub value: Option<String>,
564 /// Whether this constant is a bool, numeric, string, or char literal.
565 pub is_literal: bool,
566}
567
568/// Describes a bound applied to an associated type/constant.
569///
570/// Example:
571/// ```text
572/// IntoIterator<Item = u32, IntoIter: Clone>
573/// ^^^^^^^^^^ ^^^^^^^^^^^^^^^
574/// ```
575#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
576#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
577#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
578#[cfg_attr(feature = "rkyv_0_8", rkyv(serialize_bounds(
579 __S: rkyv::ser::Writer + rkyv::ser::Allocator,
580 __S::Error: rkyv::rancor::Source,
581)))]
582#[cfg_attr(feature = "rkyv_0_8", rkyv(deserialize_bounds(
583 __D::Error: rkyv::rancor::Source,
584)))]
585#[cfg_attr(feature = "rkyv_0_8", rkyv(bytecheck(bounds(
586 __C: rkyv::validation::ArchiveContext,
587 <__C as rkyv::rancor::Fallible>::Error: rkyv::rancor::Source,
588))))]
589pub struct AssocItemConstraint {
590 /// The name of the associated type/constant.
591 pub name: String,
592 /// Arguments provided to the associated type/constant.
593 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
594 pub args: Option<Box<GenericArgs>>,
595 /// The kind of bound applied to the associated type/constant.
596 pub binding: AssocItemConstraintKind,
597}
598
599/// The way in which an associate type/constant is bound.
600#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
601#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
602#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
603#[serde(rename_all = "snake_case")]
604pub enum AssocItemConstraintKind {
605 /// The required value/type is specified exactly. e.g.
606 /// ```text
607 /// Iterator<Item = u32, IntoIter: DoubleEndedIterator>
608 /// ^^^^^^^^^^
609 /// ```
610 Equality(Term),
611 /// The type is required to satisfy a set of bounds.
612 /// ```text
613 /// Iterator<Item = u32, IntoIter: DoubleEndedIterator>
614 /// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
615 /// ```
616 Constraint(Vec<GenericBound>),
617}
618
619/// An opaque identifier for an item.
620///
621/// It can be used to lookup in [`Crate::index`] or [`Crate::paths`] to resolve it
622/// to an [`Item`].
623///
624/// Id's are only valid within a single JSON blob. They cannot be used to
625/// resolve references between the JSON output's for different crates.
626///
627/// Rustdoc makes no guarantees about the inner value of Id's. Applications
628/// should treat them as opaque keys to lookup items, and avoid attempting
629/// to parse them, or otherwise depend on any implementation details.
630#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
631#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
632#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)))]
633// FIXME(aDotInTheVoid): Consider making this non-public in rustdoc-types.
634pub struct Id(pub u32);
635
636/// The fundamental kind of an item. Unlike [`ItemEnum`], this does not carry any additional info.
637///
638/// Part of [`ItemSummary`].
639#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
640#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
641#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
642#[cfg_attr(feature = "rkyv_0_8", rkyv(compare(PartialEq)))]
643#[serde(rename_all = "snake_case")]
644pub enum ItemKind {
645 /// A module declaration, e.g. `mod foo;` or `mod foo {}`
646 Module,
647 /// A crate imported via the `extern crate` syntax.
648 ExternCrate,
649 /// An import of 1 or more items into scope, using the `use` keyword.
650 Use,
651 /// A `struct` declaration.
652 Struct,
653 /// A field of a struct.
654 StructField,
655 /// A `union` declaration.
656 Union,
657 /// An `enum` declaration.
658 Enum,
659 /// A variant of a enum.
660 Variant,
661 /// A function declaration, e.g. `fn f() {}`
662 Function,
663 /// A type alias declaration, e.g. `type Pig = std::borrow::Cow<'static, str>;`
664 TypeAlias,
665 /// The declaration of a constant, e.g. `const GREETING: &str = "Hi :3";`
666 Constant,
667 /// A `trait` declaration.
668 Trait,
669 /// A trait alias declaration, e.g. `trait Int = Add + Sub + Mul + Div;`
670 ///
671 /// See [the tracking issue](https://github.com/rust-lang/rust/issues/41517)
672 TraitAlias,
673 /// An `impl` block.
674 Impl,
675 /// A `static` declaration.
676 Static,
677 /// `type`s from an `extern` block.
678 ///
679 /// See [the tracking issue](https://github.com/rust-lang/rust/issues/43467)
680 ExternType,
681 /// A macro declaration.
682 ///
683 /// Corresponds to either `ItemEnum::Macro(_)`
684 /// or `ItemEnum::ProcMacro(ProcMacro { kind: MacroKind::Bang })`
685 Macro,
686 /// A procedural macro attribute.
687 ///
688 /// Corresponds to `ItemEnum::ProcMacro(ProcMacro { kind: MacroKind::Attr })`
689 ProcAttribute,
690 /// A procedural macro usable in the `#[derive()]` attribute.
691 ///
692 /// Corresponds to `ItemEnum::ProcMacro(ProcMacro { kind: MacroKind::Derive })`
693 ProcDerive,
694 /// An associated constant of a trait or a type.
695 AssocConst,
696 /// An associated type of a trait or a type.
697 AssocType,
698 /// A primitive type, e.g. `u32`.
699 ///
700 /// [`Item`]s of this kind only come from the core library.
701 Primitive,
702 /// A keyword declaration.
703 ///
704 /// [`Item`]s of this kind only come from the come library and exist solely
705 /// to carry documentation for the respective keywords.
706 Keyword,
707 /// An attribute declaration.
708 ///
709 /// [`Item`]s of this kind only come from the core library and exist solely
710 /// to carry documentation for the respective builtin attributes.
711 Attribute,
712}
713
714/// Specific fields of an item.
715///
716/// Part of [`Item`].
717#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
718#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
719#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
720#[serde(rename_all = "snake_case")]
721pub enum ItemEnum {
722 /// A module declaration, e.g. `mod foo;` or `mod foo {}`
723 Module(Module),
724 /// A crate imported via the `extern crate` syntax.
725 ExternCrate {
726 /// The name of the imported crate.
727 name: String,
728 /// If the crate is renamed, this is its name in the crate.
729 rename: Option<String>,
730 },
731 /// An import of 1 or more items into scope, using the `use` keyword.
732 Use(Use),
733
734 /// A `union` declaration.
735 Union(Union),
736 /// A `struct` declaration.
737 Struct(Struct),
738 /// A field of a struct.
739 StructField(Type),
740 /// An `enum` declaration.
741 Enum(Enum),
742 /// A variant of a enum.
743 Variant(Variant),
744
745 /// A function declaration (including methods and other associated functions)
746 Function(Function),
747
748 /// A `trait` declaration.
749 Trait(Trait),
750 /// A trait alias declaration, e.g. `trait Int = Add + Sub + Mul + Div;`
751 ///
752 /// See [the tracking issue](https://github.com/rust-lang/rust/issues/41517)
753 TraitAlias(TraitAlias),
754 /// An `impl` block.
755 Impl(Impl),
756
757 /// A type alias declaration, e.g. `type Pig = std::borrow::Cow<'static, str>;`
758 TypeAlias(TypeAlias),
759 /// The declaration of a constant, e.g. `const GREETING: &str = "Hi :3";`
760 Constant {
761 /// The type of the constant.
762 #[serde(rename = "type")]
763 type_: Type,
764 /// The declared constant itself.
765 #[serde(rename = "const")]
766 const_: Constant,
767 },
768
769 /// A declaration of a `static`.
770 Static(Static),
771
772 /// `type`s from an `extern` block.
773 ///
774 /// See [the tracking issue](https://github.com/rust-lang/rust/issues/43467)
775 ExternType,
776
777 /// A macro_rules! declarative macro. Contains a single string with the source
778 /// representation of the macro with the patterns stripped.
779 Macro(String),
780 /// A procedural macro.
781 ProcMacro(ProcMacro),
782
783 /// A primitive type, e.g. `u32`.
784 ///
785 /// [`Item`]s of this kind only come from the core library.
786 Primitive(Primitive),
787
788 /// An associated constant of a trait or a type.
789 AssocConst {
790 /// The type of the constant.
791 #[serde(rename = "type")]
792 type_: Type,
793 /// Inside a trait declaration, this is the default value for the associated constant,
794 /// if provided.
795 /// Inside an `impl` block, this is the value assigned to the associated constant,
796 /// and will always be present.
797 ///
798 /// The representation is implementation-defined and not guaranteed to be representative of
799 /// either the resulting value or of the source code.
800 ///
801 /// ```rust
802 /// const X: usize = 640 * 1024;
803 /// // ^^^^^^^^^^
804 /// ```
805 value: Option<String>,
806 },
807 /// An associated type of a trait or a type.
808 AssocType {
809 /// The generic parameters and where clauses on ahis associated type.
810 generics: Generics,
811 /// The bounds for this associated type. e.g.
812 /// ```rust
813 /// trait IntoIterator {
814 /// type Item;
815 /// type IntoIter: Iterator<Item = Self::Item>;
816 /// // ^^^^^^^^^^^^^^^^^^^^^^^^^^^
817 /// }
818 /// ```
819 bounds: Vec<GenericBound>,
820 /// Inside a trait declaration, this is the default for the associated type, if provided.
821 /// Inside an impl block, this is the type assigned to the associated type, and will always
822 /// be present.
823 ///
824 /// ```rust
825 /// type X = usize;
826 /// // ^^^^^
827 /// ```
828 #[serde(rename = "type")]
829 type_: Option<Type>,
830 },
831}
832
833impl ItemEnum {
834 /// Get just the kind of this item, but with no further data.
835 ///
836 /// ```rust
837 /// # use rustdoc_json_types::{ItemKind, ItemEnum};
838 /// let item = ItemEnum::ExternCrate { name: "libc".to_owned(), rename: None };
839 /// assert_eq!(item.item_kind(), ItemKind::ExternCrate);
840 /// ```
841 pub fn item_kind(&self) -> ItemKind {
842 match self {
843 ItemEnum::Module(_) => ItemKind::Module,
844 ItemEnum::ExternCrate { .. } => ItemKind::ExternCrate,
845 ItemEnum::Use(_) => ItemKind::Use,
846 ItemEnum::Union(_) => ItemKind::Union,
847 ItemEnum::Struct(_) => ItemKind::Struct,
848 ItemEnum::StructField(_) => ItemKind::StructField,
849 ItemEnum::Enum(_) => ItemKind::Enum,
850 ItemEnum::Variant(_) => ItemKind::Variant,
851 ItemEnum::Function(_) => ItemKind::Function,
852 ItemEnum::Trait(_) => ItemKind::Trait,
853 ItemEnum::TraitAlias(_) => ItemKind::TraitAlias,
854 ItemEnum::Impl(_) => ItemKind::Impl,
855 ItemEnum::TypeAlias(_) => ItemKind::TypeAlias,
856 ItemEnum::Constant { .. } => ItemKind::Constant,
857 ItemEnum::Static(_) => ItemKind::Static,
858 ItemEnum::ExternType => ItemKind::ExternType,
859 ItemEnum::Macro(_) => ItemKind::Macro,
860 ItemEnum::ProcMacro(pm) => match pm.kind {
861 MacroKind::Bang => ItemKind::Macro,
862 MacroKind::Attr => ItemKind::ProcAttribute,
863 MacroKind::Derive => ItemKind::ProcDerive,
864 },
865 ItemEnum::Primitive(_) => ItemKind::Primitive,
866 ItemEnum::AssocConst { .. } => ItemKind::AssocConst,
867 ItemEnum::AssocType { .. } => ItemKind::AssocType,
868 }
869 }
870}
871
872/// A module declaration, e.g. `mod foo;` or `mod foo {}`.
873#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
874#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
875#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
876pub struct Module {
877 /// Whether this is the root item of a crate.
878 ///
879 /// This item doesn't correspond to any construction in the source code and is generated by the
880 /// compiler.
881 pub is_crate: bool,
882 /// [`Item`]s declared inside this module.
883 pub items: Vec<Id>,
884 /// If `true`, this module is not part of the public API, but it contains
885 /// items that are re-exported as public API.
886 pub is_stripped: bool,
887}
888
889/// A `union`.
890#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
891#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
892#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
893pub struct Union {
894 /// The generic parameters and where clauses on this union.
895 pub generics: Generics,
896 /// Whether any fields have been removed from the result, due to being private or hidden.
897 pub has_stripped_fields: bool,
898 /// The list of fields in the union.
899 ///
900 /// All of the corresponding [`Item`]s are of kind [`ItemEnum::StructField`].
901 pub fields: Vec<Id>,
902 /// All impls (both of traits and inherent) for this union.
903 ///
904 /// All of the corresponding [`Item`]s are of kind [`ItemEnum::Impl`].
905 pub impls: Vec<Id>,
906}
907
908/// A `struct`.
909#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
910#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
911#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
912pub struct Struct {
913 /// The kind of the struct (e.g. unit, tuple-like or struct-like) and the data specific to it,
914 /// i.e. fields.
915 pub kind: StructKind,
916 /// The generic parameters and where clauses on this struct.
917 pub generics: Generics,
918 /// All impls (both of traits and inherent) for this struct.
919 /// All of the corresponding [`Item`]s are of kind [`ItemEnum::Impl`].
920 pub impls: Vec<Id>,
921}
922
923/// The kind of a [`Struct`] and the data specific to it, i.e. fields.
924#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
925#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
926#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
927#[serde(rename_all = "snake_case")]
928pub enum StructKind {
929 /// A struct with no fields and no parentheses.
930 ///
931 /// ```rust
932 /// pub struct Unit;
933 /// ```
934 Unit,
935 /// A struct with unnamed fields.
936 ///
937 /// All [`Id`]'s will point to [`ItemEnum::StructField`].
938 /// Unlike most of JSON, private and `#[doc(hidden)]` fields will be given as `None`
939 /// instead of being omitted, because order matters.
940 ///
941 /// ```rust
942 /// pub struct TupleStruct(i32);
943 /// pub struct EmptyTupleStruct();
944 /// ```
945 Tuple(Vec<Option<Id>>),
946 /// A struct with named fields.
947 ///
948 /// ```rust
949 /// pub struct PlainStruct { x: i32 }
950 /// pub struct EmptyPlainStruct {}
951 /// ```
952 Plain {
953 /// The list of fields in the struct.
954 ///
955 /// All of the corresponding [`Item`]s are of kind [`ItemEnum::StructField`].
956 fields: Vec<Id>,
957 /// Whether any fields have been removed from the result, due to being private or hidden.
958 has_stripped_fields: bool,
959 },
960}
961
962/// An `enum`.
963#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
964#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
965#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
966pub struct Enum {
967 /// Information about the type parameters and `where` clauses of the enum.
968 pub generics: Generics,
969 /// Whether any variants have been removed from the result, due to being private or hidden.
970 pub has_stripped_variants: bool,
971 /// The list of variants in the enum.
972 ///
973 /// All of the corresponding [`Item`]s are of kind [`ItemEnum::Variant`]
974 pub variants: Vec<Id>,
975 /// `impl`s for the enum.
976 pub impls: Vec<Id>,
977}
978
979/// A variant of an enum.
980#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
981#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
982#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
983pub struct Variant {
984 /// Whether the variant is plain, a tuple-like, or struct-like. Contains the fields.
985 pub kind: VariantKind,
986 /// The discriminant, if explicitly specified.
987 pub discriminant: Option<Discriminant>,
988}
989
990/// The kind of an [`Enum`] [`Variant`] and the data specific to it, i.e. fields.
991#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
992#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
993#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
994#[serde(rename_all = "snake_case")]
995pub enum VariantKind {
996 /// A variant with no parentheses
997 ///
998 /// ```rust
999 /// enum Demo {
1000 /// PlainVariant,
1001 /// PlainWithDiscriminant = 1,
1002 /// }
1003 /// ```
1004 Plain,
1005 /// A variant with unnamed fields.
1006 ///
1007 /// All [`Id`]'s will point to [`ItemEnum::StructField`].
1008 /// Unlike most of JSON, `#[doc(hidden)]` fields will be given as `None`
1009 /// instead of being omitted, because order matters.
1010 ///
1011 /// ```rust
1012 /// enum Demo {
1013 /// TupleVariant(i32),
1014 /// EmptyTupleVariant(),
1015 /// }
1016 /// ```
1017 Tuple(Vec<Option<Id>>),
1018 /// A variant with named fields.
1019 ///
1020 /// ```rust
1021 /// enum Demo {
1022 /// StructVariant { x: i32 },
1023 /// EmptyStructVariant {},
1024 /// }
1025 /// ```
1026 Struct {
1027 /// The list of named fields in the variant.
1028 /// All of the corresponding [`Item`]s are of kind [`ItemEnum::StructField`].
1029 fields: Vec<Id>,
1030 /// Whether any fields have been removed from the result, due to being private or hidden.
1031 has_stripped_fields: bool,
1032 },
1033}
1034
1035/// The value that distinguishes a variant in an [`Enum`] from other variants.
1036#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1037#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1038#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1039pub struct Discriminant {
1040 /// The expression that produced the discriminant.
1041 ///
1042 /// Unlike `value`, this preserves the original formatting (eg suffixes,
1043 /// hexadecimal, and underscores), making it unsuitable to be machine
1044 /// interpreted.
1045 ///
1046 /// In some cases, when the value is too complex, this may be `"{ _ }"`.
1047 /// When this occurs is unstable, and may change without notice.
1048 pub expr: String,
1049 /// The numerical value of the discriminant. Stored as a string due to
1050 /// JSON's poor support for large integers, and the fact that it would need
1051 /// to store from [`i128::MIN`] to [`u128::MAX`].
1052 pub value: String,
1053}
1054
1055/// A set of fundamental properties of a function.
1056#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1057#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1058#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1059pub struct FunctionHeader {
1060 /// Is this function marked as `const`?
1061 pub is_const: bool,
1062 /// Is this function unsafe?
1063 pub is_unsafe: bool,
1064 /// Is this function async?
1065 pub is_async: bool,
1066 /// The ABI used by the function.
1067 pub abi: Abi,
1068}
1069
1070/// The ABI (Application Binary Interface) used by a function.
1071///
1072/// If a variant has an `unwind` field, this means the ABI that it represents can be specified in 2
1073/// ways: `extern "_"` and `extern "_-unwind"`, and a value of `true` for that field signifies the
1074/// latter variant.
1075///
1076/// See the [Rustonomicon section](https://doc.rust-lang.org/nightly/nomicon/ffi.html#ffi-and-unwinding)
1077/// on unwinding for more info.
1078#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1079#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1080#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1081pub enum Abi {
1082 // We only have a concrete listing here for stable ABI's because there are so many
1083 // See rustc_ast_passes::feature_gate::PostExpansionVisitor::check_abi for the list
1084 /// The default ABI, but that can also be written explicitly with `extern "Rust"`.
1085 Rust,
1086 /// Can be specified as `extern "C"` or, as a shorthand, just `extern`.
1087 C { unwind: bool },
1088 /// Can be specified as `extern "cdecl"`.
1089 Cdecl { unwind: bool },
1090 /// Can be specified as `extern "stdcall"`.
1091 Stdcall { unwind: bool },
1092 /// Can be specified as `extern "fastcall"`.
1093 Fastcall { unwind: bool },
1094 /// Can be specified as `extern "aapcs"`.
1095 Aapcs { unwind: bool },
1096 /// Can be specified as `extern "win64"`.
1097 Win64 { unwind: bool },
1098 /// Can be specified as `extern "sysv64"`.
1099 SysV64 { unwind: bool },
1100 /// Can be specified as `extern "system"`.
1101 System { unwind: bool },
1102 /// Any other ABI, including unstable ones.
1103 Other(String),
1104}
1105
1106/// A function declaration (including methods and other associated functions).
1107#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1108#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1109#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1110pub struct Function {
1111 /// Information about the function signature, or declaration.
1112 pub sig: FunctionSignature,
1113 /// Information about the function’s type parameters and `where` clauses.
1114 pub generics: Generics,
1115 /// Information about core properties of the function, e.g. whether it's `const`, its ABI, etc.
1116 pub header: FunctionHeader,
1117 /// Whether the function has a body, i.e. an implementation.
1118 pub has_body: bool,
1119}
1120
1121/// Generic parameters accepted by an item and `where` clauses imposed on it and the parameters.
1122#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1123#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1124#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1125pub struct Generics {
1126 /// A list of generic parameter definitions (e.g. `<T: Clone + Hash, U: Copy>`).
1127 pub params: Vec<GenericParamDef>,
1128 /// A list of where predicates (e.g. `where T: Iterator, T::Item: Copy`).
1129 pub where_predicates: Vec<WherePredicate>,
1130}
1131
1132/// One generic parameter accepted by an item.
1133#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1134#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1135#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1136pub struct GenericParamDef {
1137 /// Name of the parameter.
1138 /// ```rust
1139 /// fn f<'resource, Resource>(x: &'resource Resource) {}
1140 /// // ^^^^^^^^ ^^^^^^^^
1141 /// ```
1142 pub name: String,
1143 /// The kind of the parameter and data specific to a particular parameter kind, e.g. type
1144 /// bounds.
1145 pub kind: GenericParamDefKind,
1146}
1147
1148/// The kind of a [`GenericParamDef`].
1149#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1150#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1151#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1152#[cfg_attr(feature = "rkyv_0_8", rkyv(serialize_bounds(
1153 __S: rkyv::ser::Writer + rkyv::ser::Allocator,
1154 __S::Error: rkyv::rancor::Source,
1155)))]
1156#[cfg_attr(feature = "rkyv_0_8", rkyv(deserialize_bounds(
1157 __D::Error: rkyv::rancor::Source,
1158)))]
1159#[cfg_attr(feature = "rkyv_0_8", rkyv(bytecheck(bounds(
1160 __C: rkyv::validation::ArchiveContext,
1161))))]
1162#[serde(rename_all = "snake_case")]
1163pub enum GenericParamDefKind {
1164 /// Denotes a lifetime parameter.
1165 Lifetime {
1166 /// Lifetimes that this lifetime parameter is required to outlive.
1167 ///
1168 /// ```rust
1169 /// fn f<'a, 'b, 'resource: 'a + 'b>(a: &'a str, b: &'b str, res: &'resource str) {}
1170 /// // ^^^^^^^
1171 /// ```
1172 outlives: Vec<String>,
1173 },
1174
1175 /// Denotes a type parameter.
1176 Type {
1177 /// Bounds applied directly to the type. Note that the bounds from `where` clauses
1178 /// that constrain this parameter won't appear here.
1179 ///
1180 /// ```rust
1181 /// fn default2<T: Default>() -> [T; 2] where T: Clone { todo!() }
1182 /// // ^^^^^^^
1183 /// ```
1184 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
1185 bounds: Vec<GenericBound>,
1186 /// The default type for this parameter, if provided, e.g.
1187 ///
1188 /// ```rust
1189 /// trait PartialEq<Rhs = Self> {}
1190 /// // ^^^^
1191 /// ```
1192 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
1193 default: Option<Type>,
1194 /// This is normally `false`, which means that this generic parameter is
1195 /// declared in the Rust source text.
1196 ///
1197 /// If it is `true`, this generic parameter has been introduced by the
1198 /// compiler behind the scenes.
1199 ///
1200 /// # Example
1201 ///
1202 /// Consider
1203 ///
1204 /// ```ignore (pseudo-rust)
1205 /// pub fn f(_: impl Trait) {}
1206 /// ```
1207 ///
1208 /// The compiler will transform this behind the scenes to
1209 ///
1210 /// ```ignore (pseudo-rust)
1211 /// pub fn f<impl Trait: Trait>(_: impl Trait) {}
1212 /// ```
1213 ///
1214 /// In this example, the generic parameter named `impl Trait` (and which
1215 /// is bound by `Trait`) is synthetic, because it was not originally in
1216 /// the Rust source text.
1217 is_synthetic: bool,
1218 },
1219
1220 /// Denotes a constant parameter.
1221 Const {
1222 /// The type of the constant as declared.
1223 #[serde(rename = "type")]
1224 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
1225 type_: Type,
1226 /// The stringified expression for the default value, if provided. It's not guaranteed that
1227 /// it'll match the actual source code for the default value.
1228 default: Option<String>,
1229 },
1230}
1231
1232/// One `where` clause.
1233/// ```rust
1234/// fn default<T>() -> T where T: Default { T::default() }
1235/// // ^^^^^^^^^^
1236/// ```
1237#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1238#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1239#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1240#[serde(rename_all = "snake_case")]
1241pub enum WherePredicate {
1242 /// A type is expected to comply with a set of bounds
1243 BoundPredicate {
1244 /// The type that's being constrained.
1245 ///
1246 /// ```rust
1247 /// fn f<T>(x: T) where for<'a> &'a T: Iterator {}
1248 /// // ^
1249 /// ```
1250 #[serde(rename = "type")]
1251 type_: Type,
1252 /// The set of bounds that constrain the type.
1253 ///
1254 /// ```rust
1255 /// fn f<T>(x: T) where for<'a> &'a T: Iterator {}
1256 /// // ^^^^^^^^
1257 /// ```
1258 bounds: Vec<GenericBound>,
1259 /// Used for Higher-Rank Trait Bounds (HRTBs)
1260 /// ```rust
1261 /// fn f<T>(x: T) where for<'a> &'a T: Iterator {}
1262 /// // ^^^^^^^
1263 /// ```
1264 generic_params: Vec<GenericParamDef>,
1265 },
1266
1267 /// A lifetime is expected to outlive other lifetimes.
1268 LifetimePredicate {
1269 /// The name of the lifetime.
1270 lifetime: String,
1271 /// The lifetimes that must be encompassed by the lifetime.
1272 outlives: Vec<String>,
1273 },
1274
1275 /// A type must exactly equal another type.
1276 EqPredicate {
1277 /// The left side of the equation.
1278 lhs: Type,
1279 /// The right side of the equation.
1280 rhs: Term,
1281 },
1282}
1283
1284/// Either a trait bound or a lifetime bound.
1285#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1286#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1287#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1288#[serde(rename_all = "snake_case")]
1289pub enum GenericBound {
1290 /// A trait bound.
1291 TraitBound {
1292 /// The full path to the trait.
1293 #[serde(rename = "trait")]
1294 trait_: Path,
1295 /// Used for Higher-Rank Trait Bounds (HRTBs)
1296 /// ```text
1297 /// where F: for<'a, 'b> Fn(&'a u8, &'b u8)
1298 /// ^^^^^^^^^^^
1299 /// |
1300 /// this part
1301 /// ```
1302 generic_params: Vec<GenericParamDef>,
1303 /// The context for which a trait is supposed to be used, e.g. `const
1304 modifier: TraitBoundModifier,
1305 },
1306 /// A lifetime bound, e.g.
1307 /// ```rust
1308 /// fn f<'a, T>(x: &'a str, y: &T) where T: 'a {}
1309 /// // ^^^
1310 /// ```
1311 Outlives(String),
1312 /// `use<'a, T>` precise-capturing bound syntax
1313 Use(Vec<PreciseCapturingArg>),
1314}
1315
1316/// A set of modifiers applied to a trait.
1317#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1318#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1319#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1320#[serde(rename_all = "snake_case")]
1321pub enum TraitBoundModifier {
1322 /// Marks the absence of a modifier.
1323 None,
1324 /// Indicates that the trait bound relaxes a trait bound applied to a parameter by default,
1325 /// e.g. `T: Sized?`, the `Sized` trait is required for all generic type parameters by default
1326 /// unless specified otherwise with this modifier.
1327 Maybe,
1328 /// Indicates that the trait bound must be applicable in both a run-time and a compile-time
1329 /// context.
1330 MaybeConst,
1331}
1332
1333/// One precise capturing argument. See [the rust reference](https://doc.rust-lang.org/reference/types/impl-trait.html#precise-capturing).
1334#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1335#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1336#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1337#[serde(rename_all = "snake_case")]
1338pub enum PreciseCapturingArg {
1339 /// A lifetime.
1340 /// ```rust
1341 /// pub fn hello<'a, T, const N: usize>() -> impl Sized + use<'a, T, N> {}
1342 /// // ^^
1343 Lifetime(String),
1344 /// A type or constant parameter.
1345 /// ```rust
1346 /// pub fn hello<'a, T, const N: usize>() -> impl Sized + use<'a, T, N> {}
1347 /// // ^ ^
1348 Param(String),
1349}
1350
1351/// Either a type or a constant, usually stored as the right-hand side of an equation in places like
1352/// [`AssocItemConstraint`]
1353#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1354#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1355#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1356#[serde(rename_all = "snake_case")]
1357pub enum Term {
1358 /// A type.
1359 ///
1360 /// ```rust
1361 /// fn f(x: impl IntoIterator<Item = u32>) {}
1362 /// // ^^^
1363 /// ```
1364 Type(Type),
1365 /// A constant.
1366 ///
1367 /// ```ignore (incomplete feature in the snippet)
1368 /// trait Foo {
1369 /// const BAR: usize;
1370 /// }
1371 ///
1372 /// fn f(x: impl Foo<BAR = 42>) {}
1373 /// // ^^
1374 /// ```
1375 Constant(Constant),
1376}
1377
1378/// A type.
1379#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1380#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1381#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1382#[cfg_attr(feature = "rkyv_0_8", rkyv(serialize_bounds(
1383 __S: rkyv::ser::Writer + rkyv::ser::Allocator,
1384 __S::Error: rkyv::rancor::Source,
1385)))]
1386#[cfg_attr(feature = "rkyv_0_8", rkyv(deserialize_bounds(
1387 __D::Error: rkyv::rancor::Source,
1388)))]
1389#[cfg_attr(feature = "rkyv_0_8", rkyv(bytecheck(bounds(
1390 __C: rkyv::validation::ArchiveContext,
1391))))]
1392#[serde(rename_all = "snake_case")]
1393pub enum Type {
1394 /// Structs, enums, unions and type aliases, e.g. `std::option::Option<u32>`
1395 ResolvedPath(Path),
1396 /// Dynamic trait object type (`dyn Trait`).
1397 DynTrait(DynTrait),
1398 /// Parameterized types. The contained string is the name of the parameter.
1399 Generic(String),
1400 /// Built-in numeric types (e.g. `u32`, `f32`), `bool`, `char`.
1401 Primitive(String),
1402 /// A function pointer type, e.g. `fn(u32) -> u32`, `extern "C" fn() -> *const u8`
1403 FunctionPointer(#[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))] Box<FunctionPointer>),
1404 /// A tuple type, e.g. `(String, u32, Box<usize>)`
1405 Tuple(#[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))] Vec<Type>),
1406 /// An unsized slice type, e.g. `[u32]`.
1407 Slice(#[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))] Box<Type>),
1408 /// An array type, e.g. `[u32; 15]`
1409 Array {
1410 /// The type of the contained element.
1411 #[serde(rename = "type")]
1412 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
1413 type_: Box<Type>,
1414 /// The stringified expression that is the length of the array.
1415 ///
1416 /// Keep in mind that it's not guaranteed to match the actual source code of the expression.
1417 len: String,
1418 },
1419 /// A pattern type, e.g. `u32 is 1..`
1420 ///
1421 /// See [the tracking issue](https://github.com/rust-lang/rust/issues/123646)
1422 Pat {
1423 /// The base type, e.g. the `u32` in `u32 is 1..`
1424 #[serde(rename = "type")]
1425 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
1426 type_: Box<Type>,
1427 #[doc(hidden)]
1428 __pat_unstable_do_not_use: String,
1429 },
1430 /// An opaque type that satisfies a set of bounds, `impl TraitA + TraitB + ...`
1431 ImplTrait(Vec<GenericBound>),
1432 /// A type that's left to be inferred, `_`
1433 Infer,
1434 /// A raw pointer type, e.g. `*mut u32`, `*const u8`, etc.
1435 RawPointer {
1436 /// This is `true` for `*mut _` and `false` for `*const _`.
1437 is_mutable: bool,
1438 /// The type of the pointee.
1439 #[serde(rename = "type")]
1440 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
1441 type_: Box<Type>,
1442 },
1443 /// `&'a mut String`, `&str`, etc.
1444 BorrowedRef {
1445 /// The name of the lifetime of the reference, if provided.
1446 lifetime: Option<String>,
1447 /// This is `true` for `&mut i32` and `false` for `&i32`
1448 is_mutable: bool,
1449 /// The type of the pointee, e.g. the `i32` in `&'a mut i32`
1450 #[serde(rename = "type")]
1451 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
1452 type_: Box<Type>,
1453 },
1454 /// Associated types like `<Type as Trait>::Name` and `T::Item` where
1455 /// `T: Iterator` or inherent associated types like `Struct::Name`.
1456 QualifiedPath {
1457 /// The name of the associated type in the parent type.
1458 ///
1459 /// ```ignore (incomplete expression)
1460 /// <core::array::IntoIter<u32, 42> as Iterator>::Item
1461 /// // ^^^^
1462 /// ```
1463 name: String,
1464 /// The generic arguments provided to the associated type.
1465 ///
1466 /// ```ignore (incomplete expression)
1467 /// <core::slice::IterMut<'static, u32> as BetterIterator>::Item<'static>
1468 /// // ^^^^^^^^^
1469 /// ```
1470 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
1471 args: Option<Box<GenericArgs>>,
1472 /// The type with which this type is associated.
1473 ///
1474 /// ```ignore (incomplete expression)
1475 /// <core::array::IntoIter<u32, 42> as Iterator>::Item
1476 /// // ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1477 /// ```
1478 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
1479 self_type: Box<Type>,
1480 /// `None` iff this is an *inherent* associated type.
1481 #[serde(rename = "trait")]
1482 trait_: Option<Path>,
1483 },
1484}
1485
1486/// A type that has a simple path to it. This is the kind of type of structs, unions, enums, etc.
1487#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1488#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1489#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1490#[cfg_attr(feature = "rkyv_0_8", rkyv(serialize_bounds(
1491 __S: rkyv::ser::Writer + rkyv::ser::Allocator,
1492 __S::Error: rkyv::rancor::Source,
1493)))]
1494#[cfg_attr(feature = "rkyv_0_8", rkyv(deserialize_bounds(
1495 __D::Error: rkyv::rancor::Source,
1496)))]
1497#[cfg_attr(feature = "rkyv_0_8", rkyv(bytecheck(bounds(
1498 __C: rkyv::validation::ArchiveContext,
1499 <__C as rkyv::rancor::Fallible>::Error: rkyv::rancor::Source,
1500))))]
1501pub struct Path {
1502 /// The path of the type.
1503 ///
1504 /// This will be the path that is *used* (not where it is defined), so
1505 /// multiple `Path`s may have different values for this field even if
1506 /// they all refer to the same item. e.g.
1507 ///
1508 /// ```rust
1509 /// pub type Vec1 = std::vec::Vec<i32>; // path: "std::vec::Vec"
1510 /// pub type Vec2 = Vec<i32>; // path: "Vec"
1511 /// pub type Vec3 = std::prelude::v1::Vec<i32>; // path: "std::prelude::v1::Vec"
1512 /// ```
1513 //
1514 // Example tested in ./tests/rustdoc-json/path_name.rs
1515 pub path: String,
1516 /// The ID of the type.
1517 pub id: Id,
1518 /// Generic arguments to the type.
1519 ///
1520 /// ```ignore (incomplete expression)
1521 /// std::borrow::Cow<'static, str>
1522 /// // ^^^^^^^^^^^^^^
1523 /// ```
1524 #[cfg_attr(feature = "rkyv_0_8", rkyv(omit_bounds))]
1525 pub args: Option<Box<GenericArgs>>,
1526}
1527
1528/// A type that is a function pointer.
1529#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1530#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1531#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1532pub struct FunctionPointer {
1533 /// The signature of the function.
1534 pub sig: FunctionSignature,
1535 /// Used for Higher-Rank Trait Bounds (HRTBs)
1536 ///
1537 /// ```ignore (incomplete expression)
1538 /// for<'c> fn(val: &'c i32) -> i32
1539 /// // ^^^^^^^
1540 /// ```
1541 pub generic_params: Vec<GenericParamDef>,
1542 /// The core properties of the function, such as the ABI it conforms to, whether it's unsafe, etc.
1543 pub header: FunctionHeader,
1544}
1545
1546/// The signature of a function.
1547#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1548#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1549#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1550pub struct FunctionSignature {
1551 /// List of argument names and their type.
1552 ///
1553 /// Note that not all names will be valid identifiers, as some of
1554 /// them may be patterns.
1555 pub inputs: Vec<(String, Type)>,
1556 /// The output type, if specified.
1557 pub output: Option<Type>,
1558 /// Whether the function accepts an arbitrary amount of trailing arguments the C way.
1559 ///
1560 /// ```ignore (incomplete code)
1561 /// fn printf(fmt: &str, ...);
1562 /// ```
1563 pub is_c_variadic: bool,
1564}
1565
1566/// A `trait` declaration.
1567#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1568#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1569#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1570pub struct Trait {
1571 /// Whether the trait is marked `auto` and is thus implemented automatically
1572 /// for all applicable types.
1573 pub is_auto: bool,
1574 /// Whether the trait is marked as `unsafe`.
1575 pub is_unsafe: bool,
1576 /// Whether the trait is [dyn compatible](https://doc.rust-lang.org/reference/items/traits.html#dyn-compatibility)[^1].
1577 ///
1578 /// [^1]: Formerly known as "object safe".
1579 pub is_dyn_compatible: bool,
1580 /// Associated [`Item`]s that can/must be implemented by the `impl` blocks.
1581 pub items: Vec<Id>,
1582 /// Information about the type parameters and `where` clauses of the trait.
1583 pub generics: Generics,
1584 /// Constraints that must be met by the implementor of the trait.
1585 pub bounds: Vec<GenericBound>,
1586 /// The implementations of the trait.
1587 pub implementations: Vec<Id>,
1588}
1589
1590/// A trait alias declaration, e.g. `trait Int = Add + Sub + Mul + Div;`
1591///
1592/// See [the tracking issue](https://github.com/rust-lang/rust/issues/41517)
1593#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1594#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1595#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1596pub struct TraitAlias {
1597 /// Information about the type parameters and `where` clauses of the alias.
1598 pub generics: Generics,
1599 /// The bounds that are associated with the alias.
1600 pub params: Vec<GenericBound>,
1601}
1602
1603/// An `impl` block.
1604#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1605#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1606#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1607pub struct Impl {
1608 /// Whether this impl is for an unsafe trait.
1609 pub is_unsafe: bool,
1610 /// Information about the impl’s type parameters and `where` clauses.
1611 pub generics: Generics,
1612 /// The list of the names of all the trait methods that weren't mentioned in this impl but
1613 /// were provided by the trait itself.
1614 ///
1615 /// For example, for this impl of the [`PartialEq`] trait:
1616 /// ```rust
1617 /// struct Foo;
1618 ///
1619 /// impl PartialEq for Foo {
1620 /// fn eq(&self, other: &Self) -> bool { todo!() }
1621 /// }
1622 /// ```
1623 /// This field will be `["ne"]`, as it has a default implementation defined for it.
1624 pub provided_trait_methods: Vec<String>,
1625 /// The trait being implemented or `None` if the impl is inherent, which means
1626 /// `impl Struct {}` as opposed to `impl Trait for Struct {}`.
1627 #[serde(rename = "trait")]
1628 pub trait_: Option<Path>,
1629 /// The type that the impl block is for.
1630 #[serde(rename = "for")]
1631 pub for_: Type,
1632 /// The list of associated items contained in this impl block.
1633 pub items: Vec<Id>,
1634 /// Whether this is a negative impl (e.g. `!Sized` or `!Send`).
1635 pub is_negative: bool,
1636 /// Whether this is an impl that’s implied by the compiler
1637 /// (for autotraits, e.g. `Send` or `Sync`).
1638 pub is_synthetic: bool,
1639 // FIXME: document this
1640 pub blanket_impl: Option<Type>,
1641}
1642
1643/// A `use` statement.
1644#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1645#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1646#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1647#[serde(rename_all = "snake_case")]
1648pub struct Use {
1649 /// The full path being imported.
1650 pub source: String,
1651 /// May be different from the last segment of `source` when renaming imports:
1652 /// `use source as name;`
1653 pub name: String,
1654 /// The ID of the item being imported. Will be `None` in case of re-exports of primitives:
1655 /// ```rust
1656 /// pub use i32 as my_i32;
1657 /// ```
1658 pub id: Option<Id>,
1659 /// Whether this statement is a wildcard `use`, e.g. `use source::*;`
1660 pub is_glob: bool,
1661}
1662
1663/// A procedural macro.
1664#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1665#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1666#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1667pub struct ProcMacro {
1668 /// How this macro is supposed to be called: `foo!()`, `#[foo]` or `#[derive(foo)]`
1669 pub kind: MacroKind,
1670 /// Helper attributes defined by a macro to be used inside it.
1671 ///
1672 /// Defined only for derive macros.
1673 ///
1674 /// E.g. the [`Default`] derive macro defines a `#[default]` helper attribute so that one can
1675 /// do:
1676 ///
1677 /// ```rust
1678 /// #[derive(Default)]
1679 /// enum Option<T> {
1680 /// #[default]
1681 /// None,
1682 /// Some(T),
1683 /// }
1684 /// ```
1685 pub helpers: Vec<String>,
1686}
1687
1688/// The way a [`ProcMacro`] is declared to be used.
1689#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1690#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1691#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1692#[serde(rename_all = "snake_case")]
1693pub enum MacroKind {
1694 /// A bang macro `foo!()`.
1695 Bang,
1696 /// An attribute macro `#[foo]`.
1697 Attr,
1698 /// A derive macro `#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]`
1699 Derive,
1700}
1701
1702/// A type alias declaration, e.g. `type Pig = std::borrow::Cow<'static, str>;`
1703#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1704#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1705#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1706pub struct TypeAlias {
1707 /// The type referred to by this alias.
1708 #[serde(rename = "type")]
1709 pub type_: Type,
1710 /// Information about the type parameters and `where` clauses of the alias.
1711 pub generics: Generics,
1712}
1713
1714/// A `static` declaration.
1715#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1716#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1717#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1718pub struct Static {
1719 /// The type of the static.
1720 #[serde(rename = "type")]
1721 pub type_: Type,
1722 /// This is `true` for mutable statics, declared as `static mut X: T = f();`
1723 pub is_mutable: bool,
1724 /// The stringified expression for the initial value.
1725 ///
1726 /// It's not guaranteed that it'll match the actual source code for the initial value.
1727 pub expr: String,
1728
1729 /// Is the static `unsafe`?
1730 ///
1731 /// This is only true if it's in an `extern` block, and not explicitly marked
1732 /// as `safe`.
1733 ///
1734 /// ```rust
1735 /// unsafe extern {
1736 /// static A: i32; // unsafe
1737 /// safe static B: i32; // safe
1738 /// }
1739 ///
1740 /// static C: i32 = 0; // safe
1741 /// static mut D: i32 = 0; // safe
1742 /// ```
1743 pub is_unsafe: bool,
1744}
1745
1746/// A primitive type declaration. Declarations of this kind can only come from the core library.
1747#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1748#[cfg_attr(feature = "rkyv_0_8", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
1749#[cfg_attr(feature = "rkyv_0_8", rkyv(derive(Debug)))]
1750pub struct Primitive {
1751 /// The name of the type.
1752 pub name: String,
1753 /// The implementations, inherent and of traits, on the primitive type.
1754 pub impls: Vec<Id>,
1755}
1756
1757#[cfg(test)]
1758mod tests;