From 188b9c18795b410dcd3801c761522e1813581bcd Mon Sep 17 00:00:00 2001
From: 4o1x5 <4o1x5@4o1x5.dev>
Date: Thu, 16 May 2024 15:59:46 +0200
Subject: [PATCH] documentation, and examples

---
 readme.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 97 insertions(+), 6 deletions(-)

diff --git a/readme.md b/readme.md
index a4c525b..fdb67a7 100644
--- a/readme.md
+++ b/readme.md
@@ -15,12 +15,15 @@
       - [Complex select](#complex-select)
       - [Pair match](#pair-match)
       - [Ordering](#ordering)
+      - [File upload](#file-uploads)
 - [Frontend](#frontend)
   - [Themes](#themes)
 - [Server](#server)
   - [Backend](#backend)
   - [Authentication](#authentication)
   - [Data storage](#data-storage)
+  - [Load balancing](#load-balancing)
+- [Staging](#staging)
 
 # Abstract
 
@@ -31,8 +34,6 @@ The objective is to provide a comprehensive feature package, aiming to incorpora
 
 # Feature set
 
-- [Classroom](#classroom)
-
 _[go to top](#contents)_
 
 ## Classroom
@@ -59,6 +60,8 @@ Students may direct message their teachers inside the class. They can ask for he
 
 # Quiz
 
+_[go to top](#contents)_
+
 Teachers can create quizzes that students may fill out. This test is server-side only and students may only know the answer upon finishing it. It can also be disabled by the teacher to prevent cheating
 
 ## Question types
@@ -101,13 +104,13 @@ Teachers can create quizzes that students may fill out. This test is server-side
 
   One point for every correctly ordered card.
 
-### File upload(s)
+- ### File upload(s)
 
-A field where users can select file(s) from their own drive and upload.
+  A field where users can select file(s) from their own drive and upload.
 
-#### Rewarding:
+  #### Rewarding:
 
-Depends. The teacher may give the field a maximum achievable point that user can see when filling out. Then after the test is sent in teachers may grade accordingly.
+  Depends. The teacher may give the field a maximum achievable point that user can see when filling out. Then after the test is sent in teachers may grade accordingly.
 
 ## Drive
 
@@ -117,6 +120,8 @@ It also allows for collaborative work where users can use fully fledged office s
 
 # Frontend
 
+_[go to top](#contents)_
+
 The frontend will be built using react as its one of the most popular and stable javascript frameworks out there. The frontend will be 50% client side and 50% SSR using next.js.
 
 ## Themes
@@ -131,6 +136,8 @@ The frontend will allow users to select from a curated list of themes so they ca
 
 ## Backend
 
+_[go to top](#contents)_
+
 The server will be written in Java more precisely SpringBoot. It will be broken down to microservices for easy _vertical_ scaling.  
 Vertical scaling also allow for redundancy and 99.99% uptime as services can be updated one by one, or updates can be pushed accordingly so that inactive nodes will get the release version and get prioritized. Then older nodes will eventually die off and get updated.
 
@@ -148,6 +155,90 @@ Kubernetes Load Balancer will be used to distribute load along the nodes.
 
 # Staging
 
+_[go to top](#contents)_
+
 In this section the documentation will explain how the application will be built over its lifetime. As this is a massive project, developers need to think thru their decisions on choosing the features and technologies which the application will be built upon. Since LearningPulse will employ many features it's only one way to get started. And that is to start with the bear minimum to get the foundation laying.
 
+# Documentation
+
+Documenting software is key to an open-source project like this. Each class, method and implementation will and have to be documented.
+
+## Server
+
+Javadoc will be used to generate the documentation for each class and their inherited methods and so on.  
+For the API, springboot has a swagger documentation plugin that can auto-generate it on the go. Comments can also be added and examples will be required!
+
+Similar to the frontend, this is a way to describe docs for a function.
+
+```java
+/**
+* Returns an Image object that can then be painted on the screen.
+* The url argument must specify an absolute <a href="#{@link}">{@link URL}</a>. The name
+* argument is a specifier that is relative to the url argument.
+* <p>
+* This method always returns immediately, whether or not the
+* image exists. When this applet attempts to draw the image on
+* the screen, the data will be loaded. The graphics primitives
+* that draw the image will incrementally paint on the screen.
+*
+* @param  url  an absolute URL giving the base location of the image
+* @param  name the location of the image, relative to the url argument
+* @return      the image at the specified URL
+* @see         Image
+*/
+public Image getImage(URL url, String name) {
+  try {
+    return getImage(new URL(url, name));
+  } catch (MalformedURLException e) {
+    return null;
+  }
+}
+```
+
+# Frontend
+
+Documenting the frontend is quite hard, but since there will be also logic hid inside the frontend that too will need to be documented.
+For methods and classes, JSDoc for javascript is the perfect fit.
+
+```typescript
+/**
+ * @param {number}  number - The number we want to check if is prime
+ * @returns {boolean} Return value
+ */
+function is_even(number): boolean {
+  if (number % 2 == 0) {
+    return true;
+  }
+  return false;
+}
+```
+
+For user action descriptions and flow charts [Mermaid](https://github.com/mermaid-js/mermaid) has to be used. We can describe actions that are then generated into SVGs, PNGs, or other formats. They neatly integrate into Forgejo too.
+
+_An example of a state description_
+
+Raw
+
+```
+stateDiagram-v2
+    [*] --> Still
+    Still --> [*]
+    Still --> Moving
+    Moving --> Still
+    Moving --> Crash
+    Crash --> [*]
+```
+
+Output
+
+```mermaid
+stateDiagram-v2
+    [*] --> Still
+    Still --> [*]
+    Still --> Moving
+    Moving --> Still
+    Moving --> Crash
+    Crash --> [*]
+```
+
 ## Alpha