Documenting scenery!

* with this commit, scenery now is fully documented
* documentation gets generated by dokka (github.com/Kotlin/dokka), and is compatible with javadoc.

.editorconfig

@@ -0,0 +1,22 @@
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+# Matches multiple files with brace expansion notation
+# Set default charset
+[*.{js,kt,gradle,java}]
+charset = utf-8
+
+# 4 space indentation
+[*.{kt,gradle,java}]
+indent_style = space
+indent_size = 4
+
+# Matches the exact files either package.json or .travis.yml
+[{package.json,.travis.yml}]
+indent_style = space
+indent_size = 2

build.gradle

@@ -1,11 +1,13 @@
 buildscript {
 	ext.kotlin_version = '1.0.3'
-    ext.slf4j_version = "1.7.20"
+    ext.dokka_version = '0.9.8'
+    ext.slf4j_version = '1.7.20'
 	repositories {
     mavenCentral()
   }
   dependencies {
 	classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    classpath "org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}"
   }
 }
 
@@ -18,6 +20,7 @@ apply plugin: 'eclipse'
 apply plugin: 'maven'
 apply plugin: 'maven-publish'
 apply plugin: 'idea'
+apply plugin: 'org.jetbrains.dokka'
 
 sourceSets
 {
@@ -143,6 +146,31 @@ repositories
     { url "http://nativelibs4java.sourceforge.net/maven" }
 }
 
+dokka {
+    moduleName = 'scenery'
+    outputFormat = 'javadoc'
+    outputDirectory = "$buildDir/javadoc"
+    processConfigurations = ['compile']
+    includes = ['README.md']
+    samples = [
+        'src/test/kotlin/scenery/tests/examples/BloodCellsExample.kt',
+        'src/test/kotlin/scenery/tests/examples/CubeExample.kt',
+        'src/test/kotlin/scenery/tests/examples/TexturedCubeExample.kt',
+        'src/test/kotlin/scenery/tests/examples/LineExample.kt',
+        'src/test/kotlin/scenery/tests/examples/MultiBoxExample.kt',
+        'src/test/kotlin/scenery/tests/examples/MultiBoxInstancedExample.kt',
+        'src/test/kotlin/scenery/tests/examples/VertexUpdateExample.kt',
+        'src/test/kotlin/scenery/tests/examples/OpenVRExample.kt',
+        'src/test/kotlin/scenery/tests/examples/FontRenderingExample.kt'
+    ]
+    linkMapping {
+        dir = "src/main/kotlin"
+        url = "https://github.com/clearvolume/scenery/blob/master/src/main/kotlin"
+        suffix = "#L"
+    }
+    sourceDirs = files('src/main/kotlin')
+}
+
 if (JavaVersion.current().isJava8Compatible()) {
 	allprojects {
 		tasks.withType(Javadoc) {

src/main/kotlin/scenery/Box.kt

@@ -3,9 +3,10 @@ package scenery
 import cleargl.GLVector
 
 /**
- * <Description>
+ * Constructs a Box [Node] with the dimensions given in [sizes]
  *
  * @author Ulrik Günther <hello@ulrik.is>
+ * @property[sizes] The x/y/z sizes of the box
  */
 open class Box(sizes: GLVector) : Node("box"), HasGeometry {
     override var vertices: FloatArray = floatArrayOf()
@@ -18,44 +19,44 @@ open class Box(sizes: GLVector) : Node("box"), HasGeometry {
     override val geometryType = GeometryType.TRIANGLES;
 
     init {
-         this.scale = sizes
-         val side = 2.0f
-         val side2 = side / 2.0f
+        this.scale = sizes
+        val side = 2.0f
+        val side2 = side / 2.0f
 
-         vertices = floatArrayOf(
+        vertices = floatArrayOf(
             // Front
             -side2, -side2, side2,
             side2, -side2, side2,
-            side2,  side2, side2,
-            -side2,  side2, side2,
+            side2, side2, side2,
+            -side2, side2, side2,
             // Right
             side2, -side2, side2,
             side2, -side2, -side2,
-            side2,  side2, -side2,
-            side2,  side2, side2,
+            side2, side2, -side2,
+            side2, side2, side2,
             // Back
             -side2, -side2, -side2,
-            -side2,  side2, -side2,
-            side2,  side2, -side2,
+            -side2, side2, -side2,
+            side2, side2, -side2,
             side2, -side2, -side2,
             // Left
             -side2, -side2, side2,
-            -side2,  side2, side2,
-            -side2,  side2, -side2,
+            -side2, side2, side2,
+            -side2, side2, -side2,
             -side2, -side2, -side2,
             // Bottom
             -side2, -side2, side2,
             -side2, -side2, -side2,
             side2, -side2, -side2,
             side2, -side2, side2,
             // Top
-            -side2,  side2, side2,
-            side2,  side2, side2,
-            side2,  side2, -side2,
-            -side2,  side2, -side2
-         )
+            -side2, side2, side2,
+            side2, side2, side2,
+            side2, side2, -side2,
+            -side2, side2, -side2
+        )
 
-       normals = floatArrayOf(
+        normals = floatArrayOf(
             // Front
             0.0f, 0.0f, 1.0f,
             0.0f, 0.0f, 1.0f,
@@ -86,15 +87,15 @@ open class Box(sizes: GLVector) : Node("box"), HasGeometry {
             0.0f, 1.0f, 0.0f,
             0.0f, 1.0f, 0.0f,
             0.0f, 1.0f, 0.0f
-       )
+        )
 
         indices = intArrayOf(
-            0,1,2,0,2,3,
-            4,5,6,4,6,7,
-            8,9,10,8,10,11,
-            12,13,14,12,14,15,
-            16,17,18,16,18,19,
-            20,21,22,20,22,23
+            0, 1, 2, 0, 2, 3,
+            4, 5, 6, 4, 6, 7,
+            8, 9, 10, 8, 10, 11,
+            12, 13, 14, 12, 14, 15,
+            16, 17, 18, 16, 18, 19,
+            20, 21, 22, 20, 22, 23
         )
 
         texcoords = floatArrayOf(

src/main/kotlin/scenery/Camera.kt

@@ -1,28 +1,43 @@
-@file:JvmName("Camera")
 package scenery
 
 import cleargl.GLMatrix
 import cleargl.GLVector
 import com.jogamp.opengl.math.Quaternion
 
+/**
+ * Camera class that may be targeted or oriented
+ *
+ * @author Ulrik Günther <hello@ulrik.is>
+ * @constructor Creates a new camera with default position and right-handed
+ *  coordinate system.
+ */
 open class Camera : Node("Camera") {
 
+    /** Is the camera targeted? */
     var targeted = false
+    /** Is this camera active? Setting one camera active will deactivate the others */
     var active = false
 
+    /** Target, used if [targeted] is true */
     var target: GLVector = GLVector(0.0f, 0.0f, 0.0f)
+    /** Forward vector of the camera, used if not targeted */
     var forward: GLVector = GLVector(0.0f, 0.0f, 1.0f)
+    /** Up vector of the camera, used if not targeted */
     var up: GLVector = GLVector(0.0f, 1.0f, 0.0f)
 
+    /** View matrix of the camera. Setting the view matrix will re-set the forward
+     *  vector of the camera according to the given matrix.
+     */
     override var view: GLMatrix? = null
         set(m) {
             m?.let {
-                this.forward = GLVector(m.get(0, 2), m.get(1,2), m.get(2,2)) * -1.0f
+                this.forward = GLVector(m.get(0, 2), m.get(1, 2), m.get(2, 2)) * -1.0f
             }
 
             field = m
         }
 
+    /** Rotation of the camera. The rotation is applied after the view matrix */
     override var rotation: Quaternion = Quaternion(0.0f, 0.0f, 0.0f, 1.0f)
         set(q) {
             field = q
@@ -32,11 +47,17 @@ open class Camera : Node("Camera") {
         this.nodeType = "Camera"
     }
 
+    /**
+     * Returns the world orientation of the camera
+     *
+     * FIXME: Currently broken/unused
+     *
+     * @return Orientation of the camera in world space
+     */
     fun getWorldOrientation(): GLVector {
-        if(targeted) {
+        if (targeted) {
             return (target - position).normalized
-        }
-        else {
+        } else {
             val v: GLVector = GLVector(forward.x(), forward.y(), forward.z(), 0.0f)
             //FIXME: val o: GLVector= GLMatrix.fromQuaternion(rotation).mult(v)
             return v

src/main/kotlin/scenery/DetachedHeadCamera.kt

@@ -1,10 +1,16 @@
-@file:JvmName("DetachedHeadCamera")
 package scenery
 
 import com.jogamp.opengl.math.Quaternion
 
+/**
+ * Detached Head Camera is a Camera subclass that tracks the head orientation
+ * in addition to general orientation - useful for HMDs
+ *
+ * @author Ulrik Günther <hello@ulrik.is>
+ */
 class DetachedHeadCamera : Camera() {
 
+    /** Orientation of the user's head */
     var headOrientation: Quaternion = Quaternion(0.0f, 0.0f, 0.0f, 1.0f);
 
     init {

src/main/kotlin/scenery/FontBoard.kt

@@ -5,44 +5,54 @@ import scenery.rendermodules.opengl.OpenGLShaderPreference
 import java.util.*
 
 /**
- * <Description>
+ * FontBoard is a possibly billboarded display of a string of text,
+ * rendered using signed-distance fields.
  *
  * @author Ulrik Günther <hello@ulrik.is>
+ * @property[font]  Name of the font to use for this font board
+ * @property[isBillboard] Whether the board should be billboarded or not
+ *
+ * @constructor Returns a FontBoard instance, with [fontFamily] and a declared [OpenGLShaderPreference]
  */
 class FontBoard(font: String = "Source Code Pro", override var isBillboard: Boolean = true) : Mesh() {
+
+    /** The text displayed on this font board */
     var text: String = ""
         set(value) {
             dirty = true
             field = value
         }
 
+    /** The font family of this font board. If reset, this will set the [dirty] flag,
+     * such that the renderer can recreate the signed-distance fields used for displaying.
+     */
     var fontFamily: String = "Source Code Pro"
         set(value) {
             dirty = true
             field = value
         }
 
-    @ShaderProperty
-    var fontColor: GLVector = GLVector(0.5f, 0.5f, 0.5f)
-
-    @ShaderProperty
-    var backgroundColor: GLVector = GLVector(1.0f, 1.0f, 1.0f)
-
-    @ShaderProperty
-    var transparent: Int = 1
+    /** The [ShaderProperty] storing the font's color. */
+    @ShaderProperty var fontColor: GLVector = GLVector(0.5f, 0.5f, 0.5f)
+    /** The [ShaderProperty] storing the background color of the font board,
+     * used only if [transparent] is 0. */
+    @ShaderProperty var backgroundColor: GLVector = GLVector(1.0f, 1.0f, 1.0f)
+    /** The [ShaderProperty] storing whether the font board should be renderer transparently. */
+    @ShaderProperty var transparent: Int = 1
 
     init {
         name = "FontBoard"
         fontFamily = font
         metadata.put(
-                "ShaderPreference",
-                OpenGLShaderPreference(
-                        arrayListOf("DefaultDeferred.vert", "FontBoard.frag"),
-                        HashMap<String, String>(),
-                        arrayListOf("DeferredShadingRenderer")))
+            "ShaderPreference",
+            OpenGLShaderPreference(
+                arrayListOf("DefaultDeferred.vert", "FontBoard.frag"),
+                HashMap<String, String>(),
+                arrayListOf("DeferredShadingRenderer")))
     }
 
+    /** Stringify the font board. Returns [fontFamily] used as well as the [text]. */
     override fun toString(): String {
         return "FontBoard ($fontFamily): $text"
     }
-}
+}

src/main/kotlin/scenery/GenericTexture.kt

@@ -5,16 +5,23 @@ import coremem.types.NativeTypeEnum
 import java.nio.ByteBuffer
 
 /**
- * <Description>
+ * Data class for storing renderer-agnostic textures
  *
  * @author Ulrik Günther <hello@ulrik.is>
  */
 data class GenericTexture(
-        var name: String,
-        var dimensions: GLVector,
-        var channels: Int = 4,
-        var type: NativeTypeEnum = NativeTypeEnum.Byte,
-        var contents: ByteBuffer,
-        var repeatS: Boolean = true,
-        var repeatT: Boolean = true
-        )
+    /** Name of the texture, might e.g. be "diffuse" */
+    var name: String,
+    /** Dimensions of the texture in pixels */
+    var dimensions: GLVector,
+    /** The texture's number of channels */
+    var channels: Int = 4,
+    /** [NativeTypeEnum] declaring the data type stored in [contents] */
+    var type: NativeTypeEnum = NativeTypeEnum.Byte,
+    /** Byte contents of the texture */
+    var contents: ByteBuffer,
+    /** Shall the texture be repeated on the U/S coordinate? */
+    var repeatS: Boolean = true,
+    /** Shall the texture be repeated on the V/T coordinate? */
+    var repeatT: Boolean = true
+)