Fix private docs (#326)

## Synopsis

We do have quite a rich private documentation, which helps to understand
and navigate code. However, it has never been checked on CI, so many
intra-doc links are just broken.


## Solution

- Check private Rust docs on CI to build OK.
- Fix the broken intra-doc links in private docs.

Author: tyranron

.github/workflows/ci.yml

@@ -145,18 +145,23 @@ jobs:
   #################
 
   rustdoc:
+    name: rustdoc${{ matrix.opts != '' && ' (private)' || '' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        opts: ["", "--document-private-items"]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@v1
         with:
           toolchain: nightly
 
-      - run: cargo +nightly doc -p derive_more-impl --features full
+      - run: cargo +nightly doc -p derive_more-impl --features full ${{ matrix.opts }}
         env:
           RUSTDOCFLAGS: --cfg docsrs --cfg ci
 
-      - run: cargo +nightly doc -p derive_more --features full
+      - run: cargo +nightly doc -p derive_more --features full ${{ matrix.opts }}
         env:
           RUSTDOCFLAGS: --cfg docsrs --cfg ci
 

impl/src/as/mod.rs

@@ -148,15 +148,19 @@ pub fn expand(
 /// - [`syn::Ident`] of the derived trait.
 /// - [`syn::Ident`] of the derived trait method.
 /// - Optional `mut` token indicating [`AsMut`] expansion.
+///
+/// [`syn::Ident`]: struct@syn::Ident
 type ExpansionCtx<'a> = (&'a syn::Ident, &'a syn::Ident, Option<&'a Token![mut]>);
 
 /// Expansion of a macro for generating [`AsRef`]/[`AsMut`] implementations for a single field of a
 /// struct.
 struct Expansion<'a> {
-    /// [`ExpansionCtx] of the derived trait.
+    /// [`ExpansionCtx`] of the derived trait.
     trait_info: ExpansionCtx<'a>,
 
     /// [`syn::Ident`] of the struct.
+    ///
+    /// [`syn::Ident`]: struct@syn::Ident
     ident: &'a syn::Ident,
 
     /// [`syn::Generics`] of the struct.

impl/src/fmt/display.rs

@@ -67,6 +67,8 @@ pub fn expand(input: &syn::DeriveInput, trait_name: &str) -> syn::Result<TokenSt
 /// - Struct/enum/union [`syn::Ident`].
 /// - Derived trait [`syn::Ident`].
 /// - Attribute name [`syn::Ident`].
+///
+/// [`syn::Ident`]: struct@syn::Ident
 type ExpansionCtx<'a> = (
     &'a ContainerAttributes,
     &'a syn::Ident,
@@ -202,12 +204,16 @@ struct Expansion<'a> {
     attrs: &'a ContainerAttributes,
 
     /// Struct or enum [`syn::Ident`].
+    ///
+    /// [`syn::Ident`]: struct@syn::Ident
     ident: &'a syn::Ident,
 
     /// Struct or enum [`syn::Fields`].
     fields: &'a syn::Fields,
 
     /// [`fmt`] trait [`syn::Ident`].
+    ///
+    /// [`syn::Ident`]: struct@syn::Ident
     trait_ident: &'a syn::Ident,
 }
 
@@ -220,6 +226,7 @@ impl<'a> Expansion<'a> {
     /// greater than 1.
     ///
     /// [`Display::fmt()`]: fmt::Display::fmt()
+    /// [`FmtAttribute`]: super::FmtAttribute
     fn generate_body(&self) -> syn::Result<TokenStream> {
         match &self.attrs.fmt {
             Some(fmt) => {

impl/src/fmt/mod.rs

@@ -101,6 +101,8 @@ struct FmtAttribute {
     lit: syn::LitStr,
 
     /// Optional [`token::Comma`].
+    ///
+    /// [`token::Comma`]: struct@token::Comma
     comma: Option<token::Comma>,
 
     /// Interpolation arguments.
@@ -414,6 +416,8 @@ impl Placeholder {
 ///
 /// `#[<attribute>(...)]` can be specified only once, while multiple `#[<attribute>(bound(...))]`
 /// are allowed.
+///
+/// [`fmt::Display`]: std::fmt::Display
 #[derive(Debug, Default)]
 struct ContainerAttributes {
     /// Interpolation [`FmtAttribute`].
@@ -468,7 +472,7 @@ impl attr::ParseMultiple for ContainerAttributes {
     }
 }
 
-/// Matches the provided `trait_name` to appropriate [`Attribute::Fmt`] argument name.
+/// Matches the provided `trait_name` to appropriate [`FmtAttribute`]'s argument name.
 fn trait_name_to_attribute_name<T>(trait_name: T) -> &'static str
 where
     T: for<'a> PartialEq<&'a str>,

impl/src/from.rs

@@ -120,9 +120,13 @@ struct Expansion<'a> {
     attrs: Option<&'a VariantAttribute>,
 
     /// Struct or enum [`syn::Ident`].
+    ///
+    /// [`syn::Ident`]: struct@syn::Ident
     ident: &'a syn::Ident,
 
     /// Variant [`syn::Ident`] in case of enum expansion.
+    ///
+    /// [`syn::Ident`]: struct@syn::Ident
     variant: Option<&'a syn::Ident>,
 
     /// Struct or variant [`syn::Fields`].
@@ -132,7 +136,7 @@ struct Expansion<'a> {
     generics: &'a syn::Generics,
 
     /// Indicator whether one of the enum variants has
-    /// [`VariantAttribute::From`], [`VariantAttribute::Types`] or
+    /// [`VariantAttribute::Empty`], [`VariantAttribute::Types`] or
     /// [`VariantAttribute::Forward`].
     ///
     /// Always [`false`] for structs.
@@ -254,6 +258,9 @@ impl<'a> Expansion<'a> {
     /// Expands fields initialization wrapped into [`token::Brace`]s in case of
     /// [`syn::FieldsNamed`], or [`token::Paren`] in case of
     /// [`syn::FieldsUnnamed`].
+    ///
+    /// [`token::Brace`]: struct@token::Brace
+    /// [`token::Paren`]: struct@token::Paren
     fn expand_fields(
         &self,
         mut wrap: impl FnMut(

impl/src/into.rs

@@ -109,6 +109,8 @@ pub fn expand(input: &syn::DeriveInput, _: &'static str) -> syn::Result<TokenStr
 /// Expansion of an [`Into`] derive macro, generating [`From`] implementations for a struct.
 struct Expansion<'a> {
     /// [`syn::Ident`] of the struct.
+    ///
+    /// [`syn::Ident`]: struct@syn::Ident
     input_ident: &'a syn::Ident,
 
     /// [`syn::Generics`] of the struct.
@@ -306,13 +308,13 @@ struct Conversions {
 /// ```
 #[derive(Clone, Debug)]
 struct ConversionsAttribute {
-    /// [`Type`]s wrapped into `owned(...)` or simply `#[into(...)]`.
+    /// [`syn::Type`]s wrapped into `owned(...)` or simply `#[into(...)]`.
     owned: Conversions,
 
-    /// [`Type`]s wrapped into `ref(...)`.
+    /// [`syn::Type`]s wrapped into `ref(...)`.
     r#ref: Conversions,
 
-    /// [`Type`]s wrapped into `ref_mut(...)`.
+    /// [`syn::Type`]s wrapped into `ref_mut(...)`.
     ref_mut: Conversions,
 }
 
@@ -463,6 +465,8 @@ where
 }
 
 /// [`Error`]ors for legacy syntax: `#[into(types(i32, "&str"))]`.
+///
+/// [`Error`]: syn::Error
 fn check_legacy_syntax<'a, F>(tokens: ParseStream<'_>, fields: &'a F) -> syn::Result<()>
 where
     F: FieldsExt + ?Sized,

impl/src/parsing.rs

@@ -22,7 +22,9 @@ pub(crate) enum Expr {
 }
 
 impl Expr {
-    /// Returns an [`Ident`] in case this [`Expr`] is represented only by it.
+    /// Returns a [`syn::Ident`] in case this [`Expr`] is represented only by it.
+    ///
+    /// [`syn::Ident`]: struct@syn::Ident
     pub(crate) fn ident(&self) -> Option<&syn::Ident> {
         match self {
             Self::Ident(ident) => Some(ident),
@@ -50,12 +52,12 @@ impl Parse for Expr {
                 take_until1(
                     alt([
                         &mut seq([
-                            &mut colon2,
+                            &mut path_sep,
                             &mut balanced_pair(punct('<'), punct('>')),
                         ]),
                         &mut seq([
                             &mut balanced_pair(punct('<'), punct('>')),
-                            &mut colon2,
+                            &mut path_sep,
                         ]),
                         &mut balanced_pair(punct('|'), punct('|')),
                         &mut token_tree,
@@ -81,8 +83,10 @@ impl ToTokens for Expr {
 /// Result of parsing.
 type ParsingResult<'a> = Option<(TokenStream, Cursor<'a>)>;
 
-/// Tries to parse a [`syn::token::Colon2`].
-pub fn colon2(c: Cursor<'_>) -> ParsingResult<'_> {
+/// Tries to parse a [`token::PathSep`].
+///
+/// [`token::PathSep`]: struct@syn::token::PathSep
+pub fn path_sep(c: Cursor<'_>) -> ParsingResult<'_> {
     seq([
         &mut punct_with_spacing(':', Spacing::Joint),
         &mut punct(':'),

impl/src/try_from.rs

@@ -61,6 +61,8 @@ struct Expansion {
     attr: Option<ItemAttribute>,
 
     /// [`syn::Ident`] of the enum.
+    ///
+    /// [`syn::Ident`]: struct@syn::Ident
     ident: syn::Ident,
 
     /// [`syn::Generics`] of the enum.

impl/src/utils.rs

@@ -1780,6 +1780,7 @@ pub(crate) mod attr {
             /// If there is no explicitly specified  primitive integer type, then returns a
             /// [default `isize` discriminant][0].
             ///
+            /// [`syn::Ident`]: struct@syn::Ident
             /// [0]: https://doc.rust-lang.org/reference/items/enumerations.html#discriminants
             pub(crate) fn ty(&self) -> syn::Ident {
                 self.0
@@ -2216,7 +2217,7 @@ mod fields_ext {
 
     /// [`syn::Fields`] extension.
     pub(crate) trait FieldsExt: Len {
-        /// Validates the provided [`parsing::Type`] against these [`syn::Fields`].
+        /// Validates the provided [`syn::Type`] against these [`syn::Fields`].
         fn validate_type<'t>(
             &self,
             ty: &'t syn::Type,