Merge pull request #89 from h1alexbel/84-missing-docs

feat(#84): deny on missing_docs, routes -> handlers

server/Cargo.toml

@@ -34,6 +34,9 @@ authors = ["Aliaksei Bialíauski <[email protected]>", "Ivanchuk Ivan
 [lib]
 path = "src/lib.rs"
 
+[lints.rust]
+missing_docs = "deny"
+
 [dependencies]
 openapi = { path = "../github-mirror" }
 anyhow = "1.0.86"

server/src/routes/home.rs → server/src/handlers/home.rs

@@ -27,10 +27,7 @@ use log::debug;
 use crate::ServerConfig;
 use openapi::models::MetaRoot200Response;
 
-// @todo #79:45min Make mod/fn/struct documentation required.
-//  Let's configure cargo in such way, so documentation will be required at all
-//  levels. When such rule will be configured, please fix all warnings/errors
-//  and integrate changes into master branch.
+/// Home handler.
 pub async fn home(State(config): State<ServerConfig>) -> impl IntoResponse {
     let response = Json(
         MetaRoot200Response::new(
@@ -191,7 +188,7 @@ pub async fn home(State(config): State<ServerConfig>) -> impl IntoResponse {
 
 #[cfg(test)]
 mod tests {
-    use crate::routes::home::home;
+    use crate::handlers::home::home;
     use crate::ServerConfig;
     use anyhow::Result;
     use axum::body::to_bytes;

server/src/routes/mod.rs → server/src/handlers/mod.rs

@@ -19,6 +19,7 @@
 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
+/// Home handler.
 pub mod home;
+/// Handler for internal user registration.
 pub mod register_user;
-pub mod rs_err;

server/src/routes/register_user.rs → server/src/handlers/register_user.rs

@@ -24,6 +24,20 @@ use axum::Json;
 
 use crate::objects::user::User;
 
+/// Register user.
+///
+/// # Fields
+///
+/// * `payload`: JSON payload
+///
+/// # Examples
+///
+/// ```
+/// use axum::Json;
+/// use server::handlers::register_user::register_user;
+/// use server::objects::user::User;
+/// let registration = register_user(Json(User::new(String::from("jeff"))));
+/// ```
 pub async fn register_user(Json(payload): Json<User>) -> Result<StatusCode, String> {
     let user = User::new(payload.username.clone());
     match user.save().await {

server/src/lib.rs

@@ -19,46 +19,71 @@
 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
+/*!
+Fakehub server and storage.
+ */
 use std::io;
 
 use anyhow::Result;
 use axum::routing::{get, post};
 use axum::Router;
 use tokio::net::TcpListener;
 
-use crate::routes::home;
-use crate::routes::register_user::register_user;
+use crate::handlers::home;
+use crate::handlers::register_user::register_user;
 use crate::xml::storage::Storage;
 
-mod objects;
+/// Handlers.
+pub mod handlers;
+/// GitHub domain objects.
+pub mod objects;
+/// Reports.
 pub mod report;
-mod routes;
-mod xml;
+/// XML storage.
+pub mod xml;
 #[allow(unused_imports)]
 #[macro_use]
 extern crate hamcrest;
 
+/// Server.
 #[derive(Default)]
 pub struct Server {
+    /// Port.
     port: usize,
 }
 
 impl Server {
+    /// Create new server with port.
+    ///
+    /// * `port`: Server port
+    ///
+    /// returns: Server
+    ///
+    /// Examples:
+    ///
+    /// ```
+    /// use server::Server;
+    /// let server = Server::new(1234);
+    /// ```
     pub fn new(port: usize) -> Server {
         Server { port }
     }
 }
 
+/// Server configuration.
 #[derive(Clone)]
 pub struct ServerConfig {
+    /// Server host.
     pub host: String,
+    /// Server port.
     pub port: usize,
 }
 
 // @todo #79:30min Log 404 NOT FOUND requests too.
 //  Let's create a handler that would log requests failed with 404. Let's use
 //  info!() for this one.
 impl Server {
+    /// Start a server.
     pub async fn start(self) -> Result<()> {
         tracing_subscriber::fmt::init();
         Storage::new(Some("fakehub.xml"));

server/src/objects/mod.rs

@@ -19,4 +19,5 @@
 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
+/// GitHub user.
 pub mod user;

server/src/objects/user.rs

@@ -24,12 +24,26 @@ use log::{debug, info};
 use serde::{Deserialize, Serialize};
 use serde_xml_rs::to_string;
 
+/// GitHub user.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct User {
+    /// Username.
     pub(crate) username: String,
 }
 
 impl User {
+    /// New user.
+    ///
+    /// # Fields
+    ///
+    /// * `username`: Username
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use server::objects::user::User;
+    /// let jeff = User::new(String::from("jeff123"));
+    /// ```
     pub fn new(username: String) -> User {
         User { username }
     }
@@ -45,8 +59,9 @@ impl User {
 //  We should prohibit to use #unwrap() function in our code. Let's configure
 //  clippy tool in the respective manner and get rid of all #unwrap() calls.
 impl User {
+    /// Save user.
     pub async fn save(self) -> Result<()> {
-        info!("registering user @{}", self.username);
+        info!("saving user @{}", self.username);
         let xml = to_string(&self).unwrap();
         debug!("XMLed user: {}", xml);
         Ok(())

server/src/report/mod.rs

@@ -22,4 +22,5 @@
 // @todo #41:45min Create similar to latex.rs functions for XML and TXT formats.
 //  Let's create similar to latex.rs functions for generating reports in XML and TXT.
 //  Don't forget to remove this puzzle.
+/// LaTeX report.
 pub mod latex;

server/src/xml/mod.rs

@@ -19,4 +19,5 @@
 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
+/// Storage.
 pub mod storage;

server/src/xml/storage.rs

@@ -1,6 +1,3 @@
-use std::fs::File;
-use std::io::Write;
-
 // The MIT License (MIT)
 //
 // Copyright (c) 2024 Aliaksei Bialiauski
@@ -24,9 +21,12 @@ use std::io::Write;
 // SOFTWARE.
 use anyhow::Result;
 use log::info;
+use std::fs::File;
+use std::io::Write;
 
 #[derive(Default)]
 #[allow(dead_code)]
+/// Storage.
 pub struct Storage {
     pub(crate) path: String,
 }
@@ -37,6 +37,22 @@ const INIT_XML: &str = "<root>
 ";
 
 impl Storage {
+    /// New storage.
+    ///
+    /// # Fields
+    /// * `path`: Storage path
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use server::xml::storage::Storage;
+    /// let storage = Storage::new(Some("test.xml"));
+    /// ```
+    /// Or use default path:
+    /// ```
+    /// use server::xml::storage::Storage;
+    /// let storage = Storage::new(None);
+    /// ```
     pub fn new(path: Option<&str>) -> Storage {
         let location = path.unwrap_or("fakehub.xml");
         info!("Initializing XML storage: {location}");
@@ -62,6 +78,7 @@ impl Storage {
 //  Don't forget to create a unit tests related to #xml function.
 impl Storage {
     #[allow(dead_code)]
+    /// Return XML from the storage.
     pub fn xml() -> Result<()> {
         Ok(())
     }