begin docs improvement

Author: fractalwrench

core/src/main/kotlin/com/fractalwrench/json2kotlin/ClassTypeHolder.kt

@@ -3,7 +3,7 @@ package com.fractalwrench.json2kotlin
 import com.squareup.kotlinpoet.*
 import java.util.*
 
-
+// TODO docs
 internal class ClassTypeHolder(val delegate: SourceBuildDelegate, groupingStrategy: GroupingStrategy) { // TODO rename, bad ontology
 
     internal val stack = Stack<TypeSpec>()
@@ -41,7 +41,7 @@ internal class ClassTypeHolder(val delegate: SourceBuildDelegate, groupingStrate
     private fun processTreeLevel(levelQueue: LinkedList<TypedJsonElement>) {
         val fieldValues = levelQueue.filter { it.isJsonObject }.toMutableList()
 
-        jsonFieldGrouper.groupCommonFieldValues(fieldValues)
+        jsonFieldGrouper.groupJsonObjects(fieldValues)
                 .flatMap { convertFieldsToTypes(it) }
                 .sortedByDescending { it.name }
                 .forEach { stack += it }

core/src/main/kotlin/com/fractalwrench/json2kotlin/ConversionArgs.kt

@@ -1,3 +1,8 @@
 package com.fractalwrench.json2kotlin
 
+/**
+ * Holds arguments which are used to control the source code generation.
+ *
+ * For example, specifying a non-empty package name will set a package name in the generated source file.
+ */
 data class ConversionArgs(val rootClassName: String = "Example", val packageName: String? = null)

core/src/main/kotlin/com/fractalwrench/json2kotlin/GsonBuildDelegate.kt

@@ -4,7 +4,7 @@ import com.google.gson.annotations.SerializedName
 import com.squareup.kotlinpoet.AnnotationSpec
 import com.squareup.kotlinpoet.PropertySpec
 import com.squareup.kotlinpoet.TypeSpec
-
+// TODO docs
 class GsonBuildDelegate: SourceBuildDelegate {
 
     private val regex = "%".toRegex()

core/src/main/kotlin/com/fractalwrench/json2kotlin/JsonFieldGrouper.kt

@@ -1,21 +1,30 @@
 package com.fractalwrench.json2kotlin
 
-internal class JsonFieldGrouper(val groupingStrategy: GroupingStrategy) {
+/**
+ * Determines whether multiple JsonObjects share any commonality (i.e. whether they should be
+ * represented by the same type).
+ *
+ * The strategy used to determine commonality can be supplied as a constructor parameter.
+ */
+internal class JsonFieldGrouper(private val groupingStrategy: GroupingStrategy = ::defaultGroupingStrategy) {
 
-    fun groupCommonFieldValues(allObjects: MutableList<TypedJsonElement>): List<List<TypedJsonElement>> {
+    /**
+     * Recursively groups a List of JSONElementstogether by any commonality (i.e. whether they should be
+     * represented by the same type)
+     */
+    fun groupJsonObjects(jsonElements: MutableList<TypedJsonElement>): List<List<TypedJsonElement>> {
         val allTypes: MutableList<MutableList<TypedJsonElement>> = mutableListOf()
 
-        while (allObjects.isNotEmpty()) {
+        while (jsonElements.isNotEmpty()) {
             val typeList = mutableListOf<TypedJsonElement>()
             allTypes.add(typeList)
-            findCommonTypesForElement(allObjects.first(), allObjects, typeList)
+            findCommonTypesForElement(jsonElements.first(), jsonElements, typeList)
         }
         return allTypes
     }
 
     /**
-     * Recursively finds any commonality between types in a collection of JSON objects. Commonality between
-     * two objects is defined as them sharing one or more key value.
+     * Recursively finds any commonality between types in a collection of JSON objects.
      *
      * Recursion is necessary to detect transitive relationships. For example, an object that only contains a
      * key of "foo" may be the same type as an object that only contains a key of "bar", if another object exists

core/src/main/kotlin/com/fractalwrench/json2kotlin/JsonNames.kt

@@ -1,6 +1,6 @@
 package com.fractalwrench.json2kotlin
 
-
+// TODO docs
 internal fun nameForArrayField(index: Int, identifier: String): String =
         if (index == 0) identifier else "$identifier${index + 1}"
 

core/src/main/kotlin/com/fractalwrench/json2kotlin/JsonProcessor.kt

@@ -4,7 +4,7 @@ import com.google.gson.JsonElement
 import com.squareup.kotlinpoet.*
 import java.util.HashMap
 
-
+// TODO docs
 internal class JsonProcessor(private val typeDetector: JsonTypeDetector) { // TODO crappy name
 
     internal val jsonElementMap = HashMap<JsonElement, TypeSpec>() // FIXME feels wrong having this exposed, return instead?
@@ -24,7 +24,7 @@ internal class JsonProcessor(private val typeDetector: JsonTypeDetector) { // TO
     private fun findDistinctTypesForField(commonElements: List<TypedJsonElement>, key: String): List<TypeName?> {
         return commonElements.map {
             val fieldValue = it.asJsonObject.get(key)
-            if (fieldValue != null) typeDetector.typeForJsonField(fieldValue, key, jsonElementMap) else null
+            if (fieldValue != null) typeDetector.typeForJsonElement(fieldValue, key, jsonElementMap) else null
         }.distinct()
     }
 

core/src/main/kotlin/com/fractalwrench/json2kotlin/JsonReader.kt

@@ -16,6 +16,8 @@ class JsonReader(private val jsonParser: JsonParser) {
 
     /**
      * Reads a JSON string using GSON.
+     *
+     * If the root value is an array, a wrapper element will be added to the tree.
      */
     internal fun readJsonTree(input: InputStream, args: ConversionArgs): JsonObject {
 
@@ -34,7 +36,10 @@ class JsonReader(private val jsonParser: JsonParser) {
      * Adds an object as root which wraps the array
      */
     private fun addRootWrapper(jsonArray: JsonArray, className: String): JsonObject {
-        return JsonObject().apply { add(nameForArrayField(0, "${className}Array").decapitalize(), jsonArray) }
+        return JsonObject().apply {
+            val identifier = nameForArrayField(0, "${className}Array").decapitalize()
+            add(identifier, jsonArray)
+        }
     }
 
 }

core/src/main/kotlin/com/fractalwrench/json2kotlin/JsonTypeDetector.kt

@@ -7,11 +7,24 @@ import com.google.gson.JsonPrimitive
 import com.squareup.kotlinpoet.*
 import java.util.HashSet
 
+/**
+ * Deduces the TypeName for a JSON field value. For a primitive such as a String, this is a simple operation.
+ * For complex values such as Arrays, Objects, and Nulls, this requires various considerations,
+ * some of which are enumerated below:
+ *
+ * - Whether the type already exists
+ * - Nullability of other elements
+ * - Generic Parameters
+ * - Object nesting
+ */
 internal class JsonTypeDetector {
-    
-    internal fun typeForJsonField(jsonElement: JsonElement,
-                                  key: String,
-                                  jsonElementMap: Map<JsonElement, TypeSpec>): TypeName {
+
+    /**
+     * Determines an returns the TypeName for a JSONElement
+     */
+    internal fun typeForJsonElement(jsonElement: JsonElement,
+                                    key: String,
+                                    jsonElementMap: Map<JsonElement, TypeSpec>): TypeName {
         with(jsonElement) {
             return when {
                 isJsonPrimitive -> typeForJsonPrimitive(asJsonPrimitive)

core/src/main/kotlin/com/fractalwrench/json2kotlin/Kotlin2JsonConverter.kt

@@ -7,16 +7,14 @@ import java.io.OutputStream
 /**
  * Converts JSON to Kotlin
  */
-class Kotlin2JsonConverter(val buildDelegate: SourceBuildDelegate = GsonBuildDelegate()) {
-
-    // TODO (general: update KDocs!)
+class Kotlin2JsonConverter(private val buildDelegate: SourceBuildDelegate = GsonBuildDelegate()) {
 
     private val jsonReader = JsonReader(JsonParser())
     private val sourceFileWriter = SourceFileWriter()
     private val traverser = ReverseJsonTreeTraverser()
 
     /**
-     * Converts a JSON string to Kotlin, writing it to the OutputStream.
+     * Converts an InputStream of JSON to Kotlin source code, writing the result to the OutputStream.
      */
     fun convert(input: InputStream, output: OutputStream, args: ConversionArgs) {
         try {

core/src/main/kotlin/com/fractalwrench/json2kotlin/ReverseJsonTreeTraverser.kt

@@ -7,13 +7,17 @@ import java.util.*
 
 
 /**
- * Traverses a JSON tree from the bottom up in level order.
+ * Traverses a JSON tree in level order (BFS starting from the top) and adds each element to a
+ * Stack, with additional metadata.
  */
 internal class ReverseJsonTreeTraverser {
 
-    fun traverse(element: JsonElement, rootName: String): Stack<TypedJsonElement> {
+    /**
+     * Traverses a JSON tree in level order (BFS starting from the top)
+     */
+    fun traverse(element: JsonElement, rootElementName: String): Stack<TypedJsonElement> {
         val bfsStack: Stack<TypedJsonElement> = Stack()
-        buildStack(bfsStack, element, rootName)
+        buildStack(bfsStack, element, rootElementName)
         return bfsStack
     }