doc: silence rustdoc intra-doc warnings (private-item links and palette/surface ambiguities)
`cargo doc --no-deps` was emitting eight warnings about intra-doc links resolving to private items or ambiguous fn/module names. None reflect a behaviour bug; they were just noise that cluttered the docs build output. Five of the warnings came from doc comments that cross-referenced items not in the rendered public API. `widget::scroll::Scroll` (struct), `Scroll::horizontal`, `Scroll::both`, `event_loop::text_editing` (module) and `text_shaping` (module) are all `pub` in their own modules, but the `widget` and `event_loop` parents are private to the crate root, so rustdoc treats them as private when resolving links from items that ARE on the public surface (`ScrollAxis`, the `scroll` constructor, `font_bytes`, the `text_edit` module docs). The fix is to drop the link syntax for those references: keep the identifier in backticks (so it still renders as code) but remove the surrounding `[...]` so rustdoc doesn't try to resolve it. Where the cross-reference had no semantic load beyond "see this module", the prose is rephrased to name the module without trying to link to it (e.g. "the `event_loop::text_editing` private module", "see the `text_shaping` private module"). The remaining three warnings were `palette` / `surface` linking ambiguously between a module of that name and a function of the same name within `crate::theme`. Adding `()` after the identifier inside the brackets (`palette` → `palette()`, `surface` → `surface()`) disambiguates to the function, which is the intent in all three sites — the surrounding text talks about "per-slot shorthand accessors", which is what the functions are. After this `cargo doc --no-deps` runs clean with no warnings.
This commit is contained in:
@@ -138,7 +138,7 @@ pub struct GlesCanvas
|
|||||||
/// theme registry.
|
/// theme registry.
|
||||||
pub font: Arc<Font>,
|
pub font: Arc<Font>,
|
||||||
/// Raw bytes of the default font. Required by rustybuzz for
|
/// Raw bytes of the default font. Required by rustybuzz for
|
||||||
/// HarfBuzz shaping (see [`crate::text_shaping`]). Kept on the
|
/// HarfBuzz shaping (see the `text_shaping` private module). Kept on the
|
||||||
/// canvas so the shape pipeline has direct access without a
|
/// canvas so the shape pipeline has direct access without a
|
||||||
/// global lookup.
|
/// global lookup.
|
||||||
pub font_bytes: Arc<Vec<u8>>,
|
pub font_bytes: Arc<Vec<u8>>,
|
||||||
|
|||||||
@@ -126,7 +126,7 @@ pub fn active_mode() -> ThemeMode
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// The currently loaded theme document. Use this for slot-typed lookups
|
/// The currently loaded theme document. Use this for slot-typed lookups
|
||||||
/// when the per-slot helpers ([`crate::theme::color`], [`crate::theme::surface`], …) are not
|
/// when the per-slot helpers ([`crate::theme::color`], [`crate::theme::surface()`], …) are not
|
||||||
/// expressive enough — e.g. iterating `mode.slots.entries`.
|
/// expressive enough — e.g. iterating `mode.slots.entries`.
|
||||||
pub fn active_document() -> Arc<ThemeDocument>
|
pub fn active_document() -> Arc<ThemeDocument>
|
||||||
{
|
{
|
||||||
|
|||||||
@@ -32,7 +32,7 @@
|
|||||||
//! state. Use [`set_active_document`] / [`set_active_mode`] to change it,
|
//! state. Use [`set_active_document`] / [`set_active_mode`] to change it,
|
||||||
//! and [`active_document`] / [`active_mode`] / [`active_theme_id`] to read
|
//! and [`active_document`] / [`active_mode`] / [`active_theme_id`] to read
|
||||||
//! it back. Per-slot shorthand accessors ([`color`], [`paint()`], [`surface()`],
|
//! it back. Per-slot shorthand accessors ([`color`], [`paint()`], [`surface()`],
|
||||||
//! [`palette`], …) cover the common patterns without going through the
|
//! [`palette()`], …) cover the common patterns without going through the
|
||||||
//! full document.
|
//! full document.
|
||||||
//!
|
//!
|
||||||
//! There is **no in-code fallback**: if `ensure_active` cannot locate the
|
//! There is **no in-code fallback**: if `ensure_active` cannot locate the
|
||||||
|
|||||||
@@ -51,7 +51,7 @@ impl Palette
|
|||||||
/// (`bg-page`, `surface`, `surface-alt`, `text-primary`,
|
/// (`bg-page`, `surface`, `surface-alt`, `text-primary`,
|
||||||
/// `text-secondary`, `accent`, `divider`, `icon`). Missing slots
|
/// `text-secondary`, `accent`, `divider`, `icon`). Missing slots
|
||||||
/// fall back to a documented sensible default so downstream widgets
|
/// fall back to a documented sensible default so downstream widgets
|
||||||
/// never see uninitialised colours. Used by [`crate::theme::palette`] and
|
/// never see uninitialised colours. Used by [`crate::theme::palette()`] and
|
||||||
/// [`crate::theme::window_controls`].
|
/// [`crate::theme::window_controls`].
|
||||||
pub fn from_slots( slots: &SlotStore ) -> Self
|
pub fn from_slots( slots: &SlotStore ) -> Self
|
||||||
{
|
{
|
||||||
|
|||||||
@@ -8,7 +8,7 @@ use crate::widget::Element;
|
|||||||
#[cfg(test)]
|
#[cfg(test)]
|
||||||
mod tests;
|
mod tests;
|
||||||
|
|
||||||
/// Which axes a [`Scroll`] viewport allows to move along. Determines
|
/// Which axes a `Scroll` viewport allows to move along. Determines
|
||||||
/// whether the layout grows the child past the viewport width, the
|
/// whether the layout grows the child past the viewport width, the
|
||||||
/// viewport height, or both, and which axis gesture / wheel deltas
|
/// viewport height, or both, and which axis gesture / wheel deltas
|
||||||
/// route to.
|
/// route to.
|
||||||
@@ -139,7 +139,7 @@ pub(crate) fn clamp_offset( offset: f32, content_h: f32, viewport_h: f32 ) -> f3
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// Create a scrollable viewport wrapping `child`. Defaults to vertical
|
/// Create a scrollable viewport wrapping `child`. Defaults to vertical
|
||||||
/// scrolling; chain [`Scroll::horizontal`] or [`Scroll::both`] to
|
/// scrolling; chain `Scroll::horizontal` or `Scroll::both` to
|
||||||
/// switch axes.
|
/// switch axes.
|
||||||
///
|
///
|
||||||
/// The parent layout controls the viewport size by assigning a rect to
|
/// The parent layout controls the viewport size by assigning a rect to
|
||||||
|
|||||||
@@ -4,7 +4,7 @@
|
|||||||
//! Text input field — single-line or multiline. The widget itself
|
//! Text input field — single-line or multiline. The widget itself
|
||||||
//! owns layout / draw; the runtime side of text editing
|
//! owns layout / draw; the runtime side of text editing
|
||||||
//! (insert, delete, cursor movement, selection, clipboard)
|
//! (insert, delete, cursor movement, selection, clipboard)
|
||||||
//! lives in [`crate::event_loop::text_editing`].
|
//! lives in the `event_loop::text_editing` private module.
|
||||||
|
|
||||||
use std::sync::Arc;
|
use std::sync::Arc;
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user