documentation updates

shared/src/apirequests/general.rs

@@ -1,6 +1,8 @@
+//! The more generic request datatypes
 use std::ops::Deref;
 
 use serde::{Deserialize, Serialize};
+/// Filter one column according to the containing string.
 #[derive(Clone, Deserialize, Serialize, Debug, Default)]
 pub struct Filter {
     pub sieve: String,
@@ -14,18 +16,21 @@ impl Deref for Filter {
     }
 }
 
+/// Possible order directions
 #[derive(Clone, Deserialize, Serialize, PartialEq, Eq, Debug)]
 pub enum Ordering {
     Ascending,
     Descending,
 }
 
+/// An operation on a column
 #[derive(Clone, Deserialize, Serialize, Debug)]
 pub struct Operation<T, V> {
     pub column: T,
     pub value: V,
 }
 
+/// To differentiate between creating a new record and editing.
 #[derive(Clone, Deserialize, Serialize, Debug, PartialEq, Eq)]
 pub enum EditMode {
     Create,
@@ -38,11 +43,13 @@ impl Default for EditMode {
     }
 }
 
+/// When a message is sent between client and server (like for a dialog).
 #[derive(Clone, Deserialize, Serialize, Debug)]
 pub struct Message {
     pub message: String,
 }
 
+/// Send a message on success and also one on error.
 #[derive(Clone, Deserialize, Serialize, Debug)]
 pub enum Status {
     Success(Message),

shared/src/apirequests/links.rs

@@ -1,3 +1,5 @@
+//! types for link requesting and saving.
+
 use enum_map::{Enum, EnumMap};
 use serde::{Deserialize, Serialize};
 
@@ -5,7 +7,7 @@ use crate::datatypes::{FullLink, Link};
 
 use super::general::{EditMode, Filter, Operation, Ordering};
 
-/// A generic list returntype containing the User and a Vec containing e.g. Links or Users
+/// Request a list of users respecting the filter and ordering.
 #[derive(Clone, Deserialize, Serialize, Debug)]
 pub struct LinkRequestForm {
     pub filter: EnumMap<LinkOverviewColumns, Filter>,
@@ -23,7 +25,7 @@ impl Default for LinkRequestForm {
     }
 }
 
-/// The Struct that is responsible for creating and editing users.
+/// The Struct that is responsible for creating and editing links.
 #[derive(Default, Debug, Clone, Serialize, Deserialize)]
 pub struct LinkDelta {
     pub edit: EditMode,
@@ -36,7 +38,7 @@ pub struct LinkDelta {
 }
 
 impl From<Link> for LinkDelta {
-    /// Automatically create a `UserDelta` from a User.
+    /// Automatically create a `LinkDelta` from a Link.
     fn from(l: Link) -> Self {
         Self {
             edit: EditMode::Edit,
@@ -51,7 +53,7 @@ impl From<Link> for LinkDelta {
 }
 
 impl From<FullLink> for LinkDelta {
-    /// Automatically create a `UserDelta` from a User.
+    /// Automatically create a `LinkDelta` from a FullLink.
     fn from(l: FullLink) -> Self {
         Self {
             edit: EditMode::Edit,
@@ -65,6 +67,7 @@ impl From<FullLink> for LinkDelta {
     }
 }
 
+/// An enumeration of the filterable columns
 #[derive(Clone, Deserialize, Serialize, Debug, PartialEq, Eq, Hash, Enum)]
 pub enum LinkOverviewColumns {
     Code,
@@ -74,17 +77,20 @@ pub enum LinkOverviewColumns {
     Statistics,
 }
 
+/// A struct to request a qr-code from the server
 #[derive(Clone, Deserialize, Serialize, Debug, PartialEq, Eq)]
 pub struct QrCodeRequest {
     pub link_id: String,
     pub format: QrCodeFormat,
 }
 
+/// The response to a qr-request
 #[derive(Clone, Deserialize, Serialize, Debug, PartialEq, Eq)]
 pub struct SvgQrCodeResponse {
     pub svg: String,
 }
 
+/// Available formats of qr-codes
 #[derive(Clone, Deserialize, Serialize, Debug, PartialEq, Eq)]
 pub enum QrCodeFormat {
     Svg,

shared/src/apirequests/mod.rs

@@ -1,3 +1,4 @@
+//! This module contains the structs for api requests.
 pub mod general;
 pub mod links;
 pub mod users;

shared/src/apirequests/users.rs

@@ -1,3 +1,4 @@
+//! Types for user requesting and saving
 use enum_map::{Enum, EnumMap};
 use serde::{Deserialize, Serialize};
 
@@ -5,6 +6,7 @@ use crate::datatypes::User;
 
 use super::general::{EditMode, Filter, Operation, Ordering};
 
+/// Request an ordered and filtered list of users from the server.
 #[derive(Clone, Deserialize, Serialize, Debug)]
 pub struct UserRequestForm {
     // The filters up to one for each column
@@ -25,6 +27,7 @@ impl Default for UserRequestForm {
     }
 }
 
+/// Data to login.
 #[derive(Debug, Deserialize, Default, Serialize, Clone)]
 pub struct LoginUser {
     pub username: String,
@@ -65,7 +68,7 @@ pub enum UserOverviewColumns {
     Username,
 }
 
-/// The possible roles a user could have.
+/// The possible roles a user could have. They are stored as i64 in the database
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Copy)]
 pub enum Role {
     NotAuthenticated,

shared/src/datatypes.rs

@@ -1,3 +1,4 @@
+//! The more generic datatypes used in pslink
 use std::ops::Deref;
 
 use serde::{Deserialize, Serialize, Serializer};
@@ -19,6 +20,7 @@ pub struct FullLink {
     pub clicks: Count,
 }
 
+/// A User of the pslink service
 #[derive(PartialEq, Serialize, Deserialize, Clone, Debug)]
 pub struct User {
     pub id: i64,
@@ -29,6 +31,7 @@ pub struct User {
     pub language: Lang,
 }
 
+/// A short url of the link service
 #[derive(Serialize, Deserialize, Clone, Debug)]
 pub struct Link {
     pub id: i64,
@@ -39,10 +42,13 @@ pub struct Link {
     pub created_at: chrono::NaiveDateTime,
 }
 
+/// When statistics are counted
 #[derive(Serialize, Deserialize, Clone, Debug)]
 pub struct Count {
     pub number: i32,
 }
+
+/// Everytime a shor url is clicked record it for statistical evaluation.
 #[derive(Serialize, Debug)]
 pub struct Click {
     pub id: i64,
@@ -50,6 +56,7 @@ pub struct Click {
     pub created_at: chrono::NaiveDateTime,
 }
 
+/// The Password: Display, Debug and serialize do not include the Password to prevent leaks of sensible information in logs or similar.
 #[derive(PartialEq, Clone, Deserialize)]
 #[serde(from = "String")]
 pub struct Secret {
@@ -92,6 +99,7 @@ impl std::fmt::Display for Secret {
     }
 }
 
+/// Loadable is a type that has not been loaded but will be in future. It can be used to indicate the loading process.
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub enum Loadable<T> {
     Data(Option<T>),