From be031b0b32b0d839269c95b9de62b1598c286ab9 Mon Sep 17 00:00:00 2001
From: Nathan Cannon <nathan.cannon@edf-energy.com>
Date: Tue, 9 Oct 2018 16:22:11 +0100
Subject: [PATCH] Added comments.

---
 .../neviyn/observationdatabase/Controller.kt  | 37 +++++++++++++++++--
 .../co/neviyn/observationdatabase/Entity.kt   | 12 ++++++
 2 files changed, 45 insertions(+), 4 deletions(-)

diff --git a/backend/src/main/kotlin/uk/co/neviyn/observationdatabase/Controller.kt b/backend/src/main/kotlin/uk/co/neviyn/observationdatabase/Controller.kt
index aea1cf3..e3c563a 100644
--- a/backend/src/main/kotlin/uk/co/neviyn/observationdatabase/Controller.kt
+++ b/backend/src/main/kotlin/uk/co/neviyn/observationdatabase/Controller.kt
@@ -16,16 +16,25 @@ class Controller {
     @Autowired
     lateinit var observationRepository: ObservationRepository
 
+    /**
+     * Returns a list of all current sites.
+     */
     @GetMapping("/site")
     fun getAllSites(): List<NameValue> = siteRepository.findAll().map { NameValue(it.name, it.id) }
 
-
+    /**
+     * Add a new Site to the database based on the data provided in [newSite].
+     */
     @PostMapping("/site")
     fun addSite(@Valid @RequestBody newSite: NewSite): NameValue {
         val site = siteRepository.save(Site(name = newSite.name))
         return NameValue(site.name, site.id)
     }
 
+    /**
+     * Get all the tutors assigned to the site with the given [id].
+     * Returned in a form compatible with a HTML Select element.
+     */
     @GetMapping("/site/{id}/tutors")
     fun getTutorsForSite(@PathVariable(value = "id") id: Long): List<NameValue>? {
         val site = siteRepository.findById(id)
@@ -34,9 +43,16 @@ class Controller {
         return null
     }
 
+    /**
+     * Get all known tutors.
+     * Returned in a form compatible with a HTML Select element.
+     */
     @GetMapping("/tutor")
     fun getAllTutors(): List<NameValue> = tutorRepository.findAll().map { NameValue(it.name, it.id) }
 
+    /**
+     * Add a new Tutor to the database based on the data provided in [newTutor].
+     */
     @PostMapping("/tutor")
     fun addTutor(@Valid @RequestBody newTutor: NewTutor): NameValue? {
         var nameValue: NameValue? = null
@@ -49,18 +65,24 @@ class Controller {
         return nameValue
     }
 
+    /**
+     * Get all observations overseen by the tutor with [id].
+     */
     @GetMapping("/tutor/{id}/observations")
     fun getObservationsForTutor(@PathVariable(value = "id") id: Long): List<SimpleObservation> =
             tutorRepository.findById(id).map { tutor ->
                 tutor.observations.map { SimpleObservation(it) }
             }.orElse(listOf())
 
+    /**
+     * Add a new observation to the database using data provided in [newObservation].
+     */
     @PostMapping("/observation")
     fun addObservation(@Valid @RequestBody newObservation: NewObservation): Long? {
         val site = siteRepository.findById(newObservation.site)
         val tutors = tutorRepository.findAllById(newObservation.tutors).toSet()
-        if(!site.isPresent) return null
-        if(tutors.isEmpty() || tutors.size != newObservation.tutors.size) return null
+        if (!site.isPresent) return null
+        if (tutors.isEmpty() || tutors.size != newObservation.tutors.size) return null
         val overallScores = newObservation.entries.asSequence().groupBy { it.type }
                 .map { entry -> entry.key to entry.value.asSequence().mapNotNull { it.rating }.average() }
                 .map { it.first to if (it.second > 0) it.second else null }.toList()
@@ -87,6 +109,9 @@ class Controller {
         return observation.id
     }
 
+    /**
+     * Get all observations that are within the constraints provided in [observationsRequest].
+     */
     @PostMapping("/observations")
     fun getObservations(@Valid @RequestBody observationsRequest: ObservationsRequest): List<Observation> {
         if (observationsRequest.tutor != null) {
@@ -118,10 +143,14 @@ class Controller {
         return listOf()
     }
 
+    /**
+     * Get all observations that are within the constraints provided in [observationsRequest]
+     * in a format compatible with ChartJS.
+     */
     @PostMapping("/observations/chartdata")
     fun getObservationsChartData(@Valid @RequestBody observationsRequest: ObservationsRequest): ChartData? {
         val data = getObservations(observationsRequest)
-        if(data.isEmpty()) return ChartData(listOf(), listOf())
+        if (data.isEmpty()) return ChartData(listOf(), listOf())
         val groupedData = data.asSequence().groupBy { it.date }.map { entry ->
             AverageData(
                     entry.value.asSequence().mapNotNull { it.monitoring }.average(),
diff --git a/backend/src/main/kotlin/uk/co/neviyn/observationdatabase/Entity.kt b/backend/src/main/kotlin/uk/co/neviyn/observationdatabase/Entity.kt
index ad100eb..2ee48e4 100644
--- a/backend/src/main/kotlin/uk/co/neviyn/observationdatabase/Entity.kt
+++ b/backend/src/main/kotlin/uk/co/neviyn/observationdatabase/Entity.kt
@@ -5,6 +5,9 @@ import com.fasterxml.jackson.annotation.JsonProperty
 import org.joda.time.LocalDate
 import javax.persistence.*
 
+/**
+ * Defines a location at which observations occur.
+ */
 @Entity
 data class Site(
         @Id
@@ -15,6 +18,9 @@ data class Site(
     val tutors: MutableSet<Tutor> = mutableSetOf()
 }
 
+/**
+ * Defines a tutor who can oversee observations.
+ */
 @Entity
 data class Tutor(
         @Id
@@ -39,6 +45,9 @@ enum class RatingCategory {
     MONITORING, CONTROL, CONSERVATISM, TEAMWORK, KNOWLEDGE
 }
 
+/**
+ * Data record for a training observation.
+ */
 @Entity
 @Table(indexes = [Index(name = "dateIndex", columnList = "date")])
 data class Observation(
@@ -68,6 +77,9 @@ data class Observation(
         val tutors: Set<Tutor>
 )
 
+/**
+ * Entry giving specific details on observation performance for a tutor defined constraint.
+ */
 @Embeddable
 data class Entry(
         @Column(nullable = false)