improv(menu): add documentation.

src/widget/menu/action.rs

@@ -1,7 +1,57 @@
 use crate::widget::segmented_button::Entity;
 
+/// `MenuAction` is a trait that represents an action in a menu.
+///
+/// It is used to define the behavior of menu items when they are activated.
+/// Each menu item can have a unique action associated with it.
+///
+/// This trait is generic over a type `Message` which is the type of message
+/// that will be produced when the action is triggered.
+///
+/// # Example
+///
+/// ```
+/// use cosmic::widget::menu::action::MenuAction;
+/// use cosmic::widget::segmented_button::Entity;
+///
+/// #[derive(Clone, Copy, Eq, PartialEq)]
+/// enum MyMessage {
+///     Open,
+///     Save,
+///     Quit,
+/// }
+///
+/// #[derive(Clone, Copy, Eq, PartialEq)]
+/// enum MyAction {
+///     Open,
+///     Save,
+///     Quit,
+/// }
+///
+/// impl MenuAction for MyAction {
+///     type Message = MyMessage;
+///
+///     fn message(&self, entity: Option<Entity>) -> Self::Message {
+///         match self {
+///             MyAction::Open => MyMessage::Open,
+///             MyAction::Save => MyMessage::Save,
+///             MyAction::Quit => MyMessage::Quit,
+///         }
+///     }
+/// }
+/// ```
 pub trait MenuAction: Clone + Copy + Eq + PartialEq {
+    /// The type of message that will be produced when the action is triggered.
     type Message;
 
+    /// Returns a message of type `Self::Message` when the action is triggered.
+    ///
+    /// # Arguments
+    ///
+    /// * `entity` - An optional `Entity` that may be associated with the action.
+    ///
+    /// # Returns
+    ///
+    /// * `Self::Message` - The message that is produced when the action is triggered.
     fn message(&self, entity: Option<Entity>) -> Self::Message;
 }

src/widget/menu/key_bind.rs

@@ -1,6 +1,13 @@
 use iced_core::keyboard::{Key, Modifiers};
 use std::fmt;
 
+/// Represents the modifier keys on a keyboard.
+///
+/// It has four variants:
+/// * `Super`: Represents the Super key (also known as the Windows key on Windows, Command key on macOS).
+/// * `Ctrl`: Represents the Control key.
+/// * `Alt`: Represents the Alt key.
+/// * `Shift`: Represents the Shift key.
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 pub enum Modifier {
     Super,
@@ -9,13 +16,27 @@ pub enum Modifier {
     Shift,
 }
 
+/// Represents a combination of a key and modifiers.
+/// It is used to define keyboard shortcuts.
 #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 pub struct KeyBind {
+    /// A vector of modifiers for the key binding.
     pub modifiers: Vec<Modifier>,
+    /// The key for the key binding.
     pub key: Key,
 }
 
 impl KeyBind {
+    /// Checks if the given key and modifiers match the `KeyBind`.
+    ///
+    /// # Arguments
+    ///
+    /// * `modifiers` - A `Modifiers` instance representing the current active modifiers.
+    /// * `key` - A reference to the `Key` that is being checked.
+    ///
+    /// # Returns
+    ///
+    /// * `bool` - `true` if the key and modifiers match the `KeyBind`, `false` otherwise.
     pub fn matches(&self, modifiers: Modifiers, key: &Key) -> bool {
         key == &self.key
             && modifiers.logo() == self.modifiers.contains(&Modifier::Super)

src/widget/menu/menu_tree.rs

@@ -137,6 +137,7 @@ where
     }
 }
 
+/// This macro creates a button for a MenuTree.
 macro_rules! menu_button {
     ($($x:expr),+ $(,)?) => (
         widget::button(
@@ -154,11 +155,26 @@ macro_rules! menu_button {
     );
 }
 
+/// Represents a menu item that performs an action when selected or a separator between menu items.
+///
+/// - `Action` - Represents a menu item that performs an action when selected.
+///     - `L` - The label of the menu item.
+///     - `A` - The action to perform when the menu item is selected, the action must implement the `MenuAction` trait.
+/// - `Separator` - Represents a separator between menu items.
 pub enum MenuItem<A: MenuAction, L: Into<Cow<'static, str>>> {
+    /// Represents a menu item that performs an action when selected.
     Action(L, A),
+    /// Represents a separator between menu items.
     Separator,
 }
 
+/// Create a root menu item.
+///
+/// # Arguments
+/// - `label` - The label of the menu item.
+///
+/// # Returns
+/// - A button for the root menu item.
 pub fn menu_root<'a, Message, Renderer: renderer::Renderer>(
     label: impl Into<Cow<'a, str>> + 'a,
 ) -> iced::Element<'a, Message, crate::Theme, Renderer>
@@ -172,6 +188,16 @@ where
         .into()
 }
 
+/// Create a list of menu items from a vector of `MenuItem`.
+///
+/// The `MenuItem` can be either an action or a separator.
+///
+/// # Arguments
+/// - `key_binds` - A reference to a `HashMap` that maps `KeyBind` to `A`.
+/// - `children` - A vector of `MenuItem`.
+///
+/// # Returns
+/// - A vector of `MenuTree`.
 pub fn menu_items<
     'a,
     A: MenuAction<Message = Message>,