Merge pull request #451 from kas-gui/work1

Use doc_auto_cfg; small doc and feature tweaks

Cargo.toml

@@ -15,9 +15,9 @@ rust-version = "1.75.0"
 
 [package.metadata.docs.rs]
 features = ["stable"]
-rustdoc-args = ["--cfg", "doc_cfg"]
+rustdoc-args = ["--cfg", "docsrs"]
 # To build locally:
-# RUSTDOCFLAGS="--cfg doc_cfg" cargo +nightly doc --features=stable,internal_doc --all --no-deps --open
+# RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --features=stable,internal_doc --all --no-deps --open
 
 [features]
 #########  meta / build features  #########
@@ -84,7 +84,7 @@ ron = ["serde", "kas-core/ron"]
 toml = ["serde", "kas-core/toml"]
 
 # Support image loading and decoding
-image = ["kas-widgets/image"]
+image = ["kas-core/image", "kas-widgets/image"]
 
 # Enable resvg module (Canvas + Svg widgets)
 resvg = ["dep:kas-resvg", "kas-resvg?/svg", "kas-dylib?/resvg"]

crates/kas-core/Cargo.toml

@@ -14,14 +14,14 @@ exclude = ["/screenshots"]
 
 [package.metadata.docs.rs]
 features = ["stable"]
-rustdoc-args = ["--cfg", "doc_cfg"]
+rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
 # The minimal feature set needed to build basic applications (with assumptions
 # about target platforms).
 minimal = ["winit", "wayland"]
 # All standard test target features
-stable = ["minimal", "clipboard", "markdown", "shaping", "spawn", "x11", "serde", "toml", "yaml", "json", "ron", "macros_log"]
+stable = ["minimal", "clipboard", "markdown", "shaping", "spawn", "x11", "serde", "toml", "yaml", "json", "ron", "macros_log", "image"]
 # Enables all "recommended" features for nightly rustc
 nightly = ["stable"]
 # Additional, less recommendation-worthy features
@@ -73,6 +73,9 @@ x11 = ["winit?/x11"]
 # Enable serde integration (mainly config read/write)
 serde = ["dep:serde", "kas-text/serde", "winit?/serde"]
 
+# Enable load_icon_from_path utility function
+image = ["dep:image"]
+
 # Automatically detect usage of dark theme
 dark-light = ["dep:dark-light"]
 
@@ -106,6 +109,7 @@ raw-window-handle = "0.6.0"
 async-global-executor = { version = "2.3.1", optional = true }
 cfg-if = "1.0.0"
 smol_str = "0.2.0"
+image = { version = "0.25.1", optional = true }
 
 [target.'cfg(any(target_os="linux", target_os="dragonfly", target_os="freebsd", target_os="netbsd", target_os="openbsd"))'.dependencies]
 smithay-clipboard = { version = "0.7.0", optional = true }

crates/kas-core/src/action.rs

@@ -48,19 +48,19 @@ bitflags! {
         ///
         /// Implies [`Action::RESIZE`].
         #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-        #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+        #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
         const THEME_UPDATE = 1 << 10;
         /// Reload per-window cache of event configuration
         ///
         /// Implies [`Action::UPDATE`].
         #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-        #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+        #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
         const EVENT_CONFIG = 1 << 11;
         /// Switch themes, replacing theme-window instances
         ///
         /// Implies [`Action::RESIZE`].
         #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-        #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+        #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
         const THEME_SWITCH = 1 << 12;
         /// Reconfigure all widgets of the window
         ///

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

@@ -32,7 +32,7 @@ impl_scope! {
     impl Self {
         /// Construct from a graphics backend and a theme
         #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-        #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+        #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
         pub fn new(graphical: G, theme: T) -> Self {
             AppBuilder {
                 graphical,
@@ -100,15 +100,15 @@ impl_scope! {
     }
 }
 
-/// Application associated types
+/// Inherenet associated types of [`Application`]
 ///
 /// Note: these could be inherent associated types of [`Application`] when Rust#8995 is stable.
-pub trait AppAssoc {
+pub trait ApplicationInherent {
     /// Shared draw state type
     type DrawShared: DrawSharedImpl;
 }
 
-impl<A: AppData, G: AppGraphicsBuilder, T> AppAssoc for Application<A, G, T>
+impl<A: AppData, G: AppGraphicsBuilder, T> ApplicationInherent for Application<A, G, T>
 where
     T: Theme<G::Shared> + 'static,
     T::Window: theme::Window,

crates/kas-core/src/app/common.rs

@@ -175,8 +175,6 @@ impl Platform {
 /// Builder for a graphics backend
 ///
 /// See also [`Application`](super::Application).
-#[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-#[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
 pub trait AppGraphicsBuilder {
     /// The default theme
     type DefaultTheme: Default + Theme<Self::Shared>;
@@ -203,8 +201,6 @@ pub trait AppGraphicsBuilder {
 }
 
 /// Window graphical surface requirements
-#[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-#[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
 pub trait WindowSurface {
     /// Shared draw state
     type Shared: kas::draw::DrawSharedImpl;

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

@@ -20,12 +20,15 @@ use crate::messages::MessageStack;
 pub(crate) use window::{Window, WindowDataErased};
 
 #[cfg(winit)]
-pub use app::{AppAssoc, AppBuilder, Application, ClosedError, Proxy};
+pub use app::{AppBuilder, Application, ApplicationInherent, ClosedError, Proxy};
+pub use common::{Error, Platform, Result};
+
 #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
+#[cfg_attr(docsrs, doc(cfg(internal_doc)))]
 pub use common::{AppGraphicsBuilder, WindowSurface};
-pub use common::{Error, Platform, Result};
 
 #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
+#[cfg_attr(docsrs, doc(cfg(internal_doc)))]
 pub extern crate raw_window_handle;
 
 /// Application state

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

@@ -249,7 +249,7 @@ impl WindowConfig {
 
     /// Minimum frame time
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     #[inline]
     pub fn frame_dur(&self) -> Duration {
         self.frame_dur

crates/kas-core/src/config/format.rs

@@ -14,32 +14,26 @@ use thiserror::Error;
 #[derive(Error, Debug)]
 pub enum Error {
     #[cfg(feature = "yaml")]
-    #[cfg_attr(doc_cfg, doc(cfg(feature = "yaml")))]
     #[error("config (de)serialisation to YAML failed")]
     Yaml(#[from] serde_yaml::Error),
 
     #[cfg(feature = "json")]
-    #[cfg_attr(doc_cfg, doc(cfg(feature = "json")))]
     #[error("config (de)serialisation to JSON failed")]
     Json(#[from] serde_json::Error),
 
     #[cfg(feature = "ron")]
-    #[cfg_attr(doc_cfg, doc(cfg(feature = "ron")))]
     #[error("config serialisation to RON failed")]
     Ron(#[from] ron::Error),
 
     #[cfg(feature = "ron")]
-    #[cfg_attr(doc_cfg, doc(cfg(feature = "ron")))]
     #[error("config deserialisation from RON failed")]
     RonSpanned(#[from] ron::error::SpannedError),
 
     #[cfg(feature = "toml")]
-    #[cfg_attr(doc_cfg, doc(cfg(feature = "toml")))]
     #[error("config deserialisation from TOML failed")]
     TomlDe(#[from] toml::de::Error),
 
     #[cfg(feature = "toml")]
-    #[cfg_attr(doc_cfg, doc(cfg(feature = "toml")))]
     #[error("config serialisation to TOML failed")]
     TomlSer(#[from] toml::ser::Error),
 

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

@@ -39,7 +39,7 @@ pub struct CoreData {
     pub rect: Rect,
     pub id: Id,
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     #[cfg(debug_assertions)]
     pub status: WidgetStatus,
 }
@@ -63,7 +63,7 @@ impl Clone for CoreData {
 ///
 /// It is not used in release builds.
 #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-#[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+#[cfg_attr(docsrs, doc(cfg(internal_doc)))]
 #[cfg(debug_assertions)]
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord)]
 pub enum WidgetStatus {

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

@@ -14,7 +14,7 @@ mod widget;
 mod widget_id;
 
 #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-#[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+#[cfg_attr(docsrs, doc(cfg(internal_doc)))]
 pub mod impls;
 
 pub use collection::{CellCollection, Collection};

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

@@ -285,7 +285,7 @@ impl<'a> Node<'a> {
 }
 
 #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-#[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+#[cfg_attr(docsrs, doc(cfg(internal_doc)))]
 impl<'a> Node<'a> {
     /// Get size rules for the given axis
     pub(crate) fn size_rules(&mut self, sizer: SizeCx, axis: AxisInfo) -> SizeRules {

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

@@ -242,7 +242,7 @@ pub trait Events: Widget + Sized {
 
 /// Action of Widget::_nav_next
 #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-#[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+#[cfg_attr(docsrs, doc(cfg(internal_doc)))]
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum NavAdvance {
     /// Match only `focus` if navigable
@@ -383,21 +383,21 @@ pub trait Widget: Layout {
     ///
     /// Do not implement this method directly!
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     fn _configure(&mut self, cx: &mut ConfigCx, data: &Self::Data, id: Id);
 
     /// Internal method: update recursively
     ///
     /// Do not implement this method directly!
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     fn _update(&mut self, cx: &mut ConfigCx, data: &Self::Data);
 
     /// Internal method: send recursively
     ///
     /// Do not implement this method directly!
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     fn _send(&mut self, cx: &mut EventCx, data: &Self::Data, id: Id, event: Event) -> IsUsed;
 
     /// Internal method: replay recursively
@@ -407,7 +407,7 @@ pub trait Widget: Layout {
     ///
     /// Do not implement this method directly!
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     fn _replay(&mut self, cx: &mut EventCx, data: &Self::Data, id: Id);
 
     /// Internal method: search for the previous/next navigation target
@@ -416,7 +416,7 @@ pub trait Widget: Layout {
     ///
     /// Do not implement this method directly!
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     fn _nav_next(
         &mut self,
         cx: &mut ConfigCx,

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

@@ -46,13 +46,13 @@ use std::time::Instant;
 /// automatically for structs containing references.)
 pub struct DrawIface<'a, DS: DrawSharedImpl> {
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     pub draw: &'a mut DS::Draw,
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     pub shared: &'a mut SharedState<DS>,
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     pub pass: PassId,
 }
 
@@ -61,7 +61,7 @@ impl<'a, DS: DrawSharedImpl> DrawIface<'a, DS> {
     ///
     /// For usage by graphics backends.
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     pub fn new(draw: &'a mut DS::Draw, shared: &'a mut SharedState<DS>) -> Self {
         DrawIface {
             draw,
@@ -123,7 +123,7 @@ impl<'a, DS: DrawSharedImpl> DrawIface<'a, DS> {
     }
 }
 
-/// Base drawing interface for [`DrawIface`]
+/// Basic draw interface for [`DrawIface`]
 ///
 /// Most methods draw some feature. Exceptions are those starting with `get_`
 /// and [`Self::new_dyn_pass`].
@@ -153,7 +153,7 @@ pub trait Draw {
 
     /// Cast fields to [`Any`] references
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     fn get_fields_as_any_mut(&mut self) -> (&mut dyn Any, &mut dyn Any);
 
     /// Add a draw pass
@@ -301,7 +301,7 @@ impl<'a, DS: DrawSharedImpl> Draw for DrawIface<'a, DS> {
     }
 }
 
-/// Base abstraction over drawing
+/// Implementation target for [`Draw`]
 ///
 /// This trait covers only the bare minimum of functionality which *must* be
 /// provided by the graphics backend; extension traits such as [`DrawRoundedImpl`]
@@ -318,8 +318,6 @@ impl<'a, DS: DrawSharedImpl> Draw for DrawIface<'a, DS> {
 /// Draw operations take place over multiple render passes, identified by a
 /// handle of type [`PassId`]. In general the user only needs to pass this value
 /// into methods as required. [`DrawImpl::new_pass`] creates a new [`PassId`].
-#[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-#[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
 pub trait DrawImpl: Any {
     /// Access common data
     fn common_mut(&mut self) -> &mut WindowCommon;

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

@@ -9,7 +9,7 @@ use super::color::Rgba;
 use super::{Draw, DrawIface, DrawImpl, DrawSharedImpl, PassId};
 use crate::geom::{Quad, Vec2};
 
-/// Extension over [`Draw`] for rounded shapes
+/// Extended draw interface for [`DrawIface`] providing rounded drawing
 ///
 /// All methods draw some feature.
 pub trait DrawRounded: Draw {
@@ -94,15 +94,13 @@ where
     }
 }
 
-/// Drawing commands for rounded shapes
+/// Implementation target for [`DrawRounded`]
 ///
 /// This trait is an extension over [`DrawImpl`] providing rounded shapes.
 ///
 /// The primitives provided by this trait are partially transparent.
 /// If the implementation buffers draw commands, it should draw these
 /// primitives after solid primitives.
-#[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-#[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
 pub trait DrawRoundedImpl: DrawImpl {
     /// Draw a line with rounded ends and uniform colour
     fn rounded_line(&mut self, pass: PassId, p1: Vec2, p2: Vec2, radius: f32, col: Rgba);

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

@@ -38,7 +38,7 @@ impl ImageHandle {
 impl ImageId {
     /// Construct a new identifier from `u32` value not equal to 0
     #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-    #[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+    #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
     #[inline]
     pub const fn try_new(n: u32) -> Option<Self> {
         // We can't use ? or .map in a const fn so do it the tedious way:
@@ -78,7 +78,7 @@ pub struct SharedState<DS: DrawSharedImpl> {
 }
 
 #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-#[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
+#[cfg_attr(docsrs, doc(cfg(internal_doc)))]
 impl<DS: DrawSharedImpl> SharedState<DS> {
     /// Construct (this is only called by the graphics backend)
     pub fn new(draw: DS) -> Self {
@@ -141,11 +141,9 @@ impl<DS: DrawSharedImpl> DrawShared for SharedState<DS> {
     }
 }
 
-/// Trait over shared data of draw object
+/// Implementation target for [`DrawShared`]
 ///
 /// This is typically used via [`SharedState`].
-#[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
-#[cfg_attr(doc_cfg, doc(cfg(internal_doc)))]
 pub trait DrawSharedImpl: Any {
     type Draw: DrawImpl;