provide alternative for manual features in case of new inference

apis/infix-en_GB/atrium-api-infix-en_GB-common/src/main/kotlin/ch/tutteli/atrium/api/infix/en_GB/featureAssertions.kt

@@ -118,6 +118,7 @@ infix fun <T, R> Expect<T>.feature(provider: MetaFeatureOption<T>.(T) -> MetaFea
  *
  * ```
  * // use
+ * import ch.tutteli.atrium.api.infix.en_GB.workaround.it
  * expect(person) feature { f(it::age) } it { o toBe 20 }
  *
  * // instead of (which causes problems with Kotlin < 1.4)
@@ -149,6 +150,10 @@ infix fun <T, R> Expect<T>.feature(of: MetaFeatureOptionWithCreator<T, R>): Expe
  * expect(person) feature { f("first underage child", it.children.first { it < 18 }) }
  * ```
  *
+ * Note that you can use `feature of("first underage child") { children.first { it < 18 } }` with the new type inference
+ * enabled (e.g. if you use Kotlin 1.4 or above).
+ * This method will most likely be removed once Kotlin 1.4 is out (probably with Atrium 1.0)
+ *
  * @return The newly created [MetaFeature].
  */
 @Suppress("unused" /* unused receiver, but that's fine */)
@@ -158,72 +163,96 @@ fun <T, R> MetaFeatureOption<T>.f(description: String, provider: R): MetaFeature
 //@formatter:off
 /**
  * Helper function to create a [Feature] based on a [KFunction2] + arguments.
+ *
+ * @return The newly created [Feature].
  */
 fun <T, A1, R> of(f: KFunction2<T, A1, R>, a1: A1): Feature<T, R> =
     Feature(formatMethodCall(f, a1)) { f.invoke(it, a1) }
 
 /**
  * Helper function to create a [Feature] based on a [KFunction3] + arguments.
+ *
+ * @return The newly created [Feature].
  */
 fun <T, A1, A2, R > of(f: KFunction3<T, A1, A2, R>, a1: A1, a2: A2): Feature<T, R> =
      Feature(formatMethodCall(f, a1, a2)) { f.invoke(it, a1, a2) }
 
 /**
  * Helper function to create a [Feature] based on a [KFunction4] + arguments.
+ *
+ * @return The newly created [Feature].
  */
 fun <T, A1, A2, A3, R> of(f:  KFunction4<T, A1, A2, A3, R>, a1: A1, a2: A2, a3: A3): Feature<T, R> =
      Feature(formatMethodCall(f, a1, a2, a3)) { f.invoke(it, a1, a2, a3) }
 
 /**
  * Helper function to create a [Feature] based on a [KFunction5] + arguments.
+ *
+ * @return The newly created [Feature].
  */
 fun <T, A1, A2, A3, A4, R> of(f: KFunction5<T, A1, A2, A3, A4, R>, a1: A1, a2: A2, a3: A3, a4: A4): Feature<T, R> =
      Feature(formatMethodCall(f, a1, a2, a3, a4)) { f.invoke(it, a1, a2, a3, a4) }
 
 /**
  * Helper function to create a [Feature] based on a [KFunction6] + arguments.
+ *
+ * @return The newly created [Feature].
  */
 fun <T, A1, A2, A3, A4, A5, R> of(f: KFunction6<T, A1, A2, A3, A4, A5, R>, a1: A1, a2: A2, a3: A3, a4: A4, a5: A5): Feature<T, R> =
     Feature(formatMethodCall(f, a1, a2, a3, a4, a5)) { f.invoke(it, a1, a2, a3, a4, a5) }
 
 /**
  * Helper function to create a [FeatureWithCreator] based on a [KProperty1] + [assertionCreator].
+ *
+ * @return The newly created [FeatureWithCreator].
  */
 fun <T, R> of(property: KProperty1<in T, R>, assertionCreator: Expect<R>.() -> Unit): FeatureWithCreator<T, R> =
     FeatureWithCreator(property.name, { property.invoke(it) }, assertionCreator)
 
 /**
  * Helper function to create a [FeatureWithCreator] based on a [KFunction1] + [assertionCreator].
+ *
+ * @return The newly created [FeatureWithCreator].
  */
 fun <T, R> of(f: KFunction1<T, R>, assertionCreator: Expect<R>.() -> Unit): FeatureWithCreator<T, R> =
     FeatureWithCreator(formatMethodCall(f), { f.invoke(it) }, assertionCreator)
 
 /**
  * Helper function to create a [FeatureWithCreator] based on a [KFunction2] + arguments + [assertionCreator].
+ *
+ * @return The newly created [FeatureWithCreator].
  */
 fun <T, A1, R> of(f: KFunction2<T, A1, R>, a1: A1, assertionCreator: Expect<R>.() -> Unit): FeatureWithCreator<T, R> =
     FeatureWithCreator(formatMethodCall(f, a1), { f.invoke(it, a1) }, assertionCreator)
 
 /**
  * Helper function to create a [FeatureWithCreator] based on a [KFunction3] + arguments + [assertionCreator].
+ *
+ * @return The newly created [FeatureWithCreator].
  */
 fun <T, A1, A2, R > of(f: KFunction3<T, A1, A2, R>, a1: A1, a2: A2, assertionCreator: Expect<R>.() -> Unit): FeatureWithCreator<T, R> =
      FeatureWithCreator(formatMethodCall(f, a1, a2), { f.invoke(it, a1, a2) }, assertionCreator)
 
 /**
  * Helper function to create a [FeatureWithCreator] based on a [KFunction4] + arguments + [assertionCreator].
+ *
+ * @return The newly created [FeatureWithCreator].
  */
 fun <T, A1, A2, A3, R> of(f: KFunction4<T, A1, A2, A3, R>, a1: A1, a2: A2, a3: A3, assertionCreator: Expect<R>.() -> Unit): FeatureWithCreator<T, R> =
      FeatureWithCreator(formatMethodCall(f, a1, a2, a3), { f.invoke(it, a1, a2, a3) }, assertionCreator)
 
 /**
  * Helper function to create a [FeatureWithCreator] based on a [KFunction5] + arguments + [assertionCreator].
+ *
+ * @return The newly created [FeatureWithCreator].
  */
 fun <T, A1, A2, A3, A4, R> of(f: KFunction5<T, A1, A2, A3, A4, R>, a1: A1, a2: A2, a3: A3, a4: A4, assertionCreator: Expect<R>.() -> Unit): FeatureWithCreator<T, R> =
      FeatureWithCreator(formatMethodCall(f, a1, a2, a3, a4), { f.invoke(it, a1, a2, a3, a4) }, assertionCreator)
 
 /**
  * Helper function to create a [FeatureWithCreator] based on a [KFunction6] + arguments + [assertionCreator].
+ *
+ * @return The newly created [FeatureWithCreator].
  */
 fun <T, A1, A2, A3, A4, A5, R> of(f: KFunction6<T, A1, A2, A3, A4, A5, R>, a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, assertionCreator: Expect<R>.() -> Unit): FeatureWithCreator<T, R> =
     FeatureWithCreator(formatMethodCall(f, a1, a2, a3, a4, a5), { f.invoke(it, a1, a2, a3, a4, a5) }, assertionCreator)
@@ -244,3 +273,63 @@ fun <T, R> of(
         provider,
         assertionCreator
     )
+
+/**
+ * Creates a [Feature] using the given [extractor] and [description].
+ *
+ * This can be used to create complex features with a custom description or as workaround where Kotlin is not able to
+ * infer the types properly.
+ *
+ * For instance:
+ * ```
+ * expect(person) feature of("first underage child") { children.first { it < 18 } }
+ * ```
+ *
+ * Note, you need to enable the new type inference of Kotlin (or use Kotlin 1.4 and above) in order that Kotlin
+ * is able to infer the types.
+ * As workaround you can use [feature] with the overload which expects `MetaFeatureOption<T>.(T) -> MetaFeature<R>`.
+ * For instance:
+ * ```
+ * // use
+ * expect(person) feature { f("first underage child", { it.children.first { it < 18 }) }
+ *
+ * // instead of (which causes problems with Kotlin < 1.4)
+ * expect(person) feature of("first underage child") { children.first { it < 18 }
+ * ```
+ *
+ * @return The newly created [Feature].
+ */
+fun <T, R> of(description: String, extractor: T.() -> R): Feature<T, R> =
+    Feature(description, extractor)
+
+/**
+ * Creates a [Feature] using the given [extractor] and [description].
+ *
+ * This can be used to create complex features with a custom description or as workaround where Kotlin is not able to
+ * infer the types properly.
+ *
+ * For instance:
+ * ```
+ * expect(person) feature of("first underage child", { children.first { it < 18 }) { name.toBe("robert) }
+ * ```
+ *
+ * Note, you need to enable the new type inference of Kotlin (or use Kotlin 1.4 and above) in order that Kotlin
+ * is able to infer the types.
+ * As workaround you can use [feature] with the overload which expects `MetaFeatureOption<T>.(T) -> MetaFeature<R>`.
+ * and use `it` after the call (import from the package workaround). For instance:
+ * ```
+ * // use
+ * import ch.tutteli.atrium.api.infix.en_GB.workaround.it
+ * expect(person) feature { f(it::age) } it { o toBe 20 }
+ *
+ * // instead of (which causes problems with Kotlin < 1.4)
+ * expect(person) feature of({ f(it::age) }) { o toBe 20 }
+ * ```
+ *
+ * @return The newly created [Feature].
+ */
+fun <T, R> of(
+    description: String,
+    extractor: T.() -> R,
+    assertionCreator: Expect<R>.() -> Unit
+): FeatureWithCreator<T, R> = FeatureWithCreator(description, extractor, assertionCreator)