Mark CompletionCandidates.Custom as experimental (#120)

Author: ajalt

CHANGELOG.md

@@ -3,14 +3,14 @@
 ## [Unreleased]
 ### Added
 - `CompletionCandidates.Fixed` now has a secondary convenience constructor that take a `vararg` of `String`s
-- `CompletionCadidates.Custom`, which allows you to call other binaries or write a script to generate completions.
+- `CompletionCadidates.Custom`, which allows you to call other binaries or write a script to generate completions. This class is currently experimental. ([#79](https://github.com/ajalt/clikt/issues/79))
 - `Option.wrapValue` and `Argument.wrapValue` to make it easier to reuse existing conversion functions.
 - `ignoreCase` parameter to `choice()` and `enum()` conversion functions.
 
 ### Changed
 - `option()` and `argument()` now take optional `completionCandidates` parameters to override how completion is generated. The constructor and `copy` functions of `OptionsWithValues` and `ProcessedArgument` have changed to support default values.
-- The overloads of `findObject` ([1](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.core/-context/find-object/) [2](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.core/find-object/)) that take a default value have been renamed `findOrSetObject`. The existing names are marked with `@Deprecated`, and IntelliJ can convert your callsites automatically.
-- `enum()` parameters now accept case-insensitive values by default. You change this behavior by passing `ignoreCase = false` to `enum()`
+- The overloads of `findObject` ([1](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.core/-context/find-object/) [2](https://ajalt.github.io/clikt/api/clikt/com.github.ajalt.clikt.core/find-object/)) that take a default value have been renamed `findOrSetObject`. The existing names are marked with `@Deprecated`, and IntelliJ can convert your callsites automatically. ([#110](https://github.com/ajalt/clikt/issues/110))
+- `enum()` parameters now accept case-insensitive values by default. You change this behavior by passing `ignoreCase = false` to `enum()` ([#115](https://github.com/ajalt/clikt/issues/115))
 
 ### Fixed
 - `groupChoice` help output now includes the choices in the help output metavar

clikt/build.gradle

@@ -15,6 +15,18 @@ buildscript {
     }
 }
 
+compileKotlin {
+    kotlinOptions {
+        freeCompilerArgs += "-Xuse-experimental=kotlin.Experimental"
+    }
+}
+
+compileTestKotlin {
+    kotlinOptions {
+        freeCompilerArgs += "-Xuse-experimental=kotlin.Experimental"
+    }
+}
+
 task sourcesJar(type: Jar, dependsOn: classes) {
     classifier = 'sources'
     from sourceSets.main.allSource

clikt/src/main/kotlin/com/github/ajalt/clikt/completion/CompletionCandidates.kt

@@ -1,5 +1,10 @@
 package com.github.ajalt.clikt.completion
 
+@Experimental
+@Retention(AnnotationRetention.BINARY)
+@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
+annotation class ExperimentalCompletionCandidates
+
 /**
  * Configurations for generating shell autocomplete suggestions
  */
@@ -38,6 +43,7 @@ sealed class CompletionCandidates {
      * word being typed. The word being typed can be retrieved from the `COMP_WORDS` array at index
      * `COMP_CWORD`.
      */
+    @ExperimentalCompletionCandidates
     data class Custom(val generator: (ShellType) -> String?) : CompletionCandidates() {
         enum class ShellType { BASH }
         companion object {

clikt/src/main/kotlin/com/github/ajalt/clikt/completion/CompletionGenerator.kt

@@ -4,6 +4,7 @@ import com.github.ajalt.clikt.completion.CompletionCandidates.Custom.ShellType
 import com.github.ajalt.clikt.core.CliktCommand
 
 internal object CompletionGenerator {
+    @UseExperimental(ExperimentalCompletionCandidates::class)
     fun generateCompletion(command: CliktCommand, zsh: Boolean = true): String {
         val commandName = command.commandName
         val (isTopLevel, funcName) = commandCompletionFuncName(command)

clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/arguments/Argument.kt

@@ -375,6 +375,7 @@ inline fun <T : Any> RawArgument.convert(
         level = DeprecationLevel.ERROR
 )
 @JvmName("rawWrapValue")
+@Suppress("UNUSED_PARAMETER")
 fun RawArgument.wrapValue(wrapper: (String) -> Any): RawArgument = this
 
 /**

clikt/src/main/kotlin/com/github/ajalt/clikt/parameters/options/OptionWithValues.kt

@@ -595,6 +595,7 @@ inline fun <T : Any> RawOption.convert(
         level = DeprecationLevel.ERROR
 )
 @JvmName("rawWrapValue")
+@Suppress("UNUSED_PARAMETER")
 fun RawOption.wrapValue(wrapper: (String) -> Any): RawOption = this
 
 /**

clikt/src/test/kotlin/com/github/ajalt/clikt/completion/CompletionTest.kt

@@ -12,6 +12,7 @@ import org.junit.Rule
 import org.junit.Test
 import org.junit.contrib.java.lang.system.EnvironmentVariables
 
+@UseExperimental(ExperimentalCompletionCandidates::class)
 @Suppress("unused")
 class CompletionTest {
     @Rule