frame/request: doc RequestOpcode & CqlRequestKind

It seems that both enums should be merged into one.
This is however left for 2.0.

Author: wprzytula

scylla-cql/src/frame/request/mod.rs

@@ -31,16 +31,58 @@ use super::types::SerialConsistency;
 use super::TryFromPrimitiveError;
 
 /// Possible requests sent by the client.
+// Why is it distinct from [RequestOpcode]?
+// TODO(2.0): merge this with `RequestOpcode`.
 #[derive(Debug, Copy, Clone)]
 #[non_exhaustive]
 pub enum CqlRequestKind {
+    /// Initialize the connection. The server will respond by either a READY message
+    /// (in which case the connection is ready for queries) or an AUTHENTICATE message
+    /// (in which case credentials will need to be provided using AUTH_RESPONSE).
+    ///
+    /// This must be the first message of the connection, except for OPTIONS that can
+    /// be sent before to find out the options supported by the server. Once the
+    /// connection has been initialized, a client should not send any more STARTUP
+    /// messages.
     Startup,
+
+    /// Answers a server authentication challenge.
+
+    /// Authentication in the protocol is SASL based. The server sends authentication
+    /// challenges (a bytes token) to which the client answers with this message. Those
+    /// exchanges continue until the server accepts the authentication by sending a
+    /// AUTH_SUCCESS message after a client AUTH_RESPONSE. Note that the exchange
+    /// begins with the client sending an initial AUTH_RESPONSE in response to a
+    /// server AUTHENTICATE request.
+    ///
+    /// The response to a AUTH_RESPONSE is either a follow-up AUTH_CHALLENGE message,
+    /// an AUTH_SUCCESS message or an ERROR message.
     AuthResponse,
+
+    /// Asks the server to return which STARTUP options are supported. The server
+    /// will respond with a SUPPORTED message.
     Options,
+
+    /// Performs a CQL query, i.e., executes an unprepared statement.
+    /// The server will respond to a QUERY message with a RESULT message, the content
+    /// of which depends on the query.
     Query,
+
+    /// Prepares a query for later execution (through EXECUTE).
+    /// The server will respond with a RESULT::Prepared message.
     Prepare,
+
+    /// Executes a prepared query.
+    /// The response from the server will be a RESULT message.
     Execute,
+
+    /// Allows executing a list of queries (prepared or not) as a batch (note that
+    /// only DML statements are accepted in a batch).
+    /// The server will respond with a RESULT message.
     Batch,
+
+    /// Register this connection to receive some types of events.
+    /// The response to a REGISTER message will be a READY message.
     Register,
 }
 
@@ -65,13 +107,21 @@ impl std::fmt::Display for CqlRequestKind {
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[repr(u8)]
 pub enum RequestOpcode {
+    /// See [CqlRequestKind::Startup].
     Startup = 0x01,
+    /// See [CqlRequestKind::Options].
     Options = 0x05,
+    /// See [CqlRequestKind::Query].
     Query = 0x07,
+    /// See [CqlRequestKind::Prepare].
     Prepare = 0x09,
+    /// See [CqlRequestKind::Execute].
     Execute = 0x0A,
+    /// See [CqlRequestKind::Register].
     Register = 0x0B,
+    /// See [CqlRequestKind::Batch].
     Batch = 0x0D,
+    /// See [CqlRequestKind::AuthResponse].
     AuthResponse = 0x0F,
 }