commands: add docs for Command trait

src/commands.rs

@@ -28,17 +28,22 @@ pub use reflection::*;
 pub use stickers::*;
 pub use stored_playlists::*;
 
+/// A trait modelling the request/response pair of a single MPD command.
 pub trait Command {
-    // // The request sent from the client to the server
+    /// The request sent from the client to the server
     type Request;
 
-    // The response sent from the server to the client
+    /// The response sent from the server to the client
     type Response;
 
-    // The command name used within the protocol
+    /// The command name used within the protocol
     const COMMAND: &'static str;
 
+    /// Serialize the request into a string.
+    /// This should optimally produce an input that can be parsed by [`parse_request`]
     fn serialize_request(&self, request: Self::Request) -> String;
+
+    /// Serialize the request into a bytestring.
     fn serialize_request_to_bytes(&self, request: Self::Request) -> Vec<u8> {
         self.serialize_request(request).into_bytes()
     }
@@ -48,9 +53,21 @@ pub trait Command {
     //     self.serialize_response().into_bytes()
     // }
 
-    // A function to parse the remaining parts of the command, split by whitespace
+    /// Parse the request from its tokenized parts.
+    ///
+    /// Note that this assumes only the parts after the command name are passed in, e.g.
+    ///
+    /// ```ignore
+    /// arg1 "arg2 arg3"
+    /// ```
     fn parse_request(parts: RequestTokenizer<'_>) -> RequestParserResult<'_>;
 
+    /// Parse the raw request string into a request and the remaining unparsed string.
+    /// This assumes the raw string starts with the command name, e.g.
+    ///
+    /// ```ignore
+    /// command_name arg1 "arg2 arg3"
+    /// ```
     fn parse_raw_request(raw: &str) -> RequestParserResult<'_> {
         let (line, rest) = raw
             .split_once('\n')
@@ -67,8 +84,11 @@ pub trait Command {
         Self::parse_request(tokenized).map(|(req, _)| (req, rest))
     }
 
+    /// Parse the response from its tokenized parts.
+    /// See also [`parse_raw_response`].
     fn parse_response(parts: ResponseAttributes<'_>) -> ResponseParserResult<'_, Self::Response>;
 
+    /// Parse the raw response string into a response.
     fn parse_raw_response(raw: &str) -> ResponseParserResult<'_, Self::Response> {
         Self::parse_response(ResponseAttributes::new(raw))
     }