Add a lot of documentation so Dokka no longer complains about the KDoc

docs/I18n.md

@@ -23,7 +23,7 @@ Put the files in the directory `src/$sourceSetName/mo`, then build normally and
 
 ### Using translated *.lang files
 
-Put the files in the directory `src/$sourceSetName/lang/data`, then build normally and the files should be picked up.
+Put the files in the directory `src/$sourceSetName/lang`, then build normally and the files should be picked up.
 
 ## Change the path from where translated files are picked up
 

src/main/kotlin/config/I18nConfig.kt

@@ -57,8 +57,7 @@ class I18nConfig(private val project: Project) {
   var pathTransformer: (String) -> String = {a -> a};
 
   /**
-   * Alternative to [setPathTransformer()], can set the [pathTransformer]
-   * field using a Groovy [Closure].
+   * Alternative to the setter of property [pathTransformer] using a Groovy [Closure].
    */
   fun pathTransformer(closure: Closure<String>) {
     pathTransformer = { closure.call(it) }

src/main/kotlin/config/JosmPluginExtension.kt

@@ -151,7 +151,7 @@ open class JosmPluginExtension(private val project: Project) {
   val i18n: I18nConfig = I18nConfig(project)
 
   /**
-   * Set the field [i18n] using a Groovy [Closure]
+   * Set the field [JosmPluginExtension.i18n] using a Groovy [Closure]
    */
   public fun i18n(c: Closure<I18nConfig>) {
     project.configure(i18n, c)

src/main/kotlin/i18n/DefaultI18nSourceSet.kt

@@ -8,6 +8,9 @@ import org.gradle.api.internal.tasks.DefaultSourceSet
 import org.gradle.api.tasks.SourceSet
 import org.gradle.util.ConfigureUtil
 
+/**
+ * Implementation for a combination of one [SourceDirectorySet]s for each of the three supported translation formats.
+ */
 class DefaultI18nSourceSet(sourceSet: SourceSet, sourceDirectorySetFactory: SourceDirectorySetFactory) : I18nSourceSet {
   override val po: SourceDirectorySet = sourceDirectorySetFactory.create(
     "i18nPo",

src/main/kotlin/i18n/I18nSourceSet.kt

@@ -3,17 +3,58 @@ package org.openstreetmap.josm.gradle.plugin.i18n
 import groovy.lang.Closure
 import org.gradle.api.Action
 import org.gradle.api.file.SourceDirectorySet
+import org.gradle.api.tasks.SourceSet
 
+/**
+ * Interface that defines a container for three [SourceDirectorySet]s each one containing files for one of these
+ * translation formats: *.po, *.mo (both from gettext) and *.lang (custom format for JOSM).
+ */
 interface I18nSourceSet {
+  /**
+   * Source set for *.po files (by default only files ending in `.po` are considered).
+   */
   val po: SourceDirectorySet
+  /**
+   * Source set for *.mo files (by default only files ending in `.mo` are considered).
+   */
   val mo: SourceDirectorySet
+  /**
+   * Source set for *.lang files (by default only files ending in `.lang` are considered)
+   */
   val lang: SourceDirectorySet
 
+  /**
+   * The name of the [SourceSet] for which this interface provides [SourceDirectorySet]s for i18n.
+   */
   val name: String
+
+  /**
+   * Configure the [SourceDirectorySet] for *.lang files using a [Closure].
+   */
   fun lang(configureClosure: Closure<in SourceDirectorySet>): I18nSourceSet
+
+  /**
+   * Configure the [SourceDirectorySet] for *.lang files using an [Action].
+   */
   fun lang(configureAction: Action<in SourceDirectorySet>): I18nSourceSet
+
+  /**
+   * Configure the [SourceDirectorySet] for *.mo files using a [Closure].
+   */
   fun mo(configureClosure: Closure<in SourceDirectorySet>): I18nSourceSet
+
+  /**
+   * Configure the [SourceDirectorySet] for *.mo files using an [Action].
+   */
   fun mo(configureAction: Action<in SourceDirectorySet>): I18nSourceSet
+
+  /**
+   * Configure the [SourceDirectorySet] for *.po files using a [Closure].
+   */
   fun po(configureClosure: Closure<in SourceDirectorySet>): I18nSourceSet
+
+  /**
+   * Configure the [SourceDirectorySet] for *.po files using an [Action].
+   */
   fun po(configureAction: Action<in SourceDirectorySet>): I18nSourceSet
 }

src/main/kotlin/i18n/io/FourBytes.kt

@@ -2,8 +2,19 @@ package org.openstreetmap.josm.gradle.plugin.i18n.io
 
 /**
  * Container class for four bytes, that can then be converted to a [Long] value, either as big endian or little endian.
+ * @param a first byte
+ * @param b second byte
+ * @param c third byte
+ * @param d fourth byte
  */
 class FourBytes(val a: Byte, val b: Byte, val c: Byte, val d: Byte) {
+
+  /**
+   * Convert the four byte values to one long value.
+   * @param bigEndian determines byte order. If `true`, byte order is big-endian.
+   *   Otherwise the byte order is little-endian.
+   * @return the long value represented by the four bytes [a], [b], [c] and [d], respecting the given byte order.
+   */
   fun getLongValue(bigEndian: Boolean): Long {
     if (bigEndian) {
       // Big endian: "Beginning at the big end", first byte is most significant

src/main/kotlin/i18n/io/LangWriter.kt

@@ -7,6 +7,9 @@ import java.io.IOException
 import java.io.OutputStream
 import java.nio.charset.StandardCharsets
 
+/**
+ * Writer for creating *.lang files from a [Map] of [MsgId]s to [MsgStr]s, which e.g. [MoReader.readFile] can produce.
+ */
 class LangWriter {
   /**
    * Takes translation definitions in the form of [MsgId]s and [MsgStr]s for multiple languages.
@@ -15,6 +18,7 @@ class LangWriter {
    * @param [languageMaps] a map with language codes as keys and maps as values.
    *   These maps associates each [MsgId] a [MsgStr], which is the translation of the [MsgId].
    * @param [originLang] the language code of the language in which the strings were written in the source code.
+   * @throws IOException if writing the file is not successful
    */
   fun writeLangFile(langFileDir: File, languageMaps: Map<String, Map<MsgId, MsgStr>>, originLang: String = "en") {
     // If the original language is present in the languageMaps, then use the msgids from that file.

src/main/kotlin/i18n/io/MoReader.kt

@@ -5,10 +5,14 @@ import java.io.InputStream
 import java.net.URL
 import java.nio.charset.StandardCharsets
 
+/**
+ * Reads the strings contained inside a *.mo file.
+ * @param moFileURL the URL of the *.mo file that you want to read
+ */
 class MoReader(val moFileURL: URL) {
   companion object {
     /**
-     * The big-endian magic bytes (little-endian would be reversed)
+     * The big-endian magic bytes of *.mo files (little-endian would be reversed)
      */
     val BE_MAGIC: List<Byte> = listOf(/* 0x95 */ -107, /* 0x04 */ 4, /* 0x12 */ 18, /* 0xde */ -34)
   }
@@ -28,6 +32,11 @@ class MoReader(val moFileURL: URL) {
   private var offsetHashingTable: Long = 0
     private set
 
+  /**
+   * Reads the *.mo file at the given [URL] and returns the contained strings as a [Map] from [MsgId]s to [MsgStr]s.
+   * @throws NotImplementedError If the file contains a string longer than [Int.MAX_VALUE]
+   * @throws IOException If the
+   */
   fun readFile(): Map<MsgId, MsgStr> {
     // Stream 1 reads the indices of the strings
     val stream1 = moFileURL.openStream()
@@ -111,6 +120,8 @@ class MoReader(val moFileURL: URL) {
 /**
  * Read bytes from the input stream into the array. If there are not enough
  * bytes to fill the array, an exception is thrown.
+ * @throws IOException if reading from the [InputStream] fails (see [InputStream.read]) or if the number of bytes that
+ *   can be read is below the parameter [b].
  */
 private fun safeRead(stream: InputStream, b: ByteArray): Int {
   val readBytes = stream.read(b)

src/main/kotlin/i18n/io/MsgId.kt

@@ -1,3 +1,9 @@
 package org.openstreetmap.josm.gradle.plugin.i18n.io
 
+/**
+ * A translatable string ([MsgStr]) with an optional [String] context.
+ * @param id the string (optonally with plural versions) to be translated
+ * @param context an optional context with additional information for which situations the string should be translated
+ *   (e.g. for disambiguation of multiple identicals strings that should be translated differently in different situations)
+ */
 data class MsgId(val id: MsgStr, val context: String? = null)

src/main/kotlin/i18n/io/MsgStr.kt

@@ -1,7 +1,16 @@
 package org.openstreetmap.josm.gradle.plugin.i18n.io
 
+/**
+ * A single translatable string in singular and optionally one or more plural versions.
+ * @param strings a list of all singular and plural variants of this string. The first element is the singular version,
+ *   the rest of the elements are the plurals.
+ */
 data class MsgStr(val strings: List<String>) {
-  constructor(firstString: String, vararg moreStrings: String): this(listOf(firstString, *moreStrings))
+  /**
+   * @param singularString the singular version of the translatable string
+   * @param pluralStrings the plural versions of the translatable string
+   */
+  constructor(singularString: String, vararg pluralStrings: String): this(listOf(singularString, *pluralStrings))
   init {
     require(strings.size >= 1){"A MsgStr has to consist of at least one string!"}
   }

src/main/kotlin/packages.md

@@ -12,6 +12,14 @@ Classes for configuring the Gradle build of your JOSM plugin.
 
 [I18nConfig] and [JosmManifest] provide some specialized options for internationalization and the `MANIFEST.MF` file of your JOSM plugin. These are accessible via `project.josm.i18n` and `project.josm.manifest`.
 
+# Package org.openstreetmap.josm.gradle.plugin.i18n
+
+The source set definition for the different translation formats (*.lang, *.po and *.mo).
+
+# Package org.openstreetmap.josm.gradle.plugin.i18n.io
+
+A reader for *.mo files and a writer for JOSM's *.lang files
+
 # Package org.openstreetmap.josm.gradle.plugin.task
 
-Reusable Gradle tasks, at the moment only [RunJosmTask].
+Reusable Gradle tasks.

src/main/kotlin/task/CleanJosm.kt

@@ -2,10 +2,21 @@ package org.openstreetmap.josm.gradle.plugin.task
 
 import org.gradle.api.DefaultTask
 import org.gradle.api.tasks.Delete
+import org.openstreetmap.josm.gradle.plugin.config.JosmPluginExtension
 import org.openstreetmap.josm.gradle.plugin.josm
 import java.io.File
 import java.util.Locale
 
+/**
+ * Virtual task that coordinates deletion of the temporary JOSM preferences.
+ *
+ * This task creates three subtasks with the same name as itself, only with the suffixes `Cache`, `Pref` and `Userdata`.
+ * Each one of these subtasks deletes one of the directories defined at [JosmPluginExtension.tmpJosmCacheDir],
+ * [JosmPluginExtension.tmpJosmPrefDir] and [JosmPluginExtension.tmpJosmUserdataDir].
+ *
+ * This task depends on all three of these, so all subtasks run when you execute this task. But you can also run the
+ * subtasks individually by calling them directly.
+ */
 open class CleanJosm : DefaultTask() {
   init {
     group = "JOSM"

src/main/kotlin/task/DebugJosm.kt

@@ -5,6 +5,10 @@ import org.gradle.api.tasks.TaskExecutionException
 import org.openstreetmap.josm.gradle.plugin.config.JosmPluginExtension
 import org.openstreetmap.josm.gradle.plugin.josm
 
+/**
+ * The same as [RunJosmTask], but the JOSM instance is debuggable via JDWP (Java debug wire protocol) on the port
+ * configured at [JosmPluginExtension.debugPort].
+ */
 open class DebugJosm : RunJosmTask() {
   @Input
   private var debugPort: Int? = null

src/main/kotlin/task/GenerateFileList.kt

@@ -5,10 +5,19 @@ import org.gradle.api.tasks.Internal
 import org.gradle.api.tasks.SourceSet
 import java.io.File
 
+/**
+ * Outputs a file containing the absolute paths of all Java source files
+ */
 open class GenerateFileList: DefaultTask() {
+  /**
+   * The file to which the file list is written. Gets overwritten when this task executes.
+   */
   @Internal
   lateinit var outFile: File
 
+  /**
+   * The source set for which the file list is generated.
+   */
   @Internal
   lateinit var srcSet: SourceSet
 

src/main/kotlin/task/GeneratePot.kt

@@ -16,8 +16,17 @@ import java.io.OutputStreamWriter
 import java.nio.charset.StandardCharsets
 import java.time.Year
 
+/**
+ * Create *.pot file (gettext file format), which contains all translatable strings.
+ * This file can then be handed to the translators to translate into other languages.
+ *
+ * For this task to work the command line tool `xgettext` is required!
+ */
 open class GeneratePot: Exec() {
   private lateinit var outBaseName: String
+  /**
+   * The task that generates a list of all source files. That file is needed to tell xgettext, which files it should examine.
+   */
   @Internal
   lateinit var fileListGenTask: GenerateFileList
 

src/main/kotlin/task/InitJosmPrefs.kt

@@ -1,9 +1,16 @@
 package org.openstreetmap.josm.gradle.plugin.task
 
 import org.gradle.api.tasks.Copy
+import org.openstreetmap.josm.gradle.plugin.config.JosmPluginExtension
 import org.openstreetmap.josm.gradle.plugin.josm
 import java.io.File
 
+/**
+ * A simple copy task that copies a `preferences.xml` file from [JosmPluginExtension.josmConfigDir] to
+ * [JosmPluginExtension.tmpJosmPrefDir] if there is not already one in the destination.
+ *
+ * This way you can provide a default JOSM configuration for the [RunJosmTask].
+ */
 open class InitJosmPrefs: Copy() {
   private val PREF_FILE_NAME = "preferences.xml"
   init {

src/main/kotlin/task/LangCompile.kt

@@ -13,9 +13,15 @@ import java.io.File
  */
 open class LangCompile : Sync() {
 
+  /**
+   * The source set from which all *.lang files are synced to the destination
+   */
   @Internal
   lateinit var sourceSet: I18nSourceSet
 
+  /**
+   * The task for compiling *.mo files to *.lang files. These outputs are then used as inputs for this task.
+   */
   @Internal
   lateinit var moCompile: MoCompile
 

src/main/kotlin/task/ListJosmVersions.kt

@@ -7,6 +7,9 @@ import java.io.InputStreamReader
 import java.net.URL
 import java.nio.charset.StandardCharsets
 
+/**
+ * Task for showing the current `latest` and `tested` JOSM versions
+ */
 open class ListJosmVersions : DefaultTask() {
   private val BASE_URL = "https://josm.openstreetmap.de"
 

src/main/kotlin/task/MoCompile.kt

@@ -17,6 +17,9 @@ import java.io.File
  * For the other languages, the "msgstr" is used (the text which is already translated to this language).
  */
 open class MoCompile : DefaultTask() {
+  /**
+   * The task for compiling *.po files to *.mo files. Its outputs are used as inputs for this task.
+   */
   @Internal
   lateinit var poCompile: PoCompile
 

src/main/kotlin/task/PoCompile.kt

@@ -10,9 +10,15 @@ import java.util.concurrent.TimeUnit
 
 /**
  * Compile *.po files (textual gettext files) to *.mo files (binary gettext files).
+ *
+ * This task requires the command line tool `msgfmt` (part of GNU gettext) to work properly! If the tool is not
+ * installed, it will only issue a warning (not fail), but translations from *.po files won't be available.
  */
 open class PoCompile: DefaultTask() {
 
+  /**
+   * The source set, for which all *.po files will be compiled to *.mo files.
+   */
   @Internal
   lateinit var sourceSet: I18nSourceSet
 

src/main/kotlin/task/RunJosmTask.kt

@@ -8,7 +8,8 @@ import org.openstreetmap.josm.gradle.plugin.useSeparateTmpJosmDirs
 import java.io.File
 
 /**
- * A task that can execute a JOSM instance. Both the {@code runJosm} task and the `debugJosm` task extend this type of task.
+ * A task that can execute a JOSM instance. There's also the class [DebugJosm], which extends this class and allows to
+ * remote debug via JDWP (Java debug wire protocol).
  *
  * @constructor
  * Instantiates a new task for running a JOSM instance.

src/main/kotlin/task/ShortenPoFiles.kt

@@ -8,7 +8,19 @@ import org.openstreetmap.josm.gradle.plugin.josm
 import java.nio.charset.StandardCharsets
 import java.nio.file.Files
 
+/**
+ * Shortens the *.po files in the given source set.
+ *
+ * This means all occurences of the source code locations of the translated strings are stripped, as well as the
+ * last translator of the *.po file.
+ * Also some fields in the file header are filled out (package name, copyright holder and a descriptive title).
+ *
+ * This task should be run after downloading fresh translations from Transifex (e.g. with [TransifexDownload]).
+ */
 open class ShortenPoFiles : DefaultTask() {
+  /**
+   * The source set for which this task will shorten the *.po files.
+   */
   @Input
   lateinit var sourceSet: I18nSourceSet
 

src/main/kotlin/task/TaskSetup.kt

@@ -8,6 +8,9 @@ import org.openstreetmap.josm.gradle.plugin.java
 import org.openstreetmap.josm.gradle.plugin.josm
 import java.io.File
 
+/**
+ * This method sets up all the [Task]s (and [Configuration]s) for a given project that should be there by default.
+ */
 fun Project.setupJosmTasks() {
   tasks.create("cleanJosm", CleanJosm::class.java)