polished out the rustdoc-json-types docs

Author: its-the-shrimp

src/rustdoc-json-types/lib.rs

@@ -97,9 +97,9 @@ pub struct Item {
     pub links: FxHashMap<String, Id>,
     /// Stringified versions of the attributes on this item (e.g. `"#[inline]"`)
     pub attrs: Vec<String>,
-    /// Information about the Item’s deprecation, if present.
+    /// Information about the item’s deprecation, if present.
     pub deprecation: Option<Deprecation>,
-    /// The type-specific fields describing this Item.
+    /// The type-specific fields describing this item.
     pub inner: ItemEnum,
 }
 
@@ -117,7 +117,7 @@ pub struct Span {
 /// Information about the deprecation of an [`Item`].
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Deprecation {
-    /// Usually a version number when this Item first became deprecated.
+    /// Usually a version number when this [`Item`] first became deprecated.
     pub since: Option<String>,
     /// The reason for deprecation and/or what alternatives to use.
     pub note: Option<String>,
@@ -138,8 +138,10 @@ pub enum 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"`).
+        /// The path with which [`parent`] was referenced
+        /// (like `super::super` or `crate::foo::bar`).
+        ///
+        /// [`parent`]: Visibility::Restricted::parent
         path: String,
     },
 }
@@ -203,7 +205,8 @@ pub enum GenericArgs {
 }
 
 /// One argument in a list of generic arguments to a path segment.
-/// See [`GenericArgs`].
+///
+/// Part of [`GenericArgs`].
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum GenericArg {
@@ -264,7 +267,6 @@ pub struct TypeBinding {
 }
 
 /// 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 {
@@ -299,7 +301,7 @@ pub struct Id(pub String);
 
 /// The fundamental kind of an item. Unlike [`ItemEnum`], this does not carry any aditional info.
 ///
-/// See [`ItemSummary`].
+/// Part of [`ItemSummary`].
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum ItemKind {
@@ -317,7 +319,7 @@ pub enum ItemKind {
     Union,
     /// An `enum` declaration.
     Enum,
-    /// A variant of a struct.
+    /// A variant of a enum.
     Variant,
     /// A function declaration, e.g. `fn f() {}`
     Function,
@@ -329,39 +331,48 @@ pub enum ItemKind {
     /// A `trait` declaration.
     Trait,
     /// A trait alias declaration, e.g. `trait Int = Add + Sub + Mul + Div;`
+    ///
     /// See [the tracking issue](https://github.com/rust-lang/rust/issues/41517)
     TraitAlias,
-    /// An implementation.
+    /// An `impl` block.
     Impl,
-    /// A declaration of a `static`.
+    /// A `static` declaration.
     Static,
     /// `type`s from an `extern` block.
+    ///
     /// See [the tracking issue](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.
+    /// A primitive type, e.g. `u32`.
+    ///
+    /// [`Item`]s 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
+    /// A keyword declaration.
+    ///
+    /// [`Item`]s 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`].
+/// Part of [`Item`].
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum ItemEnum {
@@ -371,7 +382,7 @@ pub enum ItemEnum {
     ExternCrate {
         /// The name of the imported crate.
         name: String,
-        /// If the crate is renamed, this is its name in the namespace.
+        /// If the crate is renamed, this is its name in the crate.
         rename: Option<String>,
     },
     /// An import of 1 or more items into scope, using the `use` keyword.
@@ -385,7 +396,7 @@ pub enum ItemEnum {
     StructField(Type),
     /// An `enum` declaration.
     Enum(Enum),
-    /// A variant of a struct.
+    /// A variant of a enum.
     Variant(Variant),
 
     /// A function declaration (including methods and other associated functions)
@@ -394,9 +405,10 @@ pub enum ItemEnum {
     /// A `trait` declaration.
     Trait(Trait),
     /// A trait alias declaration, e.g. `trait Int = Add + Sub + Mul + Div;`
+    ///
     /// See [the tracking issue](https://github.com/rust-lang/rust/issues/41517)
     TraitAlias(TraitAlias),
-    /// An implementation.
+    /// An `impl` block.
     Impl(Impl),
 
     /// A type alias declaration, e.g. `type Pig = std::borrow::Cow<'static, str>;`
@@ -416,6 +428,7 @@ pub enum ItemEnum {
     Static(Static),
 
     /// `type`s from an `extern` block.
+    ///
     /// See [the tracking issue](https://github.com/rust-lang/rust/issues/43467)
     ForeignType,
 
@@ -425,7 +438,9 @@ pub enum ItemEnum {
     /// A procedural macro.
     ProcMacro(ProcMacro),
 
-    /// A primitive type, e.g. `u32`. Items of this kind only come from the core library.
+    /// A primitive type, e.g. `u32`.
+    ///
+    /// [`Item`]s of this kind only come from the core library.
     Primitive(Primitive),
 
     /// An associated constant of a trait or a type.
@@ -466,10 +481,11 @@ pub enum ItemEnum {
 #[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.
+    /// [`Item`]s declared inside this module.
     pub items: Vec<Id>,
     /// If `true`, this module is not part of the public API, but it contains
     /// items that are re-exported as public API.
@@ -484,17 +500,20 @@ pub struct Union {
     /// 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<Id>,
     /// All impls (both of traits and inherent) for this union.
+    ///
     /// All of the corresponding [`Item`]s are of kind [`ItemEnum::Impl`].
     pub impls: Vec<Id>,
 }
 
-/// A structure.
+/// A `struct`.
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Struct {
-    /// The kind of struct.
+    /// The kind of the struct (e.g. unit, tuple-like or struct-like) and the data specific to it,
+    /// i.e. fields.
     pub kind: StructKind,
     /// The generic parameters and where clauses on this struct.
     pub generics: Generics,
@@ -503,7 +522,7 @@ pub struct Struct {
     pub impls: Vec<Id>,
 }
 
-/// The kind of a struct and the data specific to it, e.g. fields.
+/// The kind of a [`Struct`] and the data specific to it, i.e. fields.
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum StructKind {
@@ -532,6 +551,7 @@ pub enum StructKind {
     /// ```
     Plain {
         /// The list of fields in the struct.
+        ///
         /// All of the corresponding [`Item`]s are of kind [`ItemEnum::StructField`].
         fields: Vec<Id>,
         /// Whether any fields have been removed from the result, due to being private or hidden.
@@ -546,9 +566,11 @@ pub struct 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.
+    /// The list of variants in the enum.
+    ///
+    /// All of the corresponding [`Item`]s are of kind [`ItemEnum::Variant`]
     pub variants: Vec<Id>,
-    /// Implementations for the enum.
+    /// `impl`s for the enum.
     pub impls: Vec<Id>,
 }
 
@@ -561,7 +583,7 @@ pub struct Variant {
     pub discriminant: Option<Discriminant>,
 }
 
-/// The kind of an enum variant and the data specific to it, e.g. fields.
+/// The kind of an [`Enum`] [`Variant`] and the data specific to it, i.e. fields.
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum VariantKind {
@@ -623,10 +645,9 @@ pub struct Discriminant {
 }
 
 /// 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?
+    /// Is this function marked as `const`?
     #[serde(rename = "const")]
     pub const_: bool,
     /// Is this function unsafe?
@@ -709,8 +730,7 @@ pub struct GenericParamDef {
     pub kind: GenericParamDefKind,
 }
 
-/// The kind of a generic parameter.
-/// See [`GenericParamDef`].
+/// The kind of a [`GenericParamDef`].
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum GenericParamDefKind {
@@ -909,7 +929,7 @@ pub enum Type {
     DynTrait(DynTrait),
     /// Parameterized types. The contained string is the name of the parameter.
     Generic(String),
-    /// Built-in types, such as the integers, floating-point numbers, `bool`, and `char`.
+    /// Built-in types, such as the integers, floating-point numbers, `bool`, `char`.
     Primitive(String),
     /// A function pointer type, e.g. `fn(u32) -> u32`, `extern "C" fn() -> *const u8`
     FunctionPointer(Box<FunctionPointer>),
@@ -927,6 +947,7 @@ pub enum Type {
         len: String,
     },
     /// A pattern type, e.g. `u32 is 1..`
+    ///
     /// See [the tracking issue](https://github.com/rust-lang/rust/issues/123646)
     Pat {
         /// The base type, e.g. the `u32` in `u32 is 1..`
@@ -951,9 +972,9 @@ pub enum Type {
     BorrowedRef {
         /// The name of the lifetime of the reference, if provided.
         lifetime: Option<String>,
-        /// This is `true` for `&mut _` and `false` for `&_`
+        /// This is `true` for `&mut i32` and `false` for `&i32`
         mutable: bool,
-        /// The type of the pointee.
+        /// The type of the pointee, e.g. the `i32` in `&'a mut i32`
         #[serde(rename = "type")]
         type_: Box<Type>,
     },
@@ -1054,7 +1075,7 @@ pub struct Trait {
     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.
+    /// Associated [`Item`]s that can/must be implemented by the `impl` blocks.
     pub items: Vec<Id>,
     /// Information about the type parameters and `where` clauses of the trait.
     pub generics: Generics,
@@ -1065,6 +1086,7 @@ pub struct Trait {
 }
 
 /// A trait alias declaration, e.g. `trait Int = Add + Sub + Mul + Div;`
+///
 /// See [the tracking issue](https://github.com/rust-lang/rust/issues/41517)
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct TraitAlias {
@@ -1108,12 +1130,17 @@ pub struct Impl {
     /// 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<T, U> Into<U> for T` this field would be `"T"`.
+    /// If this is a blanket impl, the name with which [`for_`] is referred to in the original impl.
+    ///
+    /// E.g., for `impl<T, U> Into<U> for T` this field would be `T`.
+    ///
+    /// The contained [`Type`], if present, is always of kind [`Type::Generic`]
+    ///
+    /// [`for_`]: Impl::for_
     pub blanket_impl: Option<Type>,
 }
 
-/// An import of an item into scope.
+/// A `use` statement.
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub struct Import {
@@ -1127,7 +1154,7 @@ pub struct Import {
     /// pub use i32 as my_i32;
     /// ```
     pub id: Option<Id>,
-    /// Whether this import uses a glob: `use source::*;`
+    /// Whether this statement is a wildcard `use`, e.g. `use source::*;`
     pub glob: bool,
 }
 
@@ -1136,13 +1163,25 @@ pub struct Import {
 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.
+    /// Helper attributes defined by a macro to be used inside it.
+    ///
+    /// Defined only for attribute & derive macros.
+    ///
+    /// E.g. the [`Default`] derive macro defines a `#[default]` helper attribute so that one can
+    /// do:
+    ///
+    /// ```rust
+    /// #[derive(Default)]
+    /// enum Option<T> {
+    ///     #[default]
+    ///     None,
+    ///     Some(T),
+    /// }
+    /// ```
     pub helpers: Vec<String>,
 }
 
-/// The way a procedural macro is declared to be used.
-/// See [`ProcMacro`]
+/// The way a [`ProcMacro`] is declared to be used.
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum MacroKind {
@@ -1170,23 +1209,24 @@ pub struct OpaqueTy {
     pub generics: Generics,
 }
 
-/// A global variable declaration.
+/// A `static` 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.
+    /// 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.
+    /// The name of the type.
     pub name: String,
     /// The implementations, inherent and of traits, on the primitive type.
     pub impls: Vec<Id>,