update the inline documentation strings

Signed-off-by: Ralf Zerres <ralf.zerres@networkx.de>

src/bin/get-roles.rs

@@ -1,7 +1,7 @@
 /*
  * advotracker - Hotline tackingtool for Advocats
  *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
+ * Copyright 2020 Ralf Zerres <ralf.zerres@networkx.de>
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 

src/bin/get-users.rs

@@ -1,7 +1,7 @@
 /*
  * advotracker - Hotline tackingtool for Advocats
  *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
+ * Copyright 2020 Ralf Zerres <ralf.zerres@networkx.de>
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 

src/bin/new-harm.rs

@@ -1,7 +1,7 @@
 /*
  * advotracker - Hotline tackingtool for Advocats
  *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
+ * Copyright 2020 Ralf Zerres <ralf.zerres@networkx.de>
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 

src/bin/new-role.rs

@@ -1,7 +1,7 @@
 /*
  * advotracker - Hotline tackingtool for Advocats
  *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
+ * Copyright 2020 Ralf Zerres <ralf.zerres@networkx.de>
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 

src/bin/new-user.rs

@@ -1,7 +1,7 @@
 /*
  * advotracker - Hotline tackingtool for Advocats
  *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
+ * Copyright 2020 Ralf Zerres <ralf.zerres@networkx.de>
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 

src/functions.rs

@@ -1,15 +0,0 @@
-/*
- * advotracker - Hotline tackingtool for Advocats
- *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
- * SPDX-License-Identifier: (0BSD or MIT)
- */
-
-// table specific functions
-pub mod db_connection;
-pub mod harms;
-pub mod roles;
-pub mod user_roles;
-pub mod users;
-//pub mod wip;
-pub mod tests;

src/functions/db_connection.rs

@@ -12,7 +12,7 @@ use diesel::sqlite::Sqlite;
 use dotenv::dotenv;
 use std::env;
 
-// generic functions
+/// establish a sqlite connection
 pub fn establish_connection() -> SqliteConnection {
     // load our .env file
     dotenv().ok();
@@ -22,17 +22,18 @@ pub fn establish_connection() -> SqliteConnection {
 
     // establish a new SQLite connection (taking the reference from database_url)
     SqliteConnection::establish(&database_url)
-	.unwrap_or_else(|_| panic!("Error connecting to {}", &database_url))
+        .unwrap_or_else(|_| panic!("Error connecting to {}", &database_url))
     /*
      * WIP: integrate tracing!
     trace!(
-	target: "diesel",
+        target: "diesel",
-	type: "Sqlite3",
+        type: "Sqlite3",
-	status: "connected"
+        status: "connected"
     );
      */
 }
 
+/// show the sql query
 pub fn show_query<T>(query: &T)
 where
     T: diesel::query_builder::QueryFragment<Sqlite>,

src/functions/harms.rs

@@ -28,6 +28,7 @@ impl Harm {
     // set-    -> Update
     // remove- -> Delete
 
+    /// create a new harm record
     pub fn new(
         param_id_harm: &str,
         param_id_policyholder: Option<&str>,

src/functions/roles.rs

@@ -28,6 +28,7 @@ impl Role {
     // update- -> Update
     // delete- -> Delete
 
+    /// create a new role record
     pub fn new(
         param_role_name: &str,
         param_id_user_changed: i32,
@@ -64,6 +65,7 @@ impl Role {
     }
      */
 
+    /// get all role records
     pub fn get_all(connection: &SqliteConnection) -> Box<Vec<Role>> {
         Box::new(
             roles
@@ -73,6 +75,7 @@ impl Role {
         )
     }
 
+    /// get a role record
     pub fn get(
         param_role_name: &str,
         connection: &SqliteConnection, //) -> Vec<Role> {
@@ -86,6 +89,7 @@ impl Role {
         Ok(query)
     }
 
+    /// update a role record
     pub fn update(
         param_id: i32,
         param_role_name: &str,

src/functions/user_roles.rs

@@ -19,6 +19,7 @@ use crate::schema::user_roles::dsl::*;
 use crate::schema::user_roles::*;
 
 impl UserRole {
+    /// create a new user role record
     pub fn new(
         param_id_user: i32,
         param_id_role: i32,
@@ -38,6 +39,7 @@ impl UserRole {
         Ok(())
     }
 
+    /// get a list of all user role records
     pub fn get_all(connection: &SqliteConnection) -> Box<Vec<UserRole>> {
         Box::new(
             user_roles
@@ -47,6 +49,7 @@ impl UserRole {
         )
     }
 
+    /// get a user role record
     pub fn get(
         param_id_role: i32,
         connection: &SqliteConnection,
@@ -60,6 +63,7 @@ impl UserRole {
         Ok(query)
     }
 
+    /// update a user role record
     pub fn update(
         param_id_user: i32,
         param_id_role: i32,

src/functions/users.rs

@@ -28,6 +28,7 @@ impl User {
     // set-    -> Update
     // remove- -> Delete
 
+    /// create a new user record
     pub fn new(
         param_last_name: &str,
         param_first_name: Option<&str>,
@@ -60,6 +61,7 @@ impl User {
         Ok(())
     }
 
+    /// get a list of all user records
     pub fn get_all(connection: &SqliteConnection) -> Box<Vec<User>> {
         Box::new(
             users
@@ -84,6 +86,7 @@ impl User {
     }
      */
 
+    /// update a user record
     pub fn update(param_id: i32, connection: &SqliteConnection) -> Result<(), Box<dyn Error>> {
         let query = users.filter(id.eq(param_id)).execute(connection)?;
 
@@ -92,24 +95,26 @@ impl User {
         Ok(())
     }
 
-    // helper functions
+    // create a hash value for the user password
     pub fn hash_password(plain: &str) -> Result<String, Box<dyn Error>> {
         Ok(hash(plain, DEFAULT_COST)?)
     }
 
-    // tests
+     /// update the confirmation status of a user emak address
     pub fn set_users_email_confirmed(connection: &SqliteConnection) -> QueryResult<usize> {
         diesel::update(users)
             .set(email_confirmed.eq(1))
             .execute(connection)
     }
 
+    /// update a singel column of a given user record
     pub fn set_users_single_column(connection: &SqliteConnection) -> QueryResult<usize> {
         diesel::insert_into(users)
             .values(alias_name.eq("Hiedemann"))
             .execute(connection)
     }
 
+    /// update multiple columns of a given user record
     pub fn set_users_multiple_columns(connection: &SqliteConnection) -> QueryResult<usize> {
         diesel::insert_into(users)
             .values((
@@ -120,6 +125,7 @@ impl User {
             .execute(connection)
     }
 
+    /// update multiple columns of a given user record with a json string
     pub fn set_user_struct_json(connection: &SqliteConnection) -> Result<(), Box<dyn Error>> {
         let json = r#"{ "first_name": "Daniela", "last_name": "Knocke", "alias_name": "Sekretariat", "email": "knocke@kanzlei.hiedemann.de",  "email_confirmed": 1, "password_hash": "", "initials": "dkn" }"#;
         let user_struct = serde_json::from_str::<NewUser>(json)?;
@@ -147,6 +153,7 @@ impl User {
 
 impl<'a> RegisterUser<'a> {
     //pub fn validates(self) -> Result<(), Error> {
+    /// validate the password hash
     pub fn validates(self) -> Result<RegisterUser<'a>, &'static str> {
         let password_are_equal = self.password_hash == self.password_confirmation;
         let password_not_empty = self.password_hash.len() > 0;

src/lib.rs

@@ -5,16 +5,26 @@
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 
-// backend database crate
+#![warn(missing_docs, rust_2018_idioms, rust_2018_compatibility)]
 //#![recursion_limit = "128"]
-#![warn(clippy::pedantic)]
+//#![warn(clippy::pedantic)]
-#![warn(clippy::nursery)]
+//#![warn(clippy::nursery)]
 
-// modules
+//! advotracker database
-pub mod models;
+//! Supports lawyers to capture relevant data encountered during an
-pub mod schema;
+//! online legal advice.
+//! This SQL database backend will consuming Diesel to make use of
+//! sql features.
 
+// ?? is this needed in edition 2018 anymore ??
 #[macro_use]
 extern crate diesel;
 
+/// SQL functions and methods
 pub mod functions;
+
+/// SQL models definitions
+pub mod models;
+
+/// SQL schema definitions
+pub mod schema;

src/models.rs

@@ -1,16 +0,0 @@
-/*
- * advotracker - Hotline tackingtool for Advocats
- *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
- * SPDX-License-Identifier: (0BSD or MIT)
- */
-
-// bring models into scope
-pub mod roles;
-pub mod harms;
-pub mod users;
-pub mod user_roles;
-
-// methods used for: INSERT
-//pub mod insert;
-//use insert::types::*;

src/models/claims.rs

@@ -1,26 +1,32 @@
 /*
  * advotracker - Hotline tackingtool for Advocats
  *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
+ * Copyright 2020 Ralf Zerres <ralf.zerres@networkx.de>
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 
-use crait::schema::claim.rs;
+use crate::schema::claim;
 
-//#[derive(Debug, Deserialize, PartialEq, Queryable)]
+/// Stucture of a claim record
 #[derive(Debug, Queryable)]
 pub struct Claim {
-    // id: the auto incremented primary index
+    /// the auto incremented primary index
     pub id: i32,
+    /// the user id
     pub user_id: i32,
+    /// the type of the user
     pub type_: Option<String>,
+    /// the name string of the claim type
     pub value: Option<String>,
 }
 
+/// Structure of a new claim record
 #[derive(Debug, Deserialize, Insertable)]
 #[table_name = "claims"]
 pub struct NewClaim<'a> {
     //pub user_id: &'a i32,
+    /// Lifetime to the claim type
     pub type_: Option<&'a str>,
+    /// Lifetime to the name of the claim type
     pub value: Option<&'a str>,
 }

src/models/harms.rs

@@ -1,7 +1,7 @@
 /*
  * advotracker - Hotline tackingtool for Advocats
  *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
+ * Copyright 2020 Ralf Zerres <ralf.zerres@networkx.de>
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 
@@ -11,33 +11,51 @@ use serde_derive::*;
 
 use crate::schema::harms;
 
-//usage: SELECT, UPDATE, DELETE
+/// Manage harm records (SELECT, UPDATE, DELETE)
 #[derive(AsChangeset, Debug, Deserialize, Identifiable, PartialEq, Queryable)]
 pub struct Harm {
-    // id: the auto incremented primary index
+    /// the auto incremented primary index
     pub id: i32,
+    /// the harm name
     pub id_harm: String,
+    /// the policy holder name
     pub id_policyholder: Option<String>,
+    /// the callback number
     pub id_callback: Option<String>,
+    /// the fallback date
     pub date_fallback: Option<NaiveDateTime>,
+    /// the date the record was recorded
     pub date_recording: NaiveDateTime,
+    /// the user id
     pub id_user: i32,
+    /// the date the record was created
     pub date_created: NaiveDateTime,
+    /// the user id that has chanced the record
     pub id_user_changed: i32,
+    /// the date the record was changed
     pub date_changed: NaiveDateTime,
 }
 
-// usage: INSERT
+/// Structure of a new harm
 #[derive(Debug, Deserialize, Insertable, Serialize)]
 #[table_name = "harms"]
 pub struct NewHarm<'a> {
+    /// Lifetime to the harm name
     pub id_harm: &'a str,
+    /// Lifetime to the policyholder
     pub id_policyholder: Option<&'a str>,
+    /// Lifetime to the callback number
     pub id_callback: Option<&'a str>,
+    /// the fallback date
     pub date_fallback: Option<NaiveDateTime>,
+    /// the date the record was recorded
     pub date_recording: NaiveDateTime,
+    /// the user id that has chanced the record
     pub id_user: i32,
+    /// the date the record was created
     pub date_created: Option<NaiveDateTime>,
+    /// the user id that has chanced the record
     pub id_user_changed: i32,
+    /// Lifetime to the date the record was changed
     pub date_changed: Option<NaiveDateTime>,
 }

src/models/insert.rs

@@ -1,7 +1,7 @@
 /*
  * advotracker - Hotline tackingtool for Advocats
  *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
+ * Copyright 2020 Ralf Zerres <ralf.zerres@networkx.de>
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 

src/models/roles.rs

@@ -1,7 +1,7 @@
 /*
  * advotracker - Hotline tackingtool for Advocats
  *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
+ * Copyright 2020 Ralf Zerres <ralf.zerres@networkx.de>
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 
@@ -11,23 +11,33 @@ use serde_derive::*;
 
 use crate::schema::roles;
 
+/// Structure of a role record
 #[derive(AsChangeset, Debug, Deserialize, Identifiable, PartialEq, Queryable)]
 #[table_name = "roles"]
 pub struct Role {
-    // id: the auto incremented primary index
+    /// The auto incremented primary index
     pub id: i32,
+    /// The role name
     pub name: String,
+    /// Creation date of the role
     pub date_created: NaiveDateTime,
+    /// The user id, that has changed the record
     pub id_user_changed: i32,
+    /// The timestamp, when the record was changed
     pub date_changed: NaiveDateTime,
 }
 
+/// Structure of a new claim record
 #[derive(Debug, Deserialize, Insertable, Serialize)]
 #[table_name = "roles"]
 pub struct NewRole<'a> {
+    /// Lifetime of the role name
     pub name: &'a str,
+    /// Creation date of the role
     pub date_created: Option<NaiveDateTime>,
+    /// The user id, that has changed the record
     pub id_user_changed: i32,
+    /// The timestamp, when the record was changed
     pub date_changed: Option<NaiveDateTime>,
 }
 

src/models/user_roles.rs

@@ -1,23 +1,28 @@
 /*
  * advotracker - Hotline tackingtool for Advocats
  *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
+ * Copyright 2020 Ralf Zerres <ralf.zerres@networkx.de>
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 
 use crate::schema::user_roles;
 use serde_derive::*;
 
+/// Structure of a user role record
 #[derive(Debug, Queryable, PartialEq)]
 pub struct UserRole {
+    /// id of the referenced user
     pub id_user: i32,
+    /// id of the referenced role
     pub id_role: i32,
 }
 
-//#[derive(Deserialize)]
+/// Structure of a new user role record
 #[derive(Deserialize, Insertable)]
 #[table_name = "user_roles"]
 pub struct NewUserRole {
+    /// id of the referenced user
     pub id_user: i32,
+    /// id of the referenced role
     pub id_role: i32,
 }

src/models/users.rs

@@ -1,7 +1,7 @@
 /*
  * advotracker - Hotline tackingtool for Advocats
  *
- * Copyright 2019 Ralf Zerres <ralf.zerres@networkx.de>
+ * Copyright 2020 Ralf Zerres <ralf.zerres@networkx.de>
  * SPDX-License-Identifier: (0BSD or MIT)
  */
 
@@ -11,25 +11,35 @@ use serde_derive::*;
 
 use crate::schema::users;
 
-// usage: SELECT, UPDATE, DELETE
+/// Structure of a user record
 #[derive(AsChangeset, Debug, Deserialize, Identifiable, PartialEq, Queryable, Serialize)]
 pub struct User {
-    // id: the auto incremented primary index
+    /// the auto incremented primary index
     pub id: i32,
+    /// last name of the user
     pub last_name: String,
     // Option -> returns "None", if db value is null
+    /// first name of the user
     pub first_name: Option<String>,
+    /// alias of the user name
     pub alias_name: Option<String>,
+    /// users email address
     pub email: Option<String>,
+    /// confirmation state of users email address
     pub email_confirmed: Option<i32>,
+    /// users initials
     pub initials: Option<String>,
+    /// users password hash
     pub password_hash: Option<String>,
+    /// timestamp when the record was created
     pub date_created: NaiveDateTime,
+    /// user id that has changed the record
     pub id_changed: i32,
+    /// timestamp when the record was changed
     pub date_changed: NaiveDateTime,
 }
 
-// usage: INSERT
+/// Structure of a new user record
 #[derive(Debug, Deserialize, Insertable, Serialize)]
 #[table_name = "users"]
 pub struct NewUser<'a> {
@@ -45,9 +55,13 @@ pub struct NewUser<'a> {
     pub date_changed: Option<NaiveDateTime>,
 }
 
+
+/// Structure of a user registration
 #[derive(Debug, Deserialize, Queryable)]
 pub struct RegisterUser<'a> {
+    /// Lifetime of users last name
     pub last_name: &'a str,
+    /// Lifetime of users first name
     pub first_name: Option<&'a str>,
     pub alias: Option<&'a str>,
     pub email: Option<&'a str>,