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.

.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,