From b18890851c03ba79b095c72f8313c83184e91d28 Mon Sep 17 00:00:00 2001
From: Danila Fedorin <danila.fedorin@gmail.com>
Date: Wed, 13 May 2020 13:36:32 -0700
Subject: [PATCH] Start working on documentation.

---
 app/build.gradle                                 | 16 ++++++++++++++++
 .../fencelessgrazing/model/CollarDetails.kt      |  7 +++++++
 .../fencelessgrazing/model/CollarDistance.kt     |  7 +++++++
 .../danilafe/fencelessgrazing/model/CollarPos.kt |  9 +++++++++
 .../fencelessgrazing/model/CollarSummary.kt      |  8 +++++++-
 .../fencelessgrazing/model/LoginResult.kt        |  5 +++++
 .../danilafe/fencelessgrazing/model/Polygon.kt   |  5 +++++
 7 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 app/src/main/java/com/danilafe/fencelessgrazing/model/CollarPos.kt

diff --git a/app/build.gradle b/app/build.gradle
index 9e314c0..f65775e 100644
--- a/app/build.gradle
+++ b/app/build.gradle
@@ -4,6 +4,17 @@ apply plugin: 'kotlin-android'
 
 apply plugin: 'kotlin-android-extensions'
 
+buildscript {
+    repositories {
+        jcenter()
+    }
+    dependencies {
+        classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.10.1"
+    }
+}
+
+apply plugin: 'org.jetbrains.dokka'
+
 android {
     compileSdkVersion 29
     buildToolsVersion "29.0.2"
@@ -23,6 +34,11 @@ android {
     }
 }
 
+dokka {
+    outputFormat = 'html'
+    outputDirectory = "$buildDir/dokka"
+}
+
 repositories {
     mavenCentral()
     google()
diff --git a/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarDetails.kt b/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarDetails.kt
index 384482b..ae6d6d5 100644
--- a/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarDetails.kt
+++ b/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarDetails.kt
@@ -1,3 +1,10 @@
 package com.danilafe.fencelessgrazing.model
 
+/**
+ * Information returned from the `/collar/<id>/details` API endpoint.
+ *
+ * @param id the collar's internal unique identifier.
+ * @param name the collar's current designation in the system.
+ * @param stimulus the number of stimulus activation reports in the last 24 hours.
+ */
 data class CollarDetails(val id: Int, val name: String, val stimulus: Int)
\ No newline at end of file
diff --git a/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarDistance.kt b/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarDistance.kt
index 8b034a1..832e10f 100644
--- a/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarDistance.kt
+++ b/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarDistance.kt
@@ -1,3 +1,10 @@
 package com.danilafe.fencelessgrazing.model
 
+/**
+ * Component of the information returned from the `/collars/stats/distance` AP endpoint.
+ *
+ * @param name the current designation of the collar to which this data point belongs.
+ * @param id the unique identifier of the collar in the system.
+ * @param distance the distance, in kilometers, traveled by this collar.
+ */
 data class CollarDistance(val name: String, val id: Int, val distance: Float)
\ No newline at end of file
diff --git a/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarPos.kt b/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarPos.kt
new file mode 100644
index 0000000..736c594
--- /dev/null
+++ b/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarPos.kt
@@ -0,0 +1,9 @@
+package com.danilafe.fencelessgrazing.model
+
+/**
+ * GPS coordinate returned by many of the project's API endpoints.
+ *
+ * @param longitude the longitude of the GPS point.
+ * @param latitude the latitude of the GPS point.
+ */
+data class CollarPos(val longitude: String, val latitude: String)
diff --git a/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarSummary.kt b/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarSummary.kt
index c885320..2ecf5f3 100644
--- a/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarSummary.kt
+++ b/app/src/main/java/com/danilafe/fencelessgrazing/model/CollarSummary.kt
@@ -1,4 +1,10 @@
 package com.danilafe.fencelessgrazing.model
 
-data class CollarPos(val longitude: String, val latitude: String)
+/**
+ * Minimal information about one of the collars returned by the `/collars` API endpoints.
+ *
+ * @param id the internal identifier of the collar in the system.
+ * @param name the collar's current designation.
+ * @param pos the collar's most recent location.
+ */
 data class CollarSummary(val id: Int, val name: String, val pos: CollarPos)
diff --git a/app/src/main/java/com/danilafe/fencelessgrazing/model/LoginResult.kt b/app/src/main/java/com/danilafe/fencelessgrazing/model/LoginResult.kt
index b76ad2e..145b9a8 100644
--- a/app/src/main/java/com/danilafe/fencelessgrazing/model/LoginResult.kt
+++ b/app/src/main/java/com/danilafe/fencelessgrazing/model/LoginResult.kt
@@ -1,3 +1,8 @@
 package com.danilafe.fencelessgrazing.model
 
+/**
+ * The result of a successful authentication via the `/login` endpoint.
+ *
+ * @param token the JWT authorization token to be used for future API requests.
+ */
 data class LoginResult(val token: String)
\ No newline at end of file
diff --git a/app/src/main/java/com/danilafe/fencelessgrazing/model/Polygon.kt b/app/src/main/java/com/danilafe/fencelessgrazing/model/Polygon.kt
index 1b1b576..6160fb4 100644
--- a/app/src/main/java/com/danilafe/fencelessgrazing/model/Polygon.kt
+++ b/app/src/main/java/com/danilafe/fencelessgrazing/model/Polygon.kt
@@ -1,3 +1,8 @@
 package com.danilafe.fencelessgrazing.model
 
+/**
+ * A general polygon returned by many of the system's API endpoints.
+ *
+ * @param dataPoints the vertices of the polygon, in order.
+ */
 data class Polygon(val dataPoints : List<CollarPos>)
\ No newline at end of file