fix rustdoc-json-types docs, remove missing_docs warning

Author: its-the-shrimp

src/rustdoc-json-types/lib.rs

@@ -3,16 +3,16 @@
 //! 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;
 
 /// rustdoc format-version.
 pub const FORMAT_VERSION: u32 = 31;
 
-/// A `Crate` is the root of the emitted JSON blob. It contains all type/documentation information
+/// The root of the emitted JSON blob.
+///
+/// It contains all type/documentation information
 /// about the language items in the local crate, as well as info about external items to allow
 /// tools to find or link to them.
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
@@ -44,7 +44,9 @@ pub struct ExternalCrate {
     pub html_root_url: Option<String>,
 }
 
-/// For external (not defined in the local crate) items, you don't get the same level of
+/// Information about an external (not defined in the local crate) [`Item`].
+///
+/// For external items, you don't get the same level of
 /// information. This struct should contain enough to generate a link/reference to the item in
 /// question, or can be used by a tool that takes the json output of multiple crates to find
 /// the actual item definition with all the relevant info.
@@ -65,8 +67,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,
+/// Anything that can hold documentation - modules, structs, enums, functions, traits, etc.
+///
+/// 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 {
@@ -107,7 +110,7 @@ pub struct Span {
     pub end: (usize, usize),
 }
 
-/// Information about the deprecation of an API entry.
+/// 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.
@@ -116,7 +119,7 @@ pub struct Deprecation {
     pub note: Option<String>,
 }
 
-/// Visibility of an API entry.
+/// Visibility of an [`Item`].
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum Visibility {
@@ -162,13 +165,11 @@ pub struct PolyTrait {
     /// ```text
     /// dyn for<'a> Fn() -> &'a i32"
     ///     ^^^^^^^
-    ///       |
-    ///       this part
     /// ```
     pub generic_params: Vec<GenericParamDef>,
 }
 
-/// A set of generic parameters provided to a path segment, e.g.
+/// A set of generic arguments provided to a path segment, e.g.
 ///
 /// ```text
 /// std::option::Option::<u32>::None
@@ -314,21 +315,20 @@ pub enum ItemKind {
     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
+    /// See [the tracking issue](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
+    /// See [the tracking issue](https://github.com/rust-lang/rust/issues/43467)
     ForeignType,
     /// A macro declaration.
     /// Corresponds to either `ItemEnum::Macro(_)`
@@ -385,14 +385,13 @@ pub enum ItemEnum {
     /// 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
+    /// See [the tracking issue](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 {
@@ -408,7 +407,7 @@ pub enum ItemEnum {
     Static(Static),
 
     /// `type`s from an `extern` block.
-    /// See https://github.com/rust-lang/rust/issues/43467
+    /// See [the tracking issue](https://github.com/rust-lang/rust/issues/43467)
     ForeignType,
 
     /// A macro_rules! declarative macro. Contains a single string with the source
@@ -434,7 +433,7 @@ pub enum ItemEnum {
     },
     /// An associated type of a trait or a type.
     AssocType {
-        /// The generic arguments and where clauses on ahis associated type.
+        /// The generic parameters and where clauses on ahis associated type.
         generics: Generics,
         /// The bounds for this associated type. e.g.
         /// ```rust
@@ -471,7 +470,7 @@ pub struct Module {
 /// A `union`.
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Union {
-    /// The generic arguments and where clauses on this union.
+    /// The generic parameters 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,
@@ -488,7 +487,7 @@ pub struct Union {
 pub struct Struct {
     /// The kind of struct.
     pub kind: StructKind,
-    /// The generic arguments and where clauses on this union.
+    /// The generic parameters and where clauses on this struct.
     pub generics: Generics,
     /// All impls (both of traits and inherent) for this struct.
     /// All of the corresponding [`Item`]s are of kind [`ItemEnum::Impl`].
@@ -531,7 +530,7 @@ pub enum StructKind {
     },
 }
 
-/// An enumeration.
+/// An `enum`.
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Enum {
     /// Information about the type parameters and `where` clauses of the enum.
@@ -596,7 +595,7 @@ pub enum VariantKind {
     },
 }
 
-/// The value that distinguishes a variant in an enum from other variants.
+/// 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.
@@ -631,53 +630,36 @@ pub struct Header {
     pub abi: Abi,
 }
 
-/// The calling convention used by a function.
+/// The ABI (Application Binary Interface) used by a function.
+///
+/// If a variant has an `unwind` field, this means the ABI that it represents can be specified in 2
+/// ways: `extern "_"` and `extern "_-unwind"`, and a value of `true` for that field signifies the
+/// latter variant.
+///
+/// See the [Rustonomicon section](https://doc.rust-lang.org/nightly/nomicon/ffi.html#ffi-and-unwinding)
+/// on unwinding for more info.
 #[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,
     /// 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,
-    },
+    C { unwind: bool },
     /// Can be specified as `extern "cdecl"`.
-    Cdecl {
-        /// If this is `true`, the ABI was specified as `extern "cdecl-unwind"`
-        unwind: bool,
-    },
+    Cdecl { unwind: bool },
     /// Can be specified as `extern "stdcall"`.
-    Stdcall {
-        /// If this is `true`, the ABI was specified as `extern "stdcall-unwind"`.
-        unwind: bool,
-    },
+    Stdcall { unwind: bool },
     /// Can be specified as `extern "fastcall"`.
-    Fastcall {
-        /// If this is `true`, the ABI was specified as `extern "fastcall-unwind"`.
-        unwind: bool,
-    },
+    Fastcall { unwind: bool },
     /// Can be specified as `extern "aapcs"`.
-    Aapcs {
-        /// If this is `true`, the ABI was specified as `extern "aapcs-unwind"`.
-        unwind: bool,
-    },
+    Aapcs { unwind: bool },
     /// Can be specified as `extern "win64"`.
-    Win64 {
-        /// If this is `true`, the ABI was specified as `extern "win64-unwind"`.
-        unwind: bool,
-    },
+    Win64 { unwind: bool },
     /// Can be specifed as `extern "sysv64"`.
-    SysV64 {
-        /// If this is `true`, the ABI was specified as `extern "sysv64-unwind"`.
-        unwind: bool,
-    },
+    SysV64 { unwind: bool },
     /// Can be specified as `extern "system"`.
-    System {
-        /// If this is `true`, the ABI was specified as `extern "system-unwind"`.
-        unwind: bool,
-    },
+    System { unwind: bool },
     /// Any other ABI, including unstable ones.
     Other(String),
 }
@@ -725,7 +707,7 @@ pub struct GenericParamDef {
 pub enum GenericParamDefKind {
     /// Denotes a lifetime parameter.
     Lifetime {
-        /// Lifetimes that this lifetime parameter is require to outlive.
+        /// Lifetimes that this lifetime parameter is required to outlive.
         ///
         /// ```rust
         /// fn f<'a, 'b, 'resource: 'a + 'b>(a: &'a str, b: &'b str, res: &'resource str) {}
@@ -934,7 +916,7 @@ pub enum Type {
         len: String,
     },
     /// A pattern type, e.g. `u32 is 1..`
-    /// See https://github.com/rust-lang/rust/issues/123646
+    /// See [the tracking issue](https://github.com/rust-lang/rust/issues/123646)
     Pat {
         /// The base type, e.g. the `u32` in `u32 is 1..`
         #[serde(rename = "type")]
@@ -974,7 +956,7 @@ pub enum Type {
         /// //                                            ^^^^
         /// ```
         name: String,
-        /// The generic parameters provided to the associated type.
+        /// The generic arguments provided to the associated type.
         ///
         /// ```ignore (incomplete expression)
         /// <core::slice::IterMut<'static, u32> as BetterIterator>::Item<'static>
@@ -1073,7 +1055,7 @@ pub struct Trait {
 }
 
 /// A trait alias declaration, e.g. `trait Int = Add + Sub + Mul + Div;`
-/// See https://github.com/rust-lang/rust/issues/41517
+/// See [the tracking issue](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.
@@ -1082,7 +1064,7 @@ pub struct TraitAlias {
     pub params: Vec<GenericBound>,
 }
 
-/// An implementation.
+/// An `impl` block.
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Impl {
     /// Whether this impl is for an unsafe trait.
@@ -1172,7 +1154,6 @@ pub struct TypeAlias {
     pub generics: Generics,
 }
 
-#[allow(missing_docs)]
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct OpaqueTy {
     pub bounds: Vec<GenericBound>,