Merge pull request #960 from sozu-proxy/documenting-comments

Documenting comments

bin/src/command/requests.rs

@@ -16,7 +16,7 @@ use sozu_command_lib::{
     buffer::fixed::Buffer,
     config::Config,
     logging,
-    parser::parse_several_commands,
+    parser::parse_several_requests,
     proto::command::{
         request::RequestType, response_content::ContentType, AggregatedMetrics, AvailableMetrics,
         CertificatesWithFingerprints, ClusterHashes, ClusterInformations, FrontendFilters,
@@ -213,7 +213,7 @@ impl CommandServer {
             }
 
             let mut offset = 0usize;
-            match parse_several_commands::<WorkerRequest>(buffer.data()) {
+            match parse_several_requests::<WorkerRequest>(buffer.data()) {
                 Ok((i, requests)) => {
                     if !i.is_empty() {
                         debug!("could not parse {} bytes", i.len());

command/src/config.rs

@@ -10,7 +10,7 @@
 //! ```
 //!
 //! `config.toml` is parsed to `FileConfig`, a structure that itself contains a lot of substructures
-//! whose names end start with `File-`, like `FileHttpFrontendConfig` for instance.
+//! whose names start with `File-` and end with `-Config`, like `FileHttpFrontendConfig` for instance.
 //!
 //! The instance of `FileConfig` is then passed to a `ConfigBuilder` that populates a final `Config`
 //! with listeners and clusters.

command/src/lib.rs

@@ -14,6 +14,7 @@ pub mod certificate;
 pub mod channel;
 /// parse TOML config and generate requests from it
 pub mod config;
+/// parse Requests
 pub mod parser;
 /// Contains Rust types generated by [`prost`](https://docs.rs/prost/latest/prost/)
 /// using the protobuf definition in `command.proto`.
@@ -58,6 +59,7 @@ pub mod parser;
 ///
 /// A bit cumbersome, but it is the only way to benefit from protobuf in Rust.
 pub mod proto;
+/// File descriptor readiness
 pub mod ready;
 /// Helper functions around types received by Sōzu
 pub mod request;
@@ -67,4 +69,5 @@ pub mod response;
 pub mod scm_socket;
 /// A representation of Sōzu's state
 pub mod state;
+/// A writer used for logging
 pub mod writer;

command/src/logging.rs

@@ -540,6 +540,7 @@ pub fn target_to_backend(target: &str) -> LoggerBackend {
     }
 }
 
+/// write a log with the custom logger (used in other macros, do not use directly)
 #[macro_export]
 macro_rules! log {
     (__inner__ $target:expr, $lvl:expr, $format:expr, $level_tag:expr,
@@ -581,6 +582,7 @@ macro_rules! log {
     };
 }
 
+/// log a failure concerning an HTTP or TCP request
 #[macro_export]
 macro_rules! log_access {
     (__inner__ $target:expr, $lvl:expr, $format:expr, $level_tag:expr,
@@ -622,6 +624,7 @@ macro_rules! log_access {
     };
 }
 
+/// log an error with Sōzu's custom log stack
 #[macro_export]
 macro_rules! error {
     ($format:expr, $($arg:tt)*) => {
@@ -632,6 +635,7 @@ macro_rules! error {
     };
 }
 
+/// log a failure concerning an HTTP or TCP request
 #[macro_export]
 macro_rules! error_access {
     ($format:expr, $($arg:tt)*) => {
@@ -642,6 +646,7 @@ macro_rules! error_access {
     };
 }
 
+/// log a warning with Sōzu’s custom log stack
 #[macro_export]
 macro_rules! warn {
     ($format:expr, $($arg:tt)*) => {
@@ -653,6 +658,7 @@ macro_rules! warn {
     }
 }
 
+/// log an info with Sōzu’s custom log stack
 #[macro_export]
 macro_rules! info {
     ($format:expr, $($arg:tt)*) => {
@@ -663,6 +669,7 @@ macro_rules! info {
     }
 }
 
+/// log the success of an HTTP or TCP request
 #[macro_export]
 macro_rules! info_access {
     ($format:expr, $($arg:tt)*) => {
@@ -673,6 +680,7 @@ macro_rules! info_access {
     }
 }
 
+/// log a debug with Sōzu’s custom log stack
 #[macro_export]
 macro_rules! debug {
     ($format:expr, $($arg:tt)*) => {
@@ -687,6 +695,7 @@ macro_rules! debug {
     }
 }
 
+/// log a trace with Sōzu’s custom log stack
 #[macro_export]
 macro_rules! trace {
     ($format:expr, $($arg:tt)*) => (
@@ -701,6 +710,7 @@ macro_rules! trace {
     )
 }
 
+/// write a log with a "FIXME" prefix on an info level
 #[macro_export]
 macro_rules! fixme {
     () => {
@@ -754,6 +764,7 @@ impl log::Log for CompatLogger {
     fn flush(&self) {}
 }
 
+/// start a logger used in test environment
 #[macro_export]
 macro_rules! setup_test_logger {
     () => {

command/src/parser.rs

@@ -41,7 +41,8 @@ impl nom::error::ParseError<&[u8]> for CustomError {
     }
 }
 
-pub fn parse_one_command<'a, T>(input: &'a [u8]) -> IResult<&[u8], T, CustomError>
+/// Parse a single Request or WorkerRequest
+pub fn parse_one_request<'a, T>(input: &'a [u8]) -> IResult<&[u8], T, CustomError>
 where
     T: serde::de::Deserialize<'a>,
 {
@@ -63,11 +64,12 @@ where
     Ok((next_input, command))
 }
 
-pub fn parse_several_commands<'a, T>(input: &'a [u8]) -> IResult<&[u8], Vec<T>, CustomError>
+/// Parse a Requests or WorkerRequests using nom
+pub fn parse_several_requests<'a, T>(input: &'a [u8]) -> IResult<&[u8], Vec<T>, CustomError>
 where
     T: serde::de::Deserialize<'a>,
 {
-    many0(parse_one_command)(input)
+    many0(parse_one_request)(input)
 }
 
 #[cfg(test)]
@@ -97,7 +99,7 @@ mod test {
         let empty_vec: Vec<u8> = vec![];
 
         assert_eq!(
-            parse_one_command(bytes).unwrap(),
+            parse_one_request(bytes).unwrap(),
             (&empty_vec[..], worker_request)
         )
     }
@@ -128,7 +130,7 @@ mod test {
 
         let bytes_to_parse = &serialized_requests.as_bytes();
 
-        let parsed_requests = parse_several_commands(bytes_to_parse).unwrap();
+        let parsed_requests = parse_several_requests(bytes_to_parse).unwrap();
 
         println!("parsed commands: {parsed_requests:?}");
 

command/src/response.rs

@@ -160,6 +160,7 @@ impl From<TcpFrontend> for RequestTcpFrontend {
     }
 }
 
+/// A backend, as used *within* Sōzu
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Backend {
     pub cluster_id: String,
@@ -223,6 +224,7 @@ struct StatePath {
 
 pub type MessageId = String;
 
+/// A response as sent by a worker
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct WorkerResponse {
     pub id: MessageId,

command/src/writer.rs

@@ -1,5 +1,6 @@
 use std::io::{self, Error, ErrorKind, Write};
 
+/// A multiline writer used for logging
 pub struct MultiLineWriter<W: Write> {
     inner: Option<W>,
     buf: Vec<u8>,