diff --git a/src/api/functions.rs b/src/api/functions.rs index 7346ede..c716336 100644 --- a/src/api/functions.rs +++ b/src/api/functions.rs @@ -116,6 +116,7 @@ pub fn get_server_caps() -> Option> { if vec.is_empty() { None } else { Some(vec) } } +/// Contains server information. Refer to [libnotify get_server_info docs](https://gnome.pages.gitlab.gnome.org/libnotify/func.get_server_info.html) to better understand specific fields pub struct ServerInfo { /// A location to store the server name, or `None` pub name: Option, diff --git a/src/api/mod.rs b/src/api/mod.rs index acca172..15241f4 100644 --- a/src/api/mod.rs +++ b/src/api/mod.rs @@ -1,4 +1,6 @@ +/// Same as [libnotify global functions](https://gnome.pages.gitlab.gnome.org/libnotify/index.html#functions) pub mod functions; mod libnotify; +/// Same as [libnotify notification](https://gnome.pages.gitlab.gnome.org/libnotify/class.Notification.html) pub mod notification; mod utils; diff --git a/src/api/notification.rs b/src/api/notification.rs index 5f53c29..ace6194 100644 --- a/src/api/notification.rs +++ b/src/api/notification.rs @@ -1,13 +1,18 @@ use super::libnotify::*; #[derive(Debug, Clone, Copy)] +/// Notification urgency level. Refer to [libnotify docs](https://gnome.pages.gitlab.gnome.org/libnotify/enum.Urgency.html) for more info pub enum Urgency { + /// Low urgency. Used for unimportant notifications Low, + /// Normal urgency. Used for most standard notifications Normal, + /// Critical urgency. Used for very important notifications Critical, } #[derive(Debug, Clone, Copy)] +/// Reason why notification was closed. Refer to [libnotify docs](https://gnome.pages.gitlab.gnome.org/libnotify/enum.ClosedReason.html) pub enum ClosedReason { /// Notification not closed Unset, @@ -29,24 +34,39 @@ pub enum ClosedReason { /// Used in set hint. #[derive(Debug, Clone)] pub enum HintValue { + #[allow(missing_docs)] String(String), + #[allow(missing_docs)] Int32(i32), + #[allow(missing_docs)] Boolean(bool), } -/// The timeout in milliseconds +/// Notification timeout, until close #[derive(Debug, Clone, Copy)] pub enum Timeout { + #[allow(missing_docs)] Default, + #[allow(missing_docs)] Never, + /// Custom timeout in milliseconds Custom(i32), } +/// Represents one notification. Wraps most of [libnotify::notifaction](https://gnome.pages.gitlab.gnome.org/libnotify/class.Notification.html) functions. pub struct Notification { inner: *mut NotifyNotification, } impl<'a> Notification { + /// Create new notification. + /// + /// # Errors + /// This function will return an error if the supplied bytes contain an + /// internal 0 byte. The [`NulError`](https://doc.rust-lang.org/stable/alloc/ffi/c_str/struct.NulError.html) returned will contain the bytes as well as + /// the position of the nul byte. + /// + /// On libnotify fail it will return Err(&str.into). May change in the future. pub fn new(summary: &str, body: T, icon: Y) -> Result> where T: Into>, @@ -73,6 +93,15 @@ impl<'a> Notification { Ok(Self { inner }) } + /// Add callback to notification. + /// + /// # Args + /// `action` – action identifier. `default` will work for most use cases. Other text will be + /// displayed as button names. + /// + /// `label` – label for user + /// + /// `callback` - any closure that accepts &str as an argument, where &str is action name. pub fn add_action( &mut self, action: &str, diff --git a/src/lib.rs b/src/lib.rs index 355823d..430faf9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,9 +1,20 @@ -#![cfg_attr(not(doctest), doc = include_str!("./../README.md"))] +//! This crate exposes two modules: +//! +//! # Api +//! This module contains a basic wrapper for libnotify calls. It just translates data types, etc, +//! so usage is basically the same as libnotify. +//! +//! # Wrappers +//! This module is a higher level abstraction over api. Recommended to use over api. +//! #![allow(non_upper_case_globals)] #![allow(non_camel_case_types)] #![allow(non_snake_case)] +#![warn(missing_docs)] +/// Basic libnotify rust wrapper pub mod api; +/// Higher level abstraction over api pub mod wrappers; pub use wrappers::{builder, context}; diff --git a/src/wrappers/builder.rs b/src/wrappers/builder.rs index 05d0110..b691328 100644 --- a/src/wrappers/builder.rs +++ b/src/wrappers/builder.rs @@ -3,12 +3,15 @@ use crate::{ wrappers::context::LibnotifyContext, }; +/// Higher level abstraction of `Notification`. Allow for builder pattern notification construction. +/// Requires `LibnotifyContext` pub struct NotificationBuilder<'a> { notification: Notification, _context: &'a LibnotifyContext, } impl<'a> NotificationBuilder<'a> { + /// Create new NotificationBuilder, with given context. pub fn new( summary: &str, body: T, @@ -27,20 +30,25 @@ impl<'a> NotificationBuilder<'a> { }) } + /// Sets app name for this specific notification. pub fn set_app_name(mut self, app_name: &str) -> Result { self.notification.set_app_name(app_name)?; Ok(self) } + /// Sets app icon fot this specific notification. pub fn set_app_icon(mut self, app_icon: &str) -> Result { self.notification.set_app_icon(app_icon)?; Ok(self) } + + /// Sets category for this specific notification pub fn set_category(mut self, category: &str) -> Result { self.notification.set_category(category)?; Ok(self) } + /// Set hint for this specific notification pub fn set_hint( mut self, key: &str, @@ -50,16 +58,19 @@ impl<'a> NotificationBuilder<'a> { Ok(self) } + /// Set timeout until close pub fn set_timeout(mut self, timeout: Timeout) -> Self { self.notification.set_timeout(timeout); self } + /// Set notification urgency level pub fn set_urgency(mut self, urgency: Urgency) -> Self { self.notification.set_urgency(urgency); self } + /// Add callback pub fn add_action( mut self, action: &str, @@ -73,11 +84,15 @@ impl<'a> NotificationBuilder<'a> { Ok(self) } + /// Show notification + /// + /// Uses `&self` borrow, so you can use this object later, after showing. pub fn show(&self) -> Result<(), Box> { self.notification.show()?; Ok(()) } + /// Close notification synchronously. pub fn close(&self) -> Result<(), Box> { self.notification.close()?; Ok(()) diff --git a/src/wrappers/context.rs b/src/wrappers/context.rs index 16f47f9..7bddcb9 100644 --- a/src/wrappers/context.rs +++ b/src/wrappers/context.rs @@ -1,11 +1,17 @@ use crate::api::functions::{init, is_initted, set_app_icon, set_app_name, uninit}; +/// Notification context. Handles libnotify initializing and uninitializing. pub struct LibnotifyContext {} static IS_CONTEXT_CREATED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false); impl LibnotifyContext { + /// Try initializing libnotify + /// + /// # Error + /// Returns an error, if libnotify cannot be initialized or if there already exists a context + /// object pub fn new(app_name: &str) -> Result> { if IS_CONTEXT_CREATED.swap(true, std::sync::atomic::Ordering::SeqCst) { return Err("You can create only one context at a time".into()); @@ -18,11 +24,13 @@ impl LibnotifyContext { Ok(Self {}) } + /// Sets global app name pub fn set_new_name(&self, app_name: &str) -> Result<(), std::ffi::NulError> { set_app_name(app_name)?; Ok(()) } + /// Sets global app icon pub fn set_app_icon(&self, app_icon: &str) -> Result<(), std::ffi::NulError> { set_app_icon(app_icon)?; Ok(()) diff --git a/src/wrappers/mod.rs b/src/wrappers/mod.rs index 55a1200..3c7c894 100644 --- a/src/wrappers/mod.rs +++ b/src/wrappers/mod.rs @@ -1,2 +1,4 @@ +/// Contains notification builder pub mod builder; +/// Containx libnotify context pub mod context;