documentation, and examples

This commit is contained in:
2005 2024-05-16 15:59:46 +02:00
parent 794c6b1e0b
commit 188b9c1879

103
readme.md
View file

@ -15,12 +15,15 @@
- [Complex select](#complex-select) - [Complex select](#complex-select)
- [Pair match](#pair-match) - [Pair match](#pair-match)
- [Ordering](#ordering) - [Ordering](#ordering)
- [File upload](#file-uploads)
- [Frontend](#frontend) - [Frontend](#frontend)
- [Themes](#themes) - [Themes](#themes)
- [Server](#server) - [Server](#server)
- [Backend](#backend) - [Backend](#backend)
- [Authentication](#authentication) - [Authentication](#authentication)
- [Data storage](#data-storage) - [Data storage](#data-storage)
- [Load balancing](#load-balancing)
- [Staging](#staging)
# Abstract # Abstract
@ -31,8 +34,6 @@ The objective is to provide a comprehensive feature package, aiming to incorpora
# Feature set # Feature set
- [Classroom](#classroom)
_[go to top](#contents)_ _[go to top](#contents)_
## Classroom ## Classroom
@ -59,6 +60,8 @@ Students may direct message their teachers inside the class. They can ask for he
# Quiz # 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 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 ## 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. 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 ## Drive
@ -117,6 +120,8 @@ It also allows for collaborative work where users can use fully fledged office s
# Frontend # 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. 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 ## Themes
@ -131,6 +136,8 @@ The frontend will allow users to select from a curated list of themes so they ca
## Backend ## 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. 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. 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 # 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. 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 ## Alpha