From 0c1b112ea89729b02e5791ef905486eac18d447c Mon Sep 17 00:00:00 2001
From: Jakob Fahr <me@jfhr.de>
Date: Sun, 12 Jul 2020 22:25:13 +0200
Subject: [PATCH] Add comments to backend.service

---
 src/app/services/backend.service.ts | 153 ++++++++++++++++++++++++++++
 1 file changed, 153 insertions(+)

diff --git a/src/app/services/backend.service.ts b/src/app/services/backend.service.ts
index 3816388..ef79bad 100644
--- a/src/app/services/backend.service.ts
+++ b/src/app/services/backend.service.ts
@@ -3,47 +3,76 @@ import { HttpClient, HttpResponse } from '@angular/common/http';
 import { Observable } from 'rxjs';
 import { environment } from '../../environments/environment';
 
+/**
+ * Provides access to the backend via HTTP.
+ */
 @Injectable()
 export class BackendService {
   constructor(private httpClient: HttpClient) {}
 
   // Tasks
+
+  /**
+   * Return all tasks.
+   */
   public getTasks(): Observable<HttpResponse<ScrumTask[]>> {
     const url = `${environment.apiUrl}/tasks`;
     return this.httpClient.get<ScrumTask[]>(url, { observe: 'response' });
   }
 
+  /**
+   * Return the task with a specific id.
+   */
   public getTask(id: number): Observable<HttpResponse<ScrumTask>> {
     const url = `${environment.apiUrl}/tasks/${id}`;
     return this.httpClient.get<ScrumTask>(url, { observe: 'response' });
   }
 
+  /**
+   * Create a new task, if successful, the newly created task will be returned.
+   */
   public postTask(task: ScrumTask): Observable<HttpResponse<ScrumTask>> {
     const url = `${environment.apiUrl}/tasks`;
     return this.httpClient.post<ScrumTask>(url, task, { observe: 'response' });
   }
 
+  /**
+   * Replace an existing task with a new one.
+   */
   public putTask(task: ScrumTask): Observable<HttpResponse<any>> {
     const url = `${environment.apiUrl}/tasks/${task.id}`;
     return this.httpClient.put(url, task, { observe: 'response' });
   }
 
+  /**
+   * Delete a task.
+   */
   public deleteTask(task: ScrumTask): Observable<HttpResponse<any>> {
     const url = `${environment.apiUrl}/tasks/${task.id}`;
     return this.httpClient.delete(url, { observe: 'response' });
   }
 
   // Userstories
+
+  /**
+   * Return all userstories.
+   */
   public getUserstories(): Observable<HttpResponse<ScrumUserstory[]>> {
     const url = `${environment.apiUrl}/userstories`;
     return this.httpClient.get<ScrumUserstory[]>(url, { observe: 'response' });
   }
 
+  /**
+   * Return the userstory with a specific id.
+   */
   public getUserstory(id: number): Observable<HttpResponse<ScrumUserstory>> {
     const url = `${environment.apiUrl}/userstories/${id}`;
     return this.httpClient.get<ScrumUserstory>(url, { observe: 'response' });
   }
 
+  /**
+   * Create a new userstory, if successful, the newly created userstory will be returned.
+   */
   public postUserstory(
     userstory: ScrumUserstory
   ): Observable<HttpResponse<ScrumUserstory>> {
@@ -53,6 +82,9 @@ export class BackendService {
     });
   }
 
+  /**
+   * Replace an existing userstory with a new one.
+   */
   public putUserstory(
     userstory: ScrumUserstory
   ): Observable<HttpResponse<any>> {
@@ -60,6 +92,9 @@ export class BackendService {
     return this.httpClient.put(url, userstory, { observe: 'response' });
   }
 
+  /**
+   * Delete a userstory.
+   */
   public deleteUserstory(
     userstory: ScrumUserstory
   ): Observable<HttpResponse<any>> {
@@ -68,16 +103,26 @@ export class BackendService {
   }
 
   // Sprints
+
+  /**
+   * Return all sprints.
+   */
   public getSprints(): Observable<HttpResponse<ScrumSprint[]>> {
     const url = `${environment.apiUrl}/sprints`;
     return this.httpClient.get<ScrumSprint[]>(url, { observe: 'response' });
   }
 
+  /**
+   * Return the sprint with a specific id.
+   */
   public getSprint(id: number): Observable<HttpResponse<ScrumSprint>> {
     const url = `${environment.apiUrl}/sprints/${id}`;
     return this.httpClient.get<ScrumSprint>(url, { observe: 'response' });
   }
 
+  /**
+   * Create a new sprint, if successful, the newly created sprint will be returned.
+   */
   public postSprint(
     sprint: ScrumSprint
   ): Observable<HttpResponse<ScrumSprint>> {
@@ -87,27 +132,43 @@ export class BackendService {
     });
   }
 
+  /**
+   * Replace an existing sprint with a new one.
+   */
   public putSprint(sprint: ScrumSprint): Observable<HttpResponse<any>> {
     const url = `${environment.apiUrl}/sprints/${sprint.id}`;
     return this.httpClient.put(url, sprint, { observe: 'response' });
   }
 
+  /**
+   * Delete a sprint.
+   */
   public deleteSprint(sprint: ScrumSprint): Observable<HttpResponse<any>> {
     const url = `${environment.apiUrl}/sprints/${sprint.id}`;
     return this.httpClient.delete(url, { observe: 'response' });
   }
 
   // Categories
+
+  /**
+   * Return all categories.
+   */
   public getCategories(): Observable<HttpResponse<ScrumCategory[]>> {
     const url = `${environment.apiUrl}/categories`;
     return this.httpClient.get<ScrumCategory[]>(url, { observe: 'response' });
   }
 
+  /**
+   * Return the category with a specific id.
+   */
   public getCategory(id: number): Observable<HttpResponse<ScrumCategory>> {
     const url = `${environment.apiUrl}/categories/${id}`;
     return this.httpClient.get<ScrumCategory>(url, { observe: 'response' });
   }
 
+  /**
+   * Create a new category, if successful, the newly created category will be returned.
+   */
   public postCategory(
     category: ScrumCategory
   ): Observable<HttpResponse<ScrumCategory>> {
@@ -117,11 +178,17 @@ export class BackendService {
     });
   }
 
+  /**
+   * Replace an existing category with a new one.
+   */
   public putCategory(category: ScrumCategory): Observable<HttpResponse<any>> {
     const url = `${environment.apiUrl}/categories/${category.id}`;
     return this.httpClient.put(url, category, { observe: 'response' });
   }
 
+  /**
+   * Delete a category.
+   */
   public deleteCategory(
     category: ScrumCategory
   ): Observable<HttpResponse<any>> {
@@ -130,16 +197,26 @@ export class BackendService {
   }
 
   // Status
+
+  /**
+   * Return all status.
+   */
   public getAllStatus(): Observable<HttpResponse<ScrumStatus[]>> {
     const url = `${environment.apiUrl}/status`;
     return this.httpClient.get<ScrumStatus[]>(url, { observe: 'response' });
   }
 
+  /**
+   * Return the status with a specific id.
+   */
   public getStatus(id: number): Observable<HttpResponse<ScrumStatus>> {
     const url = `${environment.apiUrl}/status/${id}`;
     return this.httpClient.get<ScrumStatus>(url, { observe: 'response' });
   }
 
+  /**
+   * Create a new status, if successful, the newly created status will be returned.
+   */
   public postStatus(
     status: ScrumStatus
   ): Observable<HttpResponse<ScrumStatus>> {
@@ -149,53 +226,85 @@ export class BackendService {
     });
   }
 
+  /**
+   * Replace an existing status with a new one.
+   */
   public putStatus(status: ScrumStatus): Observable<HttpResponse<any>> {
     const url = `${environment.apiUrl}/status/${status.id}`;
     return this.httpClient.put(url, status, { observe: 'response' });
   }
 
+  /**
+   * Delete a status.
+   */
   public deleteStatus(status: ScrumStatus): Observable<HttpResponse<any>> {
     const url = `${environment.apiUrl}/status/${status.id}`;
     return this.httpClient.delete(url, { observe: 'response' });
   }
 
   // Users
+
+  /**
+   * Return all users.
+   */
   public getUsers(): Observable<HttpResponse<ScrumUser[]>> {
     const url = `${environment.apiUrl}/users`;
     return this.httpClient.get<ScrumUser[]>(url, { observe: 'response' });
   }
 
+  /**
+   * Return the user with a specific id.
+   */
   public getUser(id: number): Observable<HttpResponse<ScrumUser>> {
     const url = `${environment.apiUrl}/users/${id}`;
     return this.httpClient.get<ScrumUser>(url, { observe: 'response' });
   }
 
+  /**
+   * Create a new user, if successful, the newly created user will be returned.
+   */
   public postUser(user: ScrumUser): Observable<HttpResponse<ScrumUser>> {
     const url = `${environment.apiUrl}/users`;
     return this.httpClient.post<ScrumUser>(url, user, { observe: 'response' });
   }
 
+  /**
+   * Replace an existing user with a new one.
+   */
   public putUser(user: ScrumUser): Observable<HttpResponse<any>> {
     const url = `${environment.apiUrl}/users/${user.id}`;
     return this.httpClient.put(url, user, { observe: 'response' });
   }
 
+  /**
+   * Delete a user.
+   */
   public deleteUser(user: ScrumUser): Observable<HttpResponse<any>> {
     const url = `${environment.apiUrl}/users/${user.id}`;
     return this.httpClient.delete(url, { observe: 'response' });
   }
 
   // Projects
+
+  /**
+   * Return all projects.
+   */
   public getProjects(): Observable<HttpResponse<ScrumProject[]>> {
     const url = `${environment.apiUrl}/projects`;
     return this.httpClient.get<ScrumProject[]>(url, { observe: 'response' });
   }
 
+  /**
+   * Return the project with a specific id.
+   */
   public getProject(id: number): Observable<HttpResponse<ScrumProject>> {
     const url = `${environment.apiUrl}/projects/${id}`;
     return this.httpClient.get<ScrumProject>(url, { observe: 'response' });
   }
 
+  /**
+   * Create a new project, if successful, the newly created project will be returned.
+   */
   public postProject(
     project: ScrumProject
   ): Observable<HttpResponse<ScrumProject>> {
@@ -205,23 +314,36 @@ export class BackendService {
     });
   }
 
+  /**
+   * Replace an existing project with a new one.
+   */
   public putProject(project: ScrumProject): Observable<HttpResponse<any>> {
     const url = `${environment.apiUrl}/projects/${project.id}`;
     return this.httpClient.put(url, project, { observe: 'response' });
   }
 
+  /**
+   * Delete a project.
+   */
   public deleteProject(project: ScrumProject): Observable<HttpResponse<any>> {
     const url = `${environment.apiUrl}/projects/${project.id}`;
     return this.httpClient.delete(url, { observe: 'response' });
   }
 }
 
+/**
+ * @summary Represents the priority of a task or userstory.
+ */
 export enum Priority {
   High = 'high',
   Medium = 'medium',
   Low = 'low',
 }
 
+/**
+ * @summary Represents a task in an agile work process.
+ * @description A task is a small piece of work, associated with a larger userstory.
+ */
 export interface ScrumTask {
   id?: number;
   title: string;
@@ -235,6 +357,11 @@ export interface ScrumTask {
   priority?: Priority;
 }
 
+/**
+ * @summary Represents a userstory in an agile work process.
+ * @description A userstory is a piece of work that can be done in one sprint.
+ * It can be further divided into multiple tasks.
+ */
 export interface ScrumUserstory {
   id?: number;
   title: string;
@@ -247,6 +374,12 @@ export interface ScrumUserstory {
   projectid?: number;
 }
 
+/**
+ * @summary Represents an agile sprint.
+ * @description A sprint is typically one to four weeks long.
+ * Userstories are started and completed during one sprint.
+ * </remarks>
+ */
 export interface ScrumSprint{
     id?: number;
     title: string;
@@ -256,6 +389,11 @@ export interface ScrumSprint{
     projectid?: number;
 }
 
+/**
+ * @summary Represents a category of userstories.
+ * @description Every userstory can optionally be associated with a single category.
+ * This can be helpful to organize work in larger teams.
+ */
 export interface ScrumCategory {
   id?: number;
   title: string;
@@ -264,17 +402,32 @@ export interface ScrumCategory {
   project?: number;
 }
 
+/**
+ * @summary Represents the status of a task or userstory.
+ * @description Classic status are "Backlog", "In Progress" and "Done", but
+ * teams can create others to fit their individual workflow.
+ */
 export interface ScrumStatus {
   id?: number;
   title: string;
   description: string;
 }
 
+/**
+ * @summary Represents a team member that can work on userstories.
+ * @description This allows teams to track who is working on a userstory
+ * at a given time.
+ */
 export interface ScrumUser {
   id?: number;
   name: string;
 }
 
+/**
+ * @summary Represents a project that the team works on.
+ * @description Userstories and sprints can be categorized into projects,
+ * to help organization for larger teams.
+ */
 export interface ScrumProject {
   id?: number;
   title: string;