Merge pull request parallaxsecond#236 from hug-dev/docs

Add missing_docs lint and missing docs

Author: hug-dev

src/authenticators/direct_authenticator/mod.rs

@@ -19,6 +19,7 @@ use parsec_interface::requests::{ResponseStatus, Result};
 use parsec_interface::secrecy::ExposeSecret;
 use std::str;
 
+/// Direct authentication authenticator implementation
 #[derive(Copy, Clone, Debug)]
 pub struct DirectAuthenticator;
 

src/authenticators/mod.rs

@@ -48,10 +48,12 @@ pub trait Authenticate {
 }
 
 impl ApplicationName {
+    /// Create a new ApplicationName from a String
     pub fn new(name: String) -> ApplicationName {
         ApplicationName(name)
     }
 
+    /// Get a reference to the inner string
     pub fn get_name(&self) -> &str {
         &self.0
     }

src/back/backend_handler.rs

@@ -59,10 +59,6 @@ impl BackEndHandler {
     pub fn is_capable(&self, request: &Request) -> Result<()> {
         let header = &request.header;
 
-        // TODO: Add opcode checking here; store supported opcodes as a hashset
-        //      - should we move header field parsing at deserialization?
-        // TODO: if these two don't match the service should probably panic,
-        // but I think it's reasonable to assume they do match
         if header.provider != self.provider_id {
             Err(ResponseStatus::WrongProviderID)
         } else if header.content_type != self.content_type {
@@ -257,6 +253,7 @@ pub struct BackEndHandlerBuilder {
 }
 
 impl BackEndHandlerBuilder {
+    /// Create a new BackEndHandler builder
     pub fn new() -> BackEndHandlerBuilder {
         BackEndHandlerBuilder {
             provider: None,
@@ -267,31 +264,37 @@ impl BackEndHandlerBuilder {
         }
     }
 
+    /// Add a provider to the builder
     pub fn with_provider(mut self, provider: Arc<dyn Provide + Send + Sync>) -> Self {
         self.provider = Some(provider);
         self
     }
 
+    /// Add a converter to the builder
     pub fn with_converter(mut self, converter: Box<dyn Convert + Send + Sync>) -> Self {
         self.converter = Some(converter);
         self
     }
 
+    /// Set the ID of the BackEndHandler
     pub fn with_provider_id(mut self, provider_id: ProviderID) -> Self {
         self.provider_id = Some(provider_id);
         self
     }
 
+    /// Set the content type that the BackEndHandler supports
     pub fn with_content_type(mut self, content_type: BodyType) -> Self {
         self.content_type = Some(content_type);
         self
     }
 
+    /// Set the accept type that the BackEndHandler supports
     pub fn with_accept_type(mut self, accept_type: BodyType) -> Self {
         self.accept_type = Some(accept_type);
         self
     }
 
+    /// Build into a BackEndHandler
     pub fn build(self) -> std::io::Result<BackEndHandler> {
         Ok(BackEndHandler {
             provider: self

src/back/dispatcher.rs

@@ -61,10 +61,12 @@ pub struct DispatcherBuilder {
 }
 
 impl DispatcherBuilder {
+    /// Create a new Dispatcher builder
     pub fn new() -> Self {
         DispatcherBuilder { backends: None }
     }
 
+    /// Add a BackEndHandler with a specific Provider ID to the dispatcher
     pub fn with_backend(
         mut self,
         provider_id: ProviderID,
@@ -77,6 +79,7 @@ impl DispatcherBuilder {
         self
     }
 
+    /// Add multiple BackEndHandler to the dispatcher in one call
     pub fn with_backends(mut self, new_backends: HashMap<ProviderID, BackEndHandler>) -> Self {
         let mut backends = self.backends.unwrap_or_default();
         backends.extend(new_backends);
@@ -85,6 +88,7 @@ impl DispatcherBuilder {
         self
     }
 
+    /// Build the builder into a dispatcher
     pub fn build(self) -> Result<Dispatcher> {
         Ok(Dispatcher {
             backends: self

src/bin/main.rs

@@ -1,5 +1,14 @@
 // Copyright 2019 Contributors to the Parsec project.
 // SPDX-License-Identifier: Apache-2.0
+//! Parsec is the Platform AbstRaction for SECurity, a new open-source initiative to provide a
+//! common API to secure services in a platform-agnostic way.
+//!
+//! Parsec documentation is available
+//! [here](https://parallaxsecond.github.io/parsec-book/index.html)
+//!
+//! Most of Parsec configuration comes from its configuration file.
+//! Please check the documentation to find more about configuration
+//! [here](https://parallaxsecond.github.io/parsec-book/user_guides/configuration.html)
 #![deny(
     nonstandard_style,
     const_err,
@@ -18,8 +27,7 @@
     unused_parens,
     while_true,
     missing_debug_implementations,
-    //TODO: activate this!
-    //missing_docs,
+    missing_docs,
     trivial_casts,
     trivial_numeric_casts,
     unused_extern_crates,

src/front/domain_socket.rs

@@ -229,15 +229,18 @@ pub struct DomainSocketListenerBuilder {
 }
 
 impl DomainSocketListenerBuilder {
+    /// Create a new DomainSocketListener builder
     pub fn new() -> Self {
         DomainSocketListenerBuilder { timeout: None }
     }
 
+    /// Add a timeout on the Unix Domain Socket used
     pub fn with_timeout(mut self, timeout: Duration) -> Self {
         self.timeout = Some(timeout);
         self
     }
 
+    /// Build the builder into the listener
     pub fn build(self) -> Result<DomainSocketListener> {
         DomainSocketListener::new(self.timeout.ok_or_else(|| {
             error!("The listener timeout was not set.");

src/front/front_end.rs

@@ -131,6 +131,7 @@ pub struct FrontEndHandlerBuilder {
 }
 
 impl FrontEndHandlerBuilder {
+    /// Create a new FrontEndHandler builder
     pub fn new() -> Self {
         FrontEndHandlerBuilder {
             dispatcher: None,
@@ -139,11 +140,13 @@ impl FrontEndHandlerBuilder {
         }
     }
 
+    /// Add a dispatcher to the builder
     pub fn with_dispatcher(mut self, dispatcher: Dispatcher) -> Self {
         self.dispatcher = Some(dispatcher);
         self
     }
 
+    /// Add an authenticator to the builder
     pub fn with_authenticator(
         mut self,
         auth_type: AuthType,
@@ -163,11 +166,13 @@ impl FrontEndHandlerBuilder {
         self
     }
 
+    /// Set a limit on the maximal body length received
     pub fn with_body_len_limit(mut self, body_len_limit: usize) -> Self {
         self.body_len_limit = Some(body_len_limit);
         self
     }
 
+    /// Build into a FrontEndHandler
     pub fn build(self) -> Result<FrontEndHandler> {
         Ok(FrontEndHandler {
             dispatcher: self

src/front/listener.rs

@@ -9,20 +9,25 @@ use derivative::Derivative;
 use serde::Deserialize;
 use std::time::Duration;
 
-// This trait is created to allow the iterator returned by incoming to iterate over a trait object
-// that implements both Read and Write.
+/// This trait is created to allow the iterator returned by incoming to iterate over a trait object
+/// that implements both Read and Write.
 pub trait ReadWrite: std::io::Read + std::io::Write {}
 // Automatically implements ReadWrite for all types that implement Read and Write.
 impl<T: std::io::Read + std::io::Write> ReadWrite for T {}
 
+/// Type of the Listener used
 #[derive(Copy, Clone, Deserialize, Debug)]
 pub enum ListenerType {
+    /// Listener using Unix Domain Socket
     DomainSocket,
 }
 
+/// Configuration of the Listener
 #[derive(Copy, Clone, Deserialize, Debug)]
 pub struct ListenerConfig {
+    /// Type of the Listener
     pub listener_type: ListenerType,
+    /// Timeout of the Listener before the connection errors out (in milliseconds)
     pub timeout: u64,
 }
 
@@ -32,14 +37,14 @@ pub enum ConnectionMetadata {
     // TODO: nothing here right now. Metadata types will be added as needed.
 }
 
-/// Represents a connection to a single client. Contains a stream, used for communication with the
-/// client, and some metadata associated with the connection that might be useful elsewhere (i.e.
-/// authentication, etc).
+/// Represents a connection to a single client
 #[derive(Derivative)]
 #[derivative(Debug)]
 pub struct Connection {
+    /// Stream used for communication with the client
     #[derivative(Debug = "ignore")]
     pub stream: Box<dyn ReadWrite + Send>,
+    /// Metadata associated with the connection that might be useful elsewhere (i.e. authentication, etc)
     pub metadata: Option<ConnectionMetadata>,
 }
 

src/key_info_managers/mod.rs

@@ -15,15 +15,21 @@ use std::fmt;
 
 pub mod on_disk_manager;
 
+/// Type of the KeyInfoManager
 #[derive(Copy, Clone, Deserialize, Debug)]
 pub enum KeyInfoManagerType {
+    /// KeyInfoManager storing the mappings on disk
     OnDisk,
 }
 
+/// KeyInfoManager configuration
 #[derive(Deserialize, Debug)]
 pub struct KeyInfoManagerConfig {
+    /// Name of the KeyInfoManager
     pub name: String,
+    /// Type of the KeyInfoManager
     pub manager_type: KeyInfoManagerType,
+    /// Path used to store the mappings
     pub store_path: Option<String>,
 }
 

src/key_info_managers/on_disk_manager/mod.rs

@@ -24,8 +24,10 @@ use std::fs::{DirEntry, File};
 use std::io::{Error, ErrorKind, Read, Write};
 use std::path::PathBuf;
 
+/// Default path where the mapping files will be stored on disk
 pub const DEFAULT_MAPPINGS_PATH: &str = "./mappings";
 
+/// A key info manager storing key triple to key info mapping on files on disk
 #[derive(Debug)]
 pub struct OnDiskKeyInfoManager {
     /// Internal mapping, used for non-modifying operations.
@@ -326,24 +328,28 @@ impl ManageKeyInfo for OnDiskKeyInfoManager {
     }
 }
 
+/// OnDiskKeyInfoManager builder
 #[derive(Debug, Default)]
 pub struct OnDiskKeyInfoManagerBuilder {
     mappings_dir_path: Option<PathBuf>,
 }
 
 impl OnDiskKeyInfoManagerBuilder {
+    /// Create a new OnDiskKeyInfoManagerBuilder
     pub fn new() -> OnDiskKeyInfoManagerBuilder {
         OnDiskKeyInfoManagerBuilder {
             mappings_dir_path: None,
         }
     }
 
+    /// Add a mappings directory path to the builder
     pub fn with_mappings_dir_path(mut self, path: PathBuf) -> OnDiskKeyInfoManagerBuilder {
         self.mappings_dir_path = Some(path);
 
         self
     }
 
+    /// Build into a OnDiskKeyInfoManager
     pub fn build(self) -> std::io::Result<OnDiskKeyInfoManager> {
         OnDiskKeyInfoManager::new(self.mappings_dir_path.ok_or_else(|| {
             error!("Mappings directory path is missing");