From 4472e5a51076b059a5083ca23db3aa72b7c5a121 Mon Sep 17 00:00:00 2001
From: Paul Hauner <paul@paulhauner.com>
Date: Tue, 22 Sep 2020 10:36:41 +1000
Subject: [PATCH] Add comments to http_metrics crate

---
 beacon_node/http_metrics/src/lib.rs | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/beacon_node/http_metrics/src/lib.rs b/beacon_node/http_metrics/src/lib.rs
index 053ecaa501b..37eac82bda4 100644
--- a/beacon_node/http_metrics/src/lib.rs
+++ b/beacon_node/http_metrics/src/lib.rs
@@ -1,3 +1,7 @@
+//! This crate provides a HTTP server that is solely dedicated to serving the `/metrics` endpoint.
+//!
+//! For other endpoints, see the `http_api` crate.
+
 #[macro_use]
 extern crate lazy_static;
 
@@ -31,6 +35,9 @@ impl From<String> for Error {
     }
 }
 
+/// A wrapper around all the items required to spawn the HTTP server.
+///
+/// The server will gracefully handle the case where any fields are `None`.
 pub struct Context<T: BeaconChainTypes> {
     pub config: Config,
     pub chain: Option<Arc<BeaconChain<T>>>,
@@ -39,6 +46,7 @@ pub struct Context<T: BeaconChainTypes> {
     pub log: Logger,
 }
 
+/// Configuration for the HTTP server.
 #[derive(PartialEq, Debug, Clone, Serialize, Deserialize)]
 pub struct Config {
     pub enabled: bool,
@@ -58,6 +66,21 @@ impl Default for Config {
     }
 }
 
+/// Creates a server that will serve requests using information from `ctx`.
+///
+/// The server will shut down gracefully when the `shutdown` future resolves.
+///
+/// ## Returns
+///
+/// This function will bind the server to the provided address and then return a tuple of:
+///
+/// - `SocketAddr`: the address that the HTTP server will listen on.
+/// - `Future`: the actual server future that will need to be awaited.
+///
+/// ## Errors
+///
+/// Returns an error if the server is unable to bind or there is another error during
+/// configuration.
 pub fn serve<T: BeaconChainTypes>(
     ctx: Arc<Context<T>>,
     shutdown: impl Future<Output = ()> + Send + Sync + 'static,
@@ -66,6 +89,7 @@ pub fn serve<T: BeaconChainTypes>(
     let log = ctx.log.clone();
     let allow_origin = config.allow_origin.clone();
 
+    // Sanity check.
     if !config.enabled {
         crit!(log, "Cannot start disabled metrics HTTP server");
         return Err(Error::Other(
@@ -89,7 +113,9 @@ pub fn serve<T: BeaconChainTypes>(
                     }),
             )
         })
+        // Add a `Server` header.
         .map(|reply| warp::reply::with_header(reply, "Server", &version_with_platform()))
+        // Maybe add some CORS headers.
         .map(move |reply| warp_utils::reply::maybe_cors(reply, allow_origin.as_ref()));
 
     let (listening_socket, server) = warp::serve(routes).try_bind_with_graceful_shutdown(