[ISSUE #795]📝Add doc for trait🎨

rocketmq-broker/src/broker/broker_hook.rs

@@ -17,7 +17,17 @@
 
 use std::sync::Arc;
 
+/// Trait defining a shutdown hook.
+///
+/// This trait should be implemented by types that need to perform specific actions
+/// before the system or application is shutdown. The `before_shutdown` method will
+/// be called as part of the shutdown sequence, allowing for cleanup or other shutdown
+/// procedures to be executed.
 pub trait ShutdownHook {
+    /// Method to be called before shutdown.
+    ///
+    /// Implementors should place any necessary cleanup or pre-shutdown logic within
+    /// this method. This method is called automatically when a shutdown event occurs.
     fn before_shutdown(&self);
 }
 

rocketmq-broker/src/client/consumer_ids_change_listener.rs

@@ -19,8 +19,28 @@ use std::any::Any;
 
 use crate::client::consumer_group_event::ConsumerGroupEvent;
 
+/// Trait for listening to consumer ID changes.
+///
+/// This trait defines the functionality required to listen to changes in consumer IDs within a
+/// consumer group. Implementors of this trait can react to consumer group events, handle them, and
+/// perform necessary actions such as resource cleanup during shutdown.
 pub trait ConsumerIdsChangeListener {
+    /// Handles consumer group events.
+    ///
+    /// This method is called when a consumer group event occurs, allowing the implementor to react
+    /// to changes in consumer IDs. It can be used to update internal state or perform actions
+    /// based on the event.
+    ///
+    /// # Arguments
+    /// * `event` - The consumer group event that occurred.
+    /// * `group` - The name of the consumer group affected by the event.
+    /// * `args` - Additional arguments or context provided with the event.
     fn handle(&self, event: ConsumerGroupEvent, group: &str, args: &[&dyn Any]);
 
+    /// Performs cleanup actions before shutdown.
+    ///
+    /// This method should be implemented to perform any necessary cleanup actions before the
+    /// listener is shutdown. It's a good place to release resources or perform other shutdown
+    /// procedures.
     fn shutdown(&self);
 }

rocketmq-broker/src/mqtrace/consume_message_hook.rs

@@ -16,23 +16,43 @@
  */
 use crate::mqtrace::consume_message_context::ConsumeMessageContext;
 
-/// `ConsumeMessageHook` is a trait that provides hooks for consuming messages.
-/// Implementors of this trait provide their own logic for what should happen before and after a
-/// message is consumed.
+/// Trait for hooks in the message consumption process.
+///
+/// This trait defines a mechanism for intercepting and possibly modifying the behavior
+/// of message consumption in a message queue system. Implementors can provide custom logic
+/// before and after the message consumption process.
+///
+/// # Requirements
+///
+/// Implementors must be thread-safe (`Sync + Send`) and support static lifetimes (`'static`).
 pub trait ConsumeMessageHook: Sync + Send + 'static {
     /// Returns the name of the hook.
-    /// This is typically used for logging and debugging purposes.
+    ///
+    /// This method should provide a unique name for the hook, which can be used for logging,
+    /// debugging, or identifying the hook within a collection of hooks.
+    ///
+    /// # Returns
+    /// A string slice (`&str`) representing the name of the hook.
     fn hook_name(&self) -> &str;
 
-    /// This method is called before a message is consumed.
-    /// The `context` parameter provides information about the message that is about to be consumed.
-    /// Implementors can use this method to perform setup or configuration tasks before the message
-    /// is consumed.
+    /// Hook method called before a message is consumed.
+    ///
+    /// This method is invoked before the actual consumption of a message, allowing for
+    /// pre-processing, logging, or other preparatory actions based on the message context.
+    ///
+    /// # Arguments
+    /// * `context` - A mutable reference to the `ConsumeMessageContext`, providing access to the
+    ///   message and its metadata for possible inspection or modification.
     fn consume_message_before(&self, context: &mut ConsumeMessageContext);
 
-    /// This method is called after a message is consumed.
-    /// The `context` parameter provides information about the message that was just consumed.
-    /// Implementors can use this method to perform cleanup or logging tasks after the message is
-    /// consumed.
+    /// Hook method called after a message is consumed.
+    ///
+    /// This method is invoked after a message has been consumed, allowing for post-processing,
+    /// logging, or other follow-up actions based on the message context and the outcome of its
+    /// consumption.
+    ///
+    /// # Arguments
+    /// * `context` - A mutable reference to the `ConsumeMessageContext`, providing access to the
+    ///   message and its metadata for possible inspection or modification.
     fn consume_message_after(&self, context: &mut ConsumeMessageContext);
 }

rocketmq-common/src/common/attribute.rs

@@ -22,9 +22,30 @@ pub mod cq_type;
 pub mod topic_attributes;
 pub mod topic_message_type;
 
+/// `AttributeTrait` defines a common interface for attributes.
+///
+/// This trait specifies the operations that can be performed on an attribute object.
+/// It is designed to be implemented by any struct that represents an attribute, providing
+/// a standardized way to interact with attribute data.
 pub trait AttributeTrait {
+    /// Retrieves the name of the attribute.
+    ///
+    /// # Returns
+    /// A `String` representing the name of the attribute.
     fn name(&self) -> String;
+
+    /// Checks if the attribute is changeable.
+    ///
+    /// # Returns
+    /// A `bool` indicating whether the attribute can be changed after its initial set up.
     fn changeable(&self) -> bool;
+
+    /// Verifies if the provided value is valid for the attribute.
+    ///
+    /// Implementations should define the criteria for a value to be considered valid.
+    ///
+    /// # Arguments
+    /// * `value` - A string slice representing the value to be verified.
     fn verify(&self, value: &str);
 }
 

rocketmq-common/src/common/config_manager.rs

@@ -128,29 +128,45 @@ pub trait ConfigManager {
         true
     }
 
-    /// Returns the path of the configuration file.
+    /// Returns the file path for the configuration file.
     ///
-    /// This method is a placeholder for returning the path of the configuration file.
-    /// The actual implementation should be provided by the implementer of the trait.
+    /// This method should be implemented to return the path of the configuration file
+    /// that the `ConfigManager` will use to load or persist the configuration.
+    ///
+    /// # Returns
+    /// A `String` representing the path of the configuration file.
     fn config_file_path(&self) -> String;
 
-    /// Encodes the configuration.
+    /// Encodes the current configuration into a `String`.
     ///
-    /// This method is a placeholder for encoding the configuration.
-    /// The actual implementation should be provided by the implementer of the trait.
+    /// This method leverages `encode_pretty` with `pretty_format` set to `false` to encode
+    /// the current configuration into a compact `String` representation.
+    ///
+    /// # Returns
+    /// A `String` representing the encoded configuration in a compact format.
     fn encode(&mut self) -> String {
         self.encode_pretty(false)
     }
 
-    /// Encodes the configuration with pretty format.
+    /// Encodes the current configuration into a `String` with an option for pretty formatting.
     ///
-    /// This method is a placeholder for encoding the configuration with pretty format.
-    /// The actual implementation should be provided by the implementer of the trait.
+    /// This method encodes the current configuration into a `String`. It offers an option to
+    /// format the output in a more readable (pretty) format if `pretty_format` is `true`.
+    ///
+    /// # Arguments
+    /// * `pretty_format` - A boolean indicating whether the output should be pretty formatted.
+    ///
+    /// # Returns
+    /// A `String` representing the encoded configuration, optionally in a pretty format.
     fn encode_pretty(&self, pretty_format: bool) -> String;
 
     /// Decodes the configuration from a JSON string.
     ///
-    /// This method is a placeholder for decoding the configuration from a JSON string.
-    /// The actual implementation should be provided by the implementer of the trait.
+    /// This method takes a JSON string representation of the configuration and decodes it
+    /// into the internal representation used by the `ConfigManager`. Implementations should
+    /// update the internal state based on the provided JSON string.
+    ///
+    /// # Arguments
+    /// * `json_string` - A `&str` representing the configuration in JSON format.
     fn decode(&self, json_string: &str);
 }

rocketmq-common/src/common/message.rs

@@ -32,23 +32,73 @@ pub mod message_id;
 pub mod message_queue;
 pub mod message_single;
 
+/// Trait defining the behavior of a message in a messaging system.
 pub trait MessageTrait {
+    /// Retrieves the topic of the message.
+    ///
+    /// # Returns
+    /// A string slice representing the topic of the message.
     fn topic(&self) -> &str;
 
+    /// Sets the topic of the message.
+    ///
+    /// # Arguments
+    /// * `topic` - A string or a type that can be converted into a `String` representing the new
+    ///   topic of the message.
     fn with_topic(&mut self, topic: impl Into<String>);
 
+    /// Retrieves the tags associated with the message, if any.
+    ///
+    /// # Returns
+    /// An `Option` containing a string slice representing the tags of the message, or `None` if no
+    /// tags are set.
     fn tags(&self) -> Option<&str>;
 
+    /// Sets the tags of the message.
+    ///
+    /// # Arguments
+    /// * `tags` - A string or a type that can be converted into a `String` representing the new
+    ///   tags of the message.
     fn with_tags(&mut self, tags: impl Into<String>);
 
+    /// Adds a property to the message.
+    ///
+    /// # Arguments
+    /// * `key` - A string or a type that can be converted into a `String` representing the property
+    ///   key.
+    /// * `value` - A string or a type that can be converted into a `String` representing the
+    ///   property value.
     fn put_property(&mut self, key: impl Into<String>, value: impl Into<String>);
 
+    /// Retrieves all properties of the message.
+    ///
+    /// # Returns
+    /// A reference to a `HashMap` containing all properties of the message, where the key is the
+    /// property name and the value is the property value.
     fn properties(&self) -> &HashMap<String, String>;
 
+    /// Adds a user-defined property to the message.
+    ///
+    /// # Arguments
+    /// * `name` - A string or a type that can be converted into a `String` representing the name of
+    ///   the user-defined property.
+    /// * `value` - A string or a type that can be converted into a `String` representing the value
+    ///   of the user-defined property.
     fn put_user_property(&mut self, name: impl Into<String>, value: impl Into<String>);
 
+    /// Retrieves the delay time level of the message.
+    ///
+    /// # Returns
+    /// An `i32` representing the delay time level of the message.
     fn delay_time_level(&self) -> i32;
 
+    /// Sets the delay time level of the message.
+    ///
+    /// # Arguments
+    /// * `level` - An `i32` representing the new delay time level of the message.
+    ///
+    /// # Returns
+    /// The updated delay time level of the message.
     fn with_delay_time_level(&self, level: i32) -> i32;
 }
 

rocketmq-remoting/src/clients.rs

@@ -75,25 +75,66 @@ impl RemoteClient {
     }
 }
 
+/// `RemotingClient` trait extends `RemotingService` to provide client-specific remote interaction
+/// functionalities.
+///
+/// This trait defines methods for managing name server addresses, invoking commands asynchronously
+/// or without expecting a response, checking if an address is reachable, and closing clients
+/// connected to specific addresses.
 #[allow(async_fn_in_trait)]
 pub trait RemotingClient: RemotingService {
+    /// Updates the list of name server addresses.
+    ///
+    /// # Arguments
+    /// * `addrs` - A list of name server addresses to update.
     fn update_name_server_address_list(&self, addrs: Vec<String>);
 
+    /// Retrieves the current list of name server addresses.
+    ///
+    /// # Returns
+    /// A vector containing the current list of name server addresses.
     fn get_name_server_address_list(&self) -> Vec<String>;
 
+    /// Retrieves a list of available name server addresses.
+    ///
+    /// # Returns
+    /// A vector containing the list of available name server addresses.
     fn get_available_name_srv_list(&self) -> Vec<String>;
 
+    /// Asynchronously invokes a command on a specified address.
+    ///
+    /// # Arguments
+    /// * `addr` - The address to invoke the command on.
+    /// * `request` - The `RemotingCommand` to be sent.
+    /// * `timeout_millis` - The timeout for the operation in milliseconds.
+    ///
+    /// # Returns
+    /// A `Result` containing either the response `RemotingCommand` or an `Error`.
     async fn invoke_async(
         &self,
         addr: String,
         request: RemotingCommand,
         timeout_millis: u64,
     ) -> Result<RemotingCommand, Error>;
 
+    /// Invokes a command on a specified address without waiting for a response.
+    ///
+    /// # Arguments
+    /// * `addr` - The address to invoke the command on.
+    /// * `request` - The `RemotingCommand` to be sent.
+    /// * `timeout_millis` - The timeout for the operation in milliseconds.
     async fn invoke_oneway(&self, addr: String, request: RemotingCommand, timeout_millis: u64);
 
+    /// Checks if a specified address is reachable.
+    ///
+    /// # Arguments
+    /// * `addr` - The address to check for reachability.
     fn is_address_reachable(&mut self, addr: String);
 
+    /// Closes clients connected to the specified addresses.
+    ///
+    /// # Arguments
+    /// * `addrs` - A list of addresses whose clients should be closed.
     fn close_clients(&mut self, addrs: Vec<String>);
 }