From a387adcb1bfb300089cfbbddb8fa8ce91999ac3f Mon Sep 17 00:00:00 2001 From: Michael Aaron Murphy Date: Tue, 15 Aug 2023 10:51:59 +0200 Subject: [PATCH] chore: improve documentation --- src/app/command.rs | 19 ++++--------------- src/app/mod.rs | 23 ++++++++++++++--------- src/app/settings.rs | 3 +++ src/executor/mod.rs | 4 ++++ src/executor/multi.rs | 2 ++ src/executor/single.rs | 2 ++ src/font.rs | 2 ++ src/icon_theme.rs | 2 ++ src/keyboard_nav.rs | 2 ++ src/theme/mod.rs | 2 ++ 10 files changed, 37 insertions(+), 24 deletions(-) diff --git a/src/app/command.rs b/src/app/command.rs index 1997b00..8aa4f9d 100644 --- a/src/app/command.rs +++ b/src/app/command.rs @@ -1,22 +1,11 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 -use std::future::Future; +/// Asynchronous actions for COSMIC applications. +use super::Message; -use super::{Command, Message}; -use iced_runtime::command::Action; - -/// Yields a command which contains a batch of commands. -pub fn batch(commands: impl IntoIterator>) -> Command { - Command::batch(commands) -} - -/// Yields a command which will run the future on the runtime executor. -pub fn future( - future: impl Future> + Send + 'static, -) -> Command { - Command::single(Action::Future(Box::pin(future))) -} +/// Commands for COSMIC applications. +pub type Command = iced::Command>; /// Creates a command which yields a [`crate::app::Message`]. pub fn message(message: Message) -> Command { diff --git a/src/app/mod.rs b/src/app/mod.rs index f37571f..5d98cbd 100644 --- a/src/app/mod.rs +++ b/src/app/mod.rs @@ -1,6 +1,11 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! Build interactive cross-platform COSMIC applications. +//! +//! Check out our [application](https://github.com/pop-os/libcosmic/tree/master/examples/application) +//! example in our repository. + pub mod command; mod core; pub mod cosmic; @@ -9,7 +14,7 @@ pub mod settings; pub mod message { #[derive(Clone, Debug)] #[must_use] - pub enum Message { + pub enum Message { /// Messages from the application, for the application. App(M), /// Internal messages to be handled by libcosmic. @@ -18,19 +23,20 @@ pub mod message { None, } - pub fn app(message: M) -> Message { + pub const fn app(message: M) -> Message { Message::App(message) } - pub fn cosmic(message: super::cosmic::Message) -> Message { + pub const fn cosmic(message: super::cosmic::Message) -> Message { Message::Cosmic(message) } - pub fn none() -> Message { + pub const fn none() -> Message { Message::None } } +pub use self::command::Command; pub use self::core::Core; pub use self::settings::Settings; use crate::theme::THEME; @@ -41,10 +47,7 @@ use iced::Subscription; use iced::{window, Application as IcedApplication}; pub use message::Message; -/// Commands for COSMIC applications. -pub type Command = iced::Command>; - -/// Launch the application with the given settings. +/// Launch a COSMIC application with the given [`Settings`]. /// /// # Errors /// @@ -102,6 +105,7 @@ pub fn run(settings: Settings, flags: App::Flags) -> iced::Res cosmic::Cosmic::::run(iced) } +/// An interactive cross-platform COSMIC application. #[allow(unused_variables)] pub trait Application where @@ -245,6 +249,7 @@ impl ApplicationExt for App { iced::Command::none() } + /// Creates the view for the main window. fn view_main<'a>(&'a self) -> Element<'a, Message> { let core = self.core(); let is_condensed = core.is_condensed(); @@ -313,7 +318,7 @@ impl ApplicationExt for App { } } - if core.show_content() { + if self.nav_model().is_none() || core.show_content() { let main_content = self.view().debug(core.debug).map(Message::App); widgets.push(main_content); diff --git a/src/app/settings.rs b/src/app/settings.rs index 1960663..0745fc9 100644 --- a/src/app/settings.rs +++ b/src/app/settings.rs @@ -1,11 +1,14 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! Configure a new COSMIC application. + use crate::{font, Theme}; #[cfg(feature = "wayland")] use iced::Limits; use iced_core::Font; +/// Configure a new COSMIC application. #[allow(clippy::struct_excessive_bools)] #[derive(derive_setters::Setters)] pub struct Settings { diff --git a/src/executor/mod.rs b/src/executor/mod.rs index 1dd67e8..2f98b14 100644 --- a/src/executor/mod.rs +++ b/src/executor/mod.rs @@ -1,14 +1,18 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! Select the preferred async executor for an application. + #[cfg(feature = "tokio")] pub mod multi; #[cfg(feature = "tokio")] pub mod single; +/// Uses the single thread executor by default. #[cfg(not(feature = "tokio"))] pub type Default = iced::executor::Default; +/// Uses the single thread executor by default. #[cfg(feature = "tokio")] pub type Default = single::Executor; diff --git a/src/executor/multi.rs b/src/executor/multi.rs index 18cb823..50aa111 100644 --- a/src/executor/multi.rs +++ b/src/executor/multi.rs @@ -1,6 +1,8 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! An async executor that schedules tasks across a pol ofbackground thread. + use std::future::Future; #[cfg(feature = "tokio")] diff --git a/src/executor/single.rs b/src/executor/single.rs index 1ffa052..aaa4f9f 100644 --- a/src/executor/single.rs +++ b/src/executor/single.rs @@ -1,6 +1,8 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! An async executor that schedules tasks on the same background thread. + use std::future::Future; #[cfg(feature = "tokio")] diff --git a/src/font.rs b/src/font.rs index e971a3b..5484e1f 100644 --- a/src/font.rs +++ b/src/font.rs @@ -1,6 +1,8 @@ // Copyright 2022 System76 // SPDX-License-Identifier: MPL-2.0 +//! Select preferred fonts. + pub use iced::Font; use iced::{ font::{load, Error}, diff --git a/src/icon_theme.rs b/src/icon_theme.rs index 58c0564..f426ae7 100644 --- a/src/icon_theme.rs +++ b/src/icon_theme.rs @@ -1,6 +1,8 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! Select the preferred icon theme. + use std::cell::RefCell; thread_local! { diff --git a/src/keyboard_nav.rs b/src/keyboard_nav.rs index 7610328..801c594 100644 --- a/src/keyboard_nav.rs +++ b/src/keyboard_nav.rs @@ -1,6 +1,8 @@ // Copyright 2023 System76 // SPDX-License-Identifier: MPL-2.0 +//! Subscribe to common application keyboard shortcuts. + use iced::{ event, keyboard::{self, KeyCode}, diff --git a/src/theme/mod.rs b/src/theme/mod.rs index dd2f8e4..16b1470 100644 --- a/src/theme/mod.rs +++ b/src/theme/mod.rs @@ -1,6 +1,8 @@ // Copyright 2022 System76 // SPDX-License-Identifier: MPL-2.0 +//! Use COSMIC's themes and styles. + pub mod expander; mod segmented_button;