From 0fbce558ff0e759a60a328b980ffc87d04ee85a3 Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Wed, 24 Jan 2024 15:21:44 +0000 Subject: [PATCH] Improve Collection, List docs --- crates/kas-core/src/core/collection.rs | 10 +++++++--- crates/kas-widgets/src/list.rs | 20 ++++++++++++++------ 2 files changed, 21 insertions(+), 9 deletions(-) diff --git a/crates/kas-core/src/core/collection.rs b/crates/kas-core/src/core/collection.rs index fc62d35f5..adade0048 100644 --- a/crates/kas-core/src/core/collection.rs +++ b/crates/kas-core/src/core/collection.rs @@ -10,9 +10,13 @@ use std::ops::RangeBounds; /// A collection of (child) widgets /// -/// Essentially, implementating types are lists of widgets. Simple examples are -/// `Vec` and `[W; N]` where `W: Widget` and `const N: usize`. A more complex -/// example would be a custom struct where each field is a widget. +/// Essentially, a `Collection` is a list of widgets. Notable implementations are: +/// +/// - Slices `[W]` where `W: Widget` +/// - Arrays `[W; N]` where `W: Widget` and `const N: usize` +/// - [`Vec`]`` where `W: Widget` +/// - The output of [`kas::collection!`]. This macro constructs an anonymous +/// struct of widgets which implements `Collection`. pub trait Collection { /// The associated data type type Data; diff --git a/crates/kas-widgets/src/list.rs b/crates/kas-widgets/src/list.rs index 17cf3d02d..88c14954b 100644 --- a/crates/kas-widgets/src/list.rs +++ b/crates/kas-widgets/src/list.rs @@ -27,27 +27,35 @@ pub type Column = List; impl_scope! { /// A generic row/column widget /// - /// A linear widget over a [`Collection`] of widgets, for example an array - /// `[W; N]` or a [`Vec`][Vec] where `const N: usize, W: Widget`. + /// A linear widget over a [`Collection`] of widgets. /// /// When the collection uses [`Vec`], various methods to insert/remove /// elements are available. /// /// The layout direction `D` may be compile-time fixed (e.g. [`Right`]) or - /// run-time mutable [`Direction`]); in the latter case - /// [`set_direction`][List::set_direction] is available. + /// run-time mutable ([`Direction`]); in the latter case + /// [`set_direction`] is available. /// /// ## See also /// - /// Some more specific type-defs are available: + /// [`Row`] and [`Column`] are type-defs to `List` which fix the direction `D`. /// - /// - [`Row`] and [`Column`] fix the direction `D` + /// The macros [`kas::row`] and [`kas::column`] also create row/column + /// layouts, but are not fully equivalent: + /// + /// - `row!` and `column!` generate anonymous layout widgets (or objects). + /// These do not have a [`set_direction`] method or support adding or + /// removing elements. + /// - `row!` and `column!` generate layout objects which, when used within + /// a custom widget, may refer to that widget's fields. /// /// ## Performance /// /// Configuring and resizing elements is O(n) in the number of children. /// Drawing and event handling is O(log n) in the number of children (assuming /// only a small number are visible at any one time). + /// + /// [`set_direction`]: List::set_direction #[autoimpl(Default where C: Default, D: Default)] #[widget] pub struct List {