Implement a load of TODOs and clean up docs

build.gradle.kts

@@ -41,6 +41,7 @@ dependencies {
     testRuntimeOnly("org.junit.platform:junit-platform-runner:${properties("junitRunnerVersion")}")
     testImplementation("org.junit.jupiter:junit-jupiter-api:${properties("junitVersion")}")
     testImplementation("org.junit.jupiter:junit-jupiter-engine:${properties("junitVersion")}")
+    testImplementation("org.junit.vintage:junit-vintage-engine:${properties("junitVersion")}")
     testImplementation("io.kotest:kotest-assertions-core:${properties("kotestVersion")}")
     testImplementation("io.kotest:kotest-framework-datatest:${properties("kotestVersion")}")
     testImplementation("io.kotest:kotest-runner-junit5:${properties("kotestVersion")}")

src/main/kotlin/com/fwdekker/randomness/Bundle.kt

@@ -17,8 +17,6 @@ object Bundle {
     /**
      * Returns the string at [key].
      *
-     * @param key the key of the string to return
-     * @return the string at [key]
      * @throws MissingResourceException if no string with [key] can be found
      */
     @Throws(MissingResourceException::class)
@@ -27,9 +25,6 @@ object Bundle {
     /**
      * Returns the string at [key] formatted with [arguments].
      *
-     * @param key the key of the string to return
-     * @param arguments the arguments to insert into the template
-     * @return the string at [key] formatted with [arguments]
      * @throws MissingResourceException if no string with [key] can be found
      */
     @Throws(MissingResourceException::class)
@@ -43,7 +38,6 @@ object Bundle {
  * @throws java.util.MissingFormatArgumentException if [args] has fewer arguments than required for [format]
  */
 fun String.matchesFormat(format: String, vararg args: String) =
-    // TODO: Simplify documentation everywhere throughout the project to remove redundant `@param` specifications
     Regex("%[0-9]+\\\$[Ss]").findAll(format)
         .toList()
         .reversed()

src/main/kotlin/com/fwdekker/randomness/CapitalizationMode.kt

@@ -44,28 +44,21 @@ enum class CapitalizationMode(val transform: (String, Random) -> String) {
 
     /**
      * Returns the localized string name of this mode.
-     *
-     * @return the localized string name of this mode
      */
     fun toLocalizedString() =
         Bundle("shared.capitalization.${toString().replace(' ', '_').lowercase(Locale.getDefault())}")
 }
 
 
 /**
- * Randomly converts this character to uppercase or lowercase.
- *
- * @param random the source of randomness to use
- * @return the uppercase or lowercase version of this character
+ * Randomly converts this character to uppercase or lowercase using [random] as a source of randomness.
  */
 private fun Char.toRandomCase(random: Random) =
     if (random.nextBoolean()) this.lowercaseChar()
     else this.uppercaseChar()
 
 /**
  * Turns the first character uppercase while all other characters become lowercase.
- *
- * @return the sentence-case form of this string
  */
 private fun String.toSentenceCase() =
     this.lowercase(Locale.getDefault()).replaceFirstChar { it.uppercaseChar() }

src/main/kotlin/com/fwdekker/randomness/ErrorReporter.kt

@@ -24,8 +24,6 @@ import java.nio.charset.StandardCharsets
 class ErrorReporter : ErrorReportSubmitter() {
     /**
      * Returns the text that is displayed in the button to report the error.
-     *
-     * @return the text that is displayed in the button to report the error
      */
     override fun getReportActionText() = Bundle("reporter.report")
 
@@ -62,17 +60,12 @@ class ErrorReporter : ErrorReportSubmitter() {
 
     /**
      * Returns the privacy notice text.
-     *
-     * @return the privacy notice text
      */
     override fun getPrivacyNoticeText() = Bundle("reporter.privacy_notice")
 
 
     /**
-     * Constructs a URL to create an issue with [additionalInfo] that is below the maximum URL limit.
-     *
-     * @param additionalInfo additional information about the exception provided by the user
-     * @return a URL to create an issue with [additionalInfo] that is below the maximum URL limit
+     * Constructs a URL to create an issue that provides [additionalInfo] and is below the maximum URL limit.
      */
     fun getIssueUrl(additionalInfo: String?): String {
         val baseUrl = "https://github.com/FWDekker/intellij-randomness/issues/new?body="
@@ -81,27 +74,17 @@ class ErrorReporter : ErrorReportSubmitter() {
             "Additional info",
             if (additionalInfo.isNullOrBlank()) MORE_DETAIL_MESSAGE else additionalInfo
         )
-        val stacktraceSection = createMarkdownSection(
-            "Stacktraces",
-            STACKTRACE_MESSAGE
-        )
-        val versionSection = createMarkdownSection(
-            "Version information",
-            getFormattedVersionInformation()
-        )
+        val stacktraceSection = createMarkdownSection("Stacktraces", STACKTRACE_MESSAGE)
+        val versionSection = createMarkdownSection("Version information", getFormattedVersionInformation())
 
         return URLEncoder.encode(additionalInfoSection + stacktraceSection + versionSection, StandardCharsets.UTF_8)
             .replace("%2B", "+")
             .let { baseUrl + it }
     }
 
     /**
-     * Creates a Markdown "section" containing the title in bold followed by the contents on the next line, finalized by
-     * two newlines.
-     *
-     * @param title the title of the section
-     * @param contents the contents of the section
-     * @return a Markdown "section" with the [title] and [contents]
+     * Creates a Markdown "section" containing the [title] in bold followed by the [contents] on the next line,
+     * finalized by two newlines.
      */
     private fun createMarkdownSection(title: String, contents: String) =
         """
@@ -111,8 +94,6 @@ class ErrorReporter : ErrorReportSubmitter() {
 
     /**
      * Returns version information on the user's environment as a Markdown-style list.
-     *
-     * @return version information on the user's environment as a Markdown-style list
      */
     private fun getFormattedVersionInformation() =
         """

src/main/kotlin/com/fwdekker/randomness/Icons.kt

@@ -87,9 +87,6 @@ data class TypeIcon(val base: Icon, val text: String, val colors: List<Color>) :
 
     /**
      * Returns an icon that describes both this icon's type and [other]'s type.
-     *
-     * @param other the icon to combine this icon with
-     * @return an icon that describes both this icon's type and [other]'s type
      */
     fun combineWith(other: TypeIcon) =
         TypeIcon(
@@ -216,8 +213,8 @@ data class OverlayIcon(val base: Icon, val background: Icon? = null) : Icon {
 /**
  * An icon with various icons displayed on top of it as overlays.
  *
- * @property base TODO
- * @property overlays TODO
+ * @property base The underlying base icon.
+ * @property overlays The various icons that are overlayed on top of [base].
  */
 data class OverlayedIcon(val base: Icon, val overlays: List<Icon> = emptyList()) : Icon {
     init {
@@ -229,9 +226,6 @@ data class OverlayedIcon(val base: Icon, val overlays: List<Icon> = emptyList())
 
     /**
      * Returns a copy of this icon that has [icon] as an additional overlay icon.
-     *
-     * @param icon the additional overlay icon
-     * @return a copy of this icon that has [icon] as an additional overlay icon
      */
     fun plusOverlay(icon: Icon) = copy(overlays = overlays + icon)
 
@@ -314,27 +308,17 @@ class RadialColorReplacementFilter(
 
     /**
      * Returns [toShift] which has its alpha multiplied by that of [shiftBy].
-     *
-     * @param toShift the color of which to shift the alpha
-     * @param shiftBy the color which has the alpha to shift by
-     * @return [toShift] which has its alpha multiplied by that of [shiftBy]
      */
     private fun shiftAlpha(toShift: Color, shiftBy: Color) =
         ColorUtil.withAlpha(toShift, asFraction(toShift.alpha) * asFraction(shiftBy.alpha))
 
     /**
-     * Represents an integer in the range `[0, 256)` to a fraction of that range.
-     *
-     * @param number the number to represent as a fraction
-     * @return number as a fraction
+     * Represents a [number] in the range `[0, 256)` as a fraction of that range.
      */
     private fun asFraction(number: Int) = number / COMPONENT_MAX.toDouble()
 
     /**
-     * Converts an offset to the [center] to a color in [colors].
-     *
-     * @param offset the offset to get the color for
-     * @return the color to be displayed at [offset]
+     * Returns the appropriate color from [colors] for an [offset] relative to the [center].
      */
     private fun positionToColor(offset: Pair<Int, Int>): Color {
         val angle = 2 * Math.PI - (atan2(offset.second.toDouble(), offset.first.toDouble()) + STARTING_ANGLE)

src/main/kotlin/com/fwdekker/randomness/InsertAction.kt

@@ -21,8 +21,8 @@ import javax.swing.Icon
  *
  * @property repeat `true` if and only if the same value should be inserted at each caret.
  * @property text The text that identifies the action to the user.
- * @param description The optional description of the action.
- * @param icon The icon that represents the action.
+ * @param description the optional description of the action
+ * @param icon the icon that represents the action
  */
 abstract class InsertAction(
     val repeat: Boolean = false,
@@ -40,8 +40,6 @@ abstract class InsertAction(
 
     /**
      * Specifies the thread in which [update] is invoked.
-     *
-     * @return the thread in which [update] is invoked
      */
     override fun getActionUpdateThread() = ActionUpdateThread.EDT
 
@@ -106,9 +104,6 @@ abstract class InsertAction(
 
     /**
      * Generates [count] strings.
-     *
-     * @param count the number of strings to generate
-     * @return [count] strings
      */
     abstract fun generateStrings(count: Int): List<String>
 }

src/main/kotlin/com/fwdekker/randomness/PopupAction.kt

@@ -29,8 +29,6 @@ class PopupAction : AnAction(Icons.RANDOMNESS) {
 
     /**
      * Specifies the thread in which [update] is invoked.
-     *
-     * @return the thread in which [update] is invoked
      */
     override fun getActionUpdateThread() = ActionUpdateThread.EDT
 
@@ -77,9 +75,6 @@ class PopupAction : AnAction(Icons.RANDOMNESS) {
 
     /**
      * Returns the desired title for the popup given [event].
-     *
-     * @param event the event on which the title should be based
-     * @return the desired title for the popup given [event]
      */
     @Suppress("detekt:ComplexMethod") // Cannot be simplified
     private fun captionModifier(event: ActionEvent?): String {
@@ -140,15 +135,13 @@ class PopupAction : AnAction(Icons.RANDOMNESS) {
  */
 private class SimpleAbstractAction(private val myActionPerformed: (ActionEvent?) -> Unit) : AbstractAction() {
     /**
-     * Runs [myActionPerformed].
-     *
-     * @param event the event to pass to [myActionPerformed]
+     * @see myActionPerformed
      */
     override fun actionPerformed(event: ActionEvent?) = myActionPerformed(event)
 }
 
 /**
- * Returns the cartesian product of two lists.
+ * Returns the cartesian product of [this] and [other].
  *
  * By requiring both lists to actually be lists of lists, this method can be chained.
  *
@@ -160,10 +153,6 @@ private class SimpleAbstractAction(private val myActionPerformed: (ActionEvent?)
  * $ [[1, 2]] * [[3, 4]] * [[5, 6]]
  * [[1, 3, 5], [1, 3, 6], [1, 4, 5], [1, 4, 6], [2, 3, 5], [2, 3, 6], [2, 4, 5], [2, 4, 6]]
  * ```
- *
- * @param E the type of inner element
- * @param other the list to multiply with
- * @return the cartesian product of `this` and [other]
  */
 private operator fun <E> List<List<E>>.times(other: List<List<E>>) =
     this.flatMap { t1 -> other.map { t2 -> t1 + t2 } }

src/main/kotlin/com/fwdekker/randomness/Scheme.kt

@@ -58,13 +58,11 @@ abstract class Scheme : State() {
 
 
     /**
-     * Generates random decorated data according to the settings in this scheme and its decorators.
+     * Generates [count] random decorated data according to the settings in this scheme and its decorators.
      *
      * By default, this method applies the decorators on the output of [generateUndecoratedStrings]. Override this
      * method if the scheme should interact with its decorators in a different way.
      *
-     * @param count the number of data to generate
-     * @return random data
      * @throws DataGenerationException if data could not be generated
      */
     @Throws(DataGenerationException::class)
@@ -81,10 +79,8 @@ abstract class Scheme : State() {
     }
 
     /**
-     * Generates random data according to the settings in this scheme, ignoring settings from decorators.
+     * Generates [count] random data according to the settings in this scheme, ignoring settings from decorators.
      *
-     * @param count the number of data to generate
-     * @return random data
      * @throws DataGenerationException if data could not be generated
      * @see generateStrings
      */

src/main/kotlin/com/fwdekker/randomness/SchemeEditor.kt

@@ -11,7 +11,7 @@ import javax.swing.JComponent
  * An editor for a [Scheme].
  *
  * @param S the type of scheme edited in this editor
- * @property scheme the scheme edited in this editor
+ * @property scheme The scheme edited in this editor.
  */
 abstract class SchemeEditor<S : Scheme>(val scheme: S) : Disposable {
     /**
@@ -67,8 +67,6 @@ abstract class SchemeEditor<S : Scheme>(val scheme: S) : Disposable {
 
     /**
      * Ensures [listener] is invoked on every change in this editor.
-     *
-     * @param listener the function to invoke on every change in this editor
      */
     @Suppress("detekt:SpreadOperator") // Acceptable because this method is called rarely
     fun addChangeListener(listener: () -> Unit) =

src/main/kotlin/com/fwdekker/randomness/Settings.kt

@@ -59,15 +59,13 @@ class PersistentSettings : PersistentStateComponent<Settings> {
 
     /**
      * Returns the template list.
-     *
-     * @return the template list
      */
     override fun getState() = settings
 
     /**
-     * Invokes [TemplateList.copyFrom].
+     * Copies [settings] into `this`.
      *
-     * @param settings the state to invoke [TemplateList.copyFrom] on
+     * @see TemplateList.copyFrom
      */
     override fun loadState(settings: Settings) = this.settings.copyFrom(settings)