From 9a89f8f3389ec5a3de61e1b8b6d3f20fb3e9e28a Mon Sep 17 00:00:00 2001
From: Jakob Fahr <me@jfhr.de>
Date: Tue, 14 Jul 2020 12:57:19 +0200
Subject: [PATCH] Add dashboard comments

---
 .../dashboard/dashboard.component.html        |  9 ++--
 .../dashboard/dashboard.component.ts          | 47 +++++++++++++++----
 2 files changed, 45 insertions(+), 11 deletions(-)

diff --git a/src/app/components/dashboard/dashboard.component.html b/src/app/components/dashboard/dashboard.component.html
index 66fd4e4..318689f 100644
--- a/src/app/components/dashboard/dashboard.component.html
+++ b/src/app/components/dashboard/dashboard.component.html
@@ -7,6 +7,7 @@
 
       <div class="row px-3 py-2">
 
+        <!-- Show a message if no sprints exist yet, with a link to the page where a new one can be created -->
         <ng-container *ngIf="selectedSprint === undefined">
           <h3 class="mr-3 text-primary">Alle Userstories</h3>
           <a [routerLink]="['sprints']">Lege einen Sprint an, um Userstories zu organisieren.</a>
@@ -36,6 +37,7 @@
             </select>
           </label>
 
+          <!-- If the active sprint is selected: Show the number of remaining days + urgency -->
           <span class="mr-5"></span>
           <h3
             *ngIf="selectedSprint === currentSprint"
@@ -53,12 +55,13 @@
 
       <div class="row">
 
+        <!-- Info on the userstories in the selected sprint -->
         <div class="p-3 col-12 col-xl-6 col-lg-6 col-md-12 col-sm-12">
           <div class="card">
             <div class="card-header">
-          <span class="text-large">
-            Userstories
-          </span>
+              <span class="text-large">
+                Userstories
+              </span>
             </div>
             <div class="card-body">
               <div *ngIf="selectedSprint !== undefined && usedStatus.length === 0">
diff --git a/src/app/components/dashboard/dashboard.component.ts b/src/app/components/dashboard/dashboard.component.ts
index b47f895..3cf0a70 100644
--- a/src/app/components/dashboard/dashboard.component.ts
+++ b/src/app/components/dashboard/dashboard.component.ts
@@ -1,7 +1,7 @@
-import {Component, OnChanges} from '@angular/core';
-import {forkJoin} from 'rxjs';
+import { Component } from '@angular/core';
+import { forkJoin } from 'rxjs';
 import Chart from 'chart.js';
-import {BackendService, ScrumSprint, ScrumStatus, ScrumUserstory} from '../../services/backend.service';
+import { BackendService, ScrumSprint, ScrumStatus, ScrumUserstory } from '../../services/backend.service';
 
 @Component({
   selector: 'app-dashboard',
@@ -16,6 +16,9 @@ export class DashboardComponent {
     return this.status.filter(s => this.selectedSprintUserstories.find(us => us.statusid === s.id) !== undefined);
   }
 
+  /**
+   * Returns all userstories in the selected sprint.
+   */
   public get selectedSprintUserstories(): ScrumUserstory[] {
     if (this.selectedSprint === undefined) {
       return this.userstories;
@@ -23,12 +26,20 @@ export class DashboardComponent {
     return this.userstories.filter(us => us.sprintid === this.selectedSprint.id);
   }
 
+  /**
+   * Returns the currently active sprint.
+   * If multiple sprints are active at the current time, any one of them may be returned.
+   */
   public get currentSprint(): ScrumSprint {
     const now = Date.now();
     return this.sprints.find(s => Date.parse(s.startDate) < now && Date.parse(s.endDate) > now);
   }
 
   private _selectedSprint: ScrumSprint;
+
+  /**
+   * Returns the sprint selected by the user.
+   */
   public get selectedSprint(): ScrumSprint {
     if (this._selectedSprint === undefined) {
       if (this.currentSprint === undefined) {
@@ -39,15 +50,26 @@ export class DashboardComponent {
     return this._selectedSprint;
   }
 
+  /**
+   * Sets the sprint selected by the user.
+   */
   public set selectedSprint(value) {
     this._selectedSprint = value;
     this.createChart();
   }
 
+  /** All status. */
   public status: ScrumStatus[] = [];
+
+  /** All userstories. */
   public userstories: ScrumUserstory[] = [];
+
+  /** All sprints. */
   public sprints: ScrumSprint[] = [];
 
+  /**
+   * The pie chart showing the userstories in the selected sprint.
+   */
   public chart: Chart;
 
   constructor(private backendService: BackendService) {
@@ -69,9 +91,11 @@ export class DashboardComponent {
 
   /**
    * Returns the date in the following format: 1.7.2020
+   * @param dateValue an integer representing the number of milliseconds since the
+   * ECMAScript epoch -or- a string in a format recognized by the Date.parse() method.
    */
-  public toDateString(isoFormatString) {
-    const date = new Date(isoFormatString);
+  public toDateString(dateValue) {
+    const date = new Date(dateValue);
     return `${date.getDate()}.${date.getMonth() + 1}.${date.getFullYear()}`;
   }
 
@@ -81,9 +105,7 @@ export class DashboardComponent {
 
     if (this.usedStatus.length === 0) {
       this.chart.destroy();
-    }
-
-    else {
+    } else {
       this.chart = new Chart(context, {
         type: 'pie',
         data: {
@@ -108,6 +130,9 @@ export class DashboardComponent {
     }
   }
 
+  /**
+   * Returns a sufficiently large array of background colors to be used in the chart.
+   */
   private getBackgroundColors(): string[] {
     const baseColors = [
       'rgb(255, 153, 102)',
@@ -132,10 +157,16 @@ export class DashboardComponent {
     return colors;
   }
 
+  /**
+   * Returns the number of userstories in the selected sprint that have the given status.
+   */
   public getNumberOfUserstoriesByStatus(status: ScrumStatus): number {
     return this.selectedSprintUserstories.filter(us => us.statusid === status.id).length;
   }
 
+  /**
+   * Returns the days remaining until the end date of the selected sprint.
+   */
   public getRemainingDaysInSprint(): number {
     if (this.selectedSprint === undefined) {
       return undefined;