Doc fixes, especially for for Text

crates/kas-core/src/draw/draw.rs

@@ -207,8 +207,8 @@ pub trait Draw {
     /// Text is drawn from `rect.pos` and clipped to `rect`. If the text
     /// scrolls, `rect` should be the size of the whole text, not the window.
     ///
-    /// It is required to call [`Text::prepare`] or equivalent
-    /// prior to this method to select a font, font size and perform layout.
+    /// The `text` object must be configured and prepared prior to calling this
+    /// method (see [`crate::theme::Text`] or [`crate::text::Text`]).
     fn text(&mut self, rect: Rect, text: &TextDisplay, col: Rgba);
 
     /// Draw text with a single color and effects
@@ -219,8 +219,8 @@ pub trait Draw {
     /// The effects list does not contain colour information, but may contain
     /// underlining/strikethrough information. It may be empty.
     ///
-    /// It is required to call [`Text::prepare`] or equivalent
-    /// prior to this method to select a font, font size and perform layout.
+    /// The `text` object must be configured and prepared prior to calling this
+    /// method (see [`crate::theme::Text`] or [`crate::text::Text`]).
     fn text_effects(&mut self, rect: Rect, text: &TextDisplay, col: Rgba, effects: &[Effect<()>]);
 
     /// Draw text with effects (including [`Rgba`] color)
@@ -232,8 +232,8 @@ pub trait Draw {
     /// If the `effects` list is empty or the first entry has `start > 0`, a
     /// default entity will be assumed.
     ///
-    /// It is required to call [`Text::prepare`] or equivalent
-    /// prior to this method to select a font, font size and perform layout.
+    /// The `text` object must be configured and prepared prior to calling this
+    /// method (see [`crate::theme::Text`] or [`crate::text::Text`]).
     fn text_effects_rgba(&mut self, rect: Rect, text: &TextDisplay, effects: &[Effect<Rgba>]);
 }
 

crates/kas-core/src/event/cx/config.rs

@@ -125,10 +125,7 @@ impl<'a> ConfigCx<'a> {
 
     /// Configure a text object
     ///
-    /// The [`TextClass`] should be set before calling this method (via
-    /// [`Text::new`] or [`Text::set_class`]).
-    ///
-    /// This selects a font given the [`TextClass`],
+    /// This selects a font given the [`TextClass`][crate::theme::TextClass],
     /// [theme configuration][crate::theme::Config] and
     /// the loaded [fonts][crate::text::fonts].
     #[inline]

crates/kas-core/src/text/mod.rs

@@ -8,11 +8,8 @@
 //! Most of this module is simply a re-export of the [KAS Text] API, hence the
 //! lower level of integration than other parts of the library.
 //!
-//! [`Text`] objects *must* be configured and prepared before usage, otherwise
-//! they may appear empty. Call [`ConfigCx::text_config`] from
-//! [`Events::configure`] and [`ConfigCx::text_set_size`] from
-//! [`Layout::set_rect`] to set text position and prepare.
-//! If text is adjusted, one may use e.g. [`Text::prepare`] to update.
+//! See also [`crate::theme::Text`] which provides better integration with KAS
+//! theming and widget sizing operations.
 //!
 //! [KAS Text]: https://github.com/kas-gui/kas-text/
 

crates/kas-core/src/theme/size.rs

@@ -230,7 +230,7 @@ pub trait ThemeSize {
 
     /// The height of a line of text by class
     ///
-    /// Prefer to use [`Self::text_line_height`] where possible.
+    /// Prefer to use [`SizeCx::text_line_height`] where possible.
     fn line_height(&self, class: TextClass) -> i32;
 
     /// Configure a text object, setting font properties

crates/kas-core/src/theme/text.rs

@@ -6,6 +6,7 @@
 //! Theme-applied Text element
 
 use super::TextClass;
+#[allow(unused)] use super::{DrawCx, SizeCx};
 #[allow(unused)] use crate::event::ConfigCx;
 use crate::layout::AxisInfo;
 use crate::text::fonts::{FaceId, FontId, InvalidFontId};
@@ -16,18 +17,27 @@ use crate::Action;
 /// Text type-setting object (theme aware)
 ///
 /// This struct is a theme-aware variant of [`crate::text::Text`]. It contains:
+/// -   A [`TextClass`]
 /// -   A [`FormattableText`]
 /// -   A [`TextDisplay`]
 /// -   Type-setting configuration. Values have reasonable defaults:
-///     -   The default font will be the first loaded font: see [fonts].
-///     -   The default font size is 16px (the web default).
+///     -   The font is derived from the [`TextClass`] by
+///         [`ConfigCx::text_configure`]. Otherwise, the default font will be
+///         the first loaded font: see [`crate::text::fonts`].
+///     -   The font size is derived from the [`TextClass`] by
+///         [`ConfigCx::text_configure`]. Otherwise, the default font size is
+///         16px (the web default).
 ///     -   Default text direction and alignment is inferred from the text.
-///     -   Line-wrapping requires a call to [`Text::set_wrap_width`].
-///     -   The bounds used for alignment [must be set][Text::set_bounds].
+///     -   The bounds used for alignment and line-wrapping
+///         must be set by calling [`Text::set_bounds`].
 ///
 /// This struct tracks the [`TextDisplay`]'s
 /// [state of preparation][TextDisplay#status-of-preparation] and will perform
-/// steps as required.
+/// steps as required. Normal usage of this struct is as follows:
+/// -   Configure by calling [`ConfigCx::text_configure`]
+/// -   (Optionally) check size requirements by calling [`SizeCx::text_rules`]
+/// -   Set the size and prepare by calling [`ConfigCx::text_set_size`]
+/// -   Draw by calling [`DrawCx::text`] (and/or other text methods)
 #[derive(Clone, Debug)]
 pub struct Text<T: FormattableText + ?Sized> {
     /// Bounds to use for alignment
@@ -169,6 +179,8 @@ impl<T: FormattableText + ?Sized> Text<T> {
 
     /// Set text class
     ///
+    /// This controls line-wrapping, font and font size selection.
+    ///
     /// Default: `TextClass::Label(true)`
     #[inline]
     pub fn set_class(&mut self, class: TextClass) {
@@ -209,7 +221,7 @@ impl<T: FormattableText + ?Sized> Text<T> {
     ///
     /// This is a scaling factor used to convert font sizes, with units
     /// `pixels/Em`. Equivalently, this is the line-height in pixels.
-    /// See [`crate::fonts`] documentation.
+    /// See [`crate::text::fonts`] documentation.
     ///
     /// To calculate this from text size in Points, use `dpem = dpp * pt_size`
     /// where the dots-per-point is usually `dpp = scale_factor * 96.0 / 72.0`