feat: add specific error docs

feat: add clap feature

README.md

@@ -27,9 +27,11 @@ Available at [github pages](https://szymon-jozef.github.io/libnotify-rs/libnotif
 ## Add to project
 Type in:
 ```bash
-cargo add --git "https://github.com/szymon-jozef/libnotify-rs"
+cargo add --git "https://github.com/szymon-jozef/libnotify-rs" --tag <desired version>
 ```
 
+Tag argument is optional, but encouraged.
+
 ### Nix flake
 For nix users, there is also a flake inside. If you want to use it add this to your flake:
 

src/api/functions.rs

@@ -12,6 +12,9 @@ use super::libnotify::*;
 /// Initialized libnotify. This must be called before any other functions.
 ///
 /// Starting from 0.8, if the provided app_name is NULL, libnotify will try to figure it out from the running application. Before it was not allowed, and was causing libnotify not to be initialized.
+///
+/// # Errors
+/// This function can return LibnotifyError::{InitError, NulError}
 pub fn init<'a, T>(app_name: T) -> Result<(), LibnotifyError>
 where
     T: Into<Option<&'a str>>,
@@ -163,6 +166,9 @@ pub fn get_server_info() -> Option<ServerInfo> {
 */
 
 /// Sets the application name
+///
+/// # Errors
+/// This function can return LibnotifyError::NulError
 pub fn set_app_name(app_name: &str) -> Result<(), LibnotifyError> {
     let app_name_c = std::ffi::CString::new(app_name)?;
     unsafe { notify_set_app_name(app_name_c.as_ptr()) };
@@ -174,6 +180,9 @@ pub fn set_app_name(app_name: &str) -> Result<(), LibnotifyError> {
 /// Available since: 0.8.4
 ///
 /// app_icon is icon name or path to an image
+///
+/// # Errors
+/// This function can return LibnotifyError::NulError
 pub fn set_app_icon(app_icon: &str) -> Result<(), LibnotifyError> {
     let app_icon_c = std::ffi::CString::new(app_icon)?;
     unsafe { notify_set_app_icon(app_icon_c.as_ptr()) };

src/api/notification.rs

@@ -47,7 +47,6 @@ pub enum HintValue {
 
 /// Notification timeout, until close
 #[derive(Debug, Clone, Copy)]
-#[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
 pub enum Timeout {
     #[allow(missing_docs)]
     Default,
@@ -66,11 +65,7 @@ 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.
+    /// This function can return LibnotifyError::{NewNotificationError, NulError}
     pub fn new<T, Y>(summary: &str, body: T, icon: Y) -> Result<Self, LibnotifyError>
     where
         T: Into<Option<&'a str>>,
@@ -106,6 +101,9 @@ impl<'a> Notification {
     /// `label` – label for user
     ///
     /// `callback` - any closure that accepts &str as an argument, where &str is action name.
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::NulError
     pub fn add_action<F>(
         &mut self,
         action: &str,
@@ -148,6 +146,9 @@ impl<'a> Notification {
     }
 
     /// Synchronously tells the notification server to hide the notification on the screen
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{AllocationError, GerrorError}
     pub fn close(&self) -> Result<(), LibnotifyError> {
         let mut gerror = std::ptr::null_mut() as *mut GError;
 
@@ -195,6 +196,9 @@ impl<'a> Notification {
     /// `set_app_icon()`.
     ///
     /// Available since: 0.8.4
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{NulError}
     pub fn set_app_icon(&mut self, app_icon: &str) -> Result<(), LibnotifyError> {
         let app_icon_c = std::ffi::CString::new(app_icon)?;
         unsafe { notify_notification_set_app_icon(self.inner, app_icon_c.as_ptr()) };
@@ -207,6 +211,9 @@ impl<'a> Notification {
     /// If this function is not called, the application name will be set from the value used in init() or overridden with set_app_name().
     ///
     /// Available since: 0.7.3
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{NulError}
     pub fn set_app_name(&mut self, app_name: &str) -> Result<(), LibnotifyError> {
         let app_name_c = std::ffi::CString::new(app_name)?;
         unsafe { notify_notification_set_app_name(self.inner, app_name_c.as_ptr()) };
@@ -217,6 +224,9 @@ impl<'a> Notification {
     /// Sets the category of this notification.
     ///
     /// This can be used by the notification server to filter or display the data in a certain way
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{NulError}
     pub fn set_category(&mut self, category: &str) -> Result<(), LibnotifyError> {
         let category_c = std::ffi::CString::new(category)?;
         unsafe { notify_notification_set_category(self.inner, category_c.as_ptr()) };
@@ -227,6 +237,9 @@ impl<'a> Notification {
     /// Sets a hint for key with value value
     ///
     /// Available since: 0.6
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{NulError, AllocationError}
     pub fn set_hint(&mut self, key: &str, value: HintValue) -> Result<(), LibnotifyError> {
         let key_c = std::ffi::CString::new(key)?;
 
@@ -275,6 +288,9 @@ impl<'a> Notification {
     }
 
     /// Tells the notification server to display the notification on the screen
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{GerrorError, AllocationError}
     pub fn show(&self) -> Result<(), LibnotifyError> {
         let mut gerror = std::ptr::null_mut() as *mut GError;
 
@@ -304,12 +320,15 @@ impl<'a> Notification {
     /// Updates the notification text and icon.
     ///
     /// This won’t send the update out and display it on the screen. For that, you will need to call `show()`.
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{NulError}
     pub fn update<'b, F, I>(
         &mut self,
         summary: &str,
         body: F,
         icon: I,
-    ) -> Result<(), std::ffi::NulError>
+    ) -> Result<(), LibnotifyError>
     where
         F: Into<Option<&'b str>>,
         I: Into<Option<&'b str>>,

src/lib.rs

@@ -10,7 +10,7 @@
 //!
 //! # Features
 //!
-//! - clap – enables [clap] support for `Urgency` and `Timeout` enums
+//! - clap – enables [clap] support for `Urgency`
 //!
 #![allow(non_upper_case_globals)]
 #![allow(non_camel_case_types)]

src/wrappers/builder.rs

@@ -15,6 +15,10 @@ pub struct NotificationBuilder<'a> {
 
 impl<'a> NotificationBuilder<'a> {
     /// Create new NotificationBuilder, with given context.
+    ///
+    /// # Errors
+    ///
+    /// This function can return LibnotifyError::{NewNotificationError, NulError}
     pub fn new<T, Y>(
         summary: &str,
         body: T,
@@ -34,52 +38,86 @@ impl<'a> NotificationBuilder<'a> {
     }
 
     /// Sets app name for this specific notification.
-    pub fn set_app_name(mut self, app_name: &str) -> Result<Self, LibnotifyError> {
-        self.notification.set_app_name(app_name)?;
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{NulError}
+    pub fn set_app_name<T: Into<Option<&'a str>>>(
+        mut self,
+        app_name: T,
+    ) -> Result<Self, LibnotifyError> {
+        if let Some(app_name) = app_name.into() {
+            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, LibnotifyError> {
-        self.notification.set_app_icon(app_icon)?;
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{NulError}
+    pub fn set_app_icon<T: Into<Option<&'a str>>>(
+        mut self,
+        app_icon: T,
+    ) -> Result<Self, LibnotifyError> {
+        if let Some(app_icon) = app_icon.into() {
+            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, LibnotifyError> {
-        self.notification.set_category(category)?;
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{NulError}
+    pub fn set_category<T: Into<Option<&'a str>>>(
+        mut self,
+        category: T,
+    ) -> Result<Self, LibnotifyError> {
+        if let Some(category) = category.into() {
+            self.notification.set_category(category)?;
+        }
+
         Ok(self)
     }
 
     /// Set hint for this specific notification
-    pub fn set_hint(
-        mut self,
-        key: &str,
-        value: HintValue,
-    ) -> Result<Self, Box<dyn std::error::Error>> {
+    /// # Errors
+    /// This function can return LibnotifyError::{NulError, AllocationError}
+    pub fn set_hint(mut self, key: &str, value: HintValue) -> Result<Self, LibnotifyError> {
         self.notification.set_hint(key, value)?;
         Ok(self)
     }
 
     /// Set timeout until close
-    pub fn set_timeout(mut self, timeout: Timeout) -> Self {
-        self.notification.set_timeout(timeout);
+    pub fn set_timeout<T: Into<Option<Timeout>>>(mut self, timeout: T) -> Self {
+        if let Some(timeout) = timeout.into() {
+            self.notification.set_timeout(timeout);
+        }
+
         self
     }
 
     /// Set notification urgency level
-    pub fn set_urgency(mut self, urgency: Urgency) -> Self {
-        self.notification.set_urgency(urgency);
+    pub fn set_urgency<T: Into<Option<Urgency>>>(mut self, urgency: T) -> Self {
+        if let Some(urgency) = urgency.into() {
+            self.notification.set_urgency(urgency);
+        }
+
         self
     }
 
     /// Add callback
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::NulError
     pub fn add_action<F>(
         mut self,
         action: &str,
         label: &str,
         callback: F,
-    ) -> Result<Self, Box<dyn std::error::Error>>
+    ) -> Result<Self, LibnotifyError>
     where
         F: Fn(&str) + 'static,
     {
@@ -90,13 +128,21 @@ impl<'a> NotificationBuilder<'a> {
     /// Show notification
     ///
     /// Uses `&self` borrow, so you can use this object later, after showing.
-    pub fn show(&self) -> Result<(), Box<dyn std::error::Error>> {
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{GerrorError, AllocationError}
+    pub fn show(&self) -> Result<(), LibnotifyError> {
         self.notification.show()?;
         Ok(())
     }
 
     /// Close notification synchronously.
-    pub fn close(&self) -> Result<(), Box<dyn std::error::Error>> {
+    ///
+    /// Uses `&self` borrow, so you can use this object later, after closing.
+    ///
+    /// # Errors
+    /// This function can return LibnotifyError::{GerrorError, AllocationError}
+    pub fn close(&self) -> Result<(), LibnotifyError> {
         self.notification.close()?;
         Ok(())
     }