Apply renaming of with*FailureHint -> withHelpOn*Failure for issue #671 (#970)

core/atrium-core-common/src/main/kotlin/ch/tutteli/atrium/assertions/builders/descriptiveWithFailureHint.kt

@@ -14,9 +14,22 @@ import ch.tutteli.atrium.reporting.translating.Translatable
  * Option to create a [DescriptiveAssertion] like assertion with an additional hint which might be shown if the
  * [Descriptive.DescriptionOption.test] fails.
  *
- * You can use [withFailureHintBasedOnSubject] or [withFailureHintBasedOnDefinedSubject]
+ * You can use [withHelpOnFailureBasedOnSubject] or [withHelpOnFailureBasedOnDefinedSubject]
  * in case your [DescriptiveAssertion] is based on the subject.
  */
+fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withHelpOnFailure(
+    failureHintFactory: () -> Assertion
+): DescriptiveAssertionWithFailureHint.ShowOption =
+    DescriptiveAssertionWithFailureHint.ShowOption.create(test, failureHintFactory)
+
+/**
+ * Option to create a [DescriptiveAssertion] like assertion with an additional hint which might be shown if the
+ * [Descriptive.DescriptionOption.test] fails.
+ *
+ * You can use [withHelpOnFailureBasedOnSubject] or [withHelpOnFailureBasedOnDefinedSubject]
+ * in case your [DescriptiveAssertion] is based on the subject.
+ */
+@Deprecated("Use withHelpOnFailure; will be removed with 1.0.0")
 fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withFailureHint(
     failureHintFactory: () -> Assertion
 ): DescriptiveAssertionWithFailureHint.ShowOption =
@@ -27,20 +40,50 @@ fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withFailureHint(
  * which is based on the subject of the expectation and
  * which is only shown the subject is defined.
  *
- * You can use [withFailureHintBasedOnSubject] in case you want to:
+ * You can use [withHelpOnFailureBasedOnSubject] in case you want to:
  * - provide a hint also if the subject is absent.
  * - do not show the hint in certain cases even if the subject is defined
  *
- * Or use [withFailureHint] which does not expect a [subjectProvider] in case your [DescriptiveAssertion] is not based
+ * Or use [withHelpOnFailure] which does not expect a [subjectProvider] in case your [DescriptiveAssertion] is not based
  * on the subject of the expectation.
  */
 //TODO if we introduce Record or something else as replacement for Assertion then not but if we keep Assertion
 // then move to logic and expect ProofContainer with 0.18.0
+fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withHelpOnFailureBasedOnDefinedSubject(
+    expect: Expect<T>,
+    failureHintFactory: (T) -> Assertion
+): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> {
+    return withHelpOnFailureBasedOnSubject(expect) {
+        ifDefined(failureHintFactory)
+            .ifAbsent {
+                assertionBuilder.explanatoryGroup
+                    .withWarningType
+                    .withExplanatoryAssertion(Text(SHOULD_NOT_BE_SHOWN_TO_THE_USER_BUG))
+                    .build()
+            }
+    }.showOnlyIfSubjectDefined(expect)
+}
+
+/**
+ * Option to create a [DescriptiveAssertion] like assertion with an additional hint
+ * which is based on the subject of the expectation and
+ * which is only shown the subject is defined.
+ *
+ * You can use [withHelpOnFailureBasedOnSubject] in case you want to:
+ * - provide a hint also if the subject is absent.
+ * - do not show the hint in certain cases even if the subject is defined
+ *
+ * Or use [withHelpOnFailure] which does not expect a [subjectProvider] in case your [DescriptiveAssertion] is not based
+ * on the subject of the expectation.
+ */
+//TODO if we introduce Record or something else as replacement for Assertion then not but if we keep Assertion
+// then move to logic and expect ProofContainer with 0.18.0
+@Deprecated("Use withHelpOnFailureBasedOnDefinedSubject; will be removed with 1.0.0")
 fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withFailureHintBasedOnDefinedSubject(
     expect: Expect<T>,
     failureHintFactory: (T) -> Assertion
 ): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> {
-    return withFailureHintBasedOnSubject(expect) {
+    return withHelpOnFailureBasedOnSubject(expect) {
         ifDefined(failureHintFactory)
             .ifAbsent {
                 assertionBuilder.explanatoryGroup
@@ -56,13 +99,33 @@ fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withFailureHintBase
  * (which is based on the subject of the expectation)
  * which might be shown if the [Descriptive.DescriptionOption.test] fails.
  *
- * You can use [withFailureHint] which does not expect a [expect] in case your [DescriptiveAssertion] is not based
+ * You can use [withHelpOnFailure] which does not expect a [expect] in case your [DescriptiveAssertion] is not based
  * on the subject of the expectation.
  */
+fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withHelpOnFailureBasedOnSubject(
+    expect: Expect<T>,
+    failureHintSubStep: DescriptiveAssertionWithFailureHint.FailureHintSubjectDefinedOption<T>.() -> Pair<() -> Assertion, (T) -> Assertion>
+): DescriptiveAssertionWithFailureHint.ShowOption = withHelpOnFailure {
+    SubjectBasedOption(
+        expect,
+        failureHintSubStep,
+        DescriptiveAssertionWithFailureHint.FailureHintSubjectDefinedOption.Companion::create
+    )
+}
+
+/**
+ * Option to create a [DescriptiveAssertion] like assertion with an additional hint
+ * (which is based on the subject of the expectation)
+ * which might be shown if the [Descriptive.DescriptionOption.test] fails.
+ *
+ * You can use [withHelpOnFailure] which does not expect a [expect] in case your [DescriptiveAssertion] is not based
+ * on the subject of the expectation.
+ */
+@Deprecated("Use withHelpOnFailureBasedOnSubject; will be removed with 1.0.0")
 fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withFailureHintBasedOnSubject(
     expect: Expect<T>,
     failureHintSubStep: DescriptiveAssertionWithFailureHint.FailureHintSubjectDefinedOption<T>.() -> Pair<() -> Assertion, (T) -> Assertion>
-): DescriptiveAssertionWithFailureHint.ShowOption = withFailureHint {
+): DescriptiveAssertionWithFailureHint.ShowOption = withHelpOnFailure {
     SubjectBasedOption(
         expect,
         failureHintSubStep,

core/atrium-core-common/src/main/kotlin/ch/tutteli/atrium/creating/impl/CollectingExpectImpl.kt

@@ -40,7 +40,7 @@ internal class CollectingExpectImpl<T>(
         } else {
             allAssertions.add(assertionBuilder.descriptive
                 .failing
-                .withFailureHint {
+                .withHelpOnFailure {
                     assertionBuilder.explanatoryGroup
                         .withDefaultType
                         .withAssertions(

core/atrium-core-common/src/test/kotlin/ch/tutteli/atrium/assertions/builders/DescriptiveWithBasedOnSubjectSpec.kt

@@ -20,17 +20,17 @@ class DescriptiveWithBasedOnSubjectSpec : Spek({
                 .withDescriptionAndRepresentation("what ever", 1)
                 .build()
         },
-        "withFailureHintBasedOnDefinedSubject" to addDescriptive { expect, builder ->
+        "withHelpOnFailureBasedOnDefinedSubject" to addDescriptive { expect, builder ->
             builder.failing
-                .withFailureHintBasedOnDefinedSubject(expect) {
+                .withHelpOnFailureBasedOnDefinedSubject(expect) {
                     assertionBuilder.explanatory.withExplanation("asdf").build()
                 }
                 .withDescriptionAndRepresentation("what ever", 1)
                 .build()
         },
-        "withFailureHintBasedOnSubject" to addDescriptive { expect, builder ->
+        "withHelpOnFailureBasedOnSubject" to addDescriptive { expect, builder ->
             builder.failing
-                .withFailureHintBasedOnSubject(expect) {
+                .withHelpOnFailureBasedOnSubject(expect) {
                     ifDefined {
                         assertionBuilder.explanatory.withExplanation("asdf").build()
                     } ifAbsent {
@@ -43,7 +43,7 @@ class DescriptiveWithBasedOnSubjectSpec : Spek({
         },
         "showOnlyIf" to addDescriptive { expect, builder ->
             builder.failing
-                .withFailureHint { assertionBuilder.explanatory.withExplanation("any hint").build() }
+                .withHelpOnFailure { assertionBuilder.explanatory.withExplanation("any hint").build() }
                 .showBasedOnSubjectOnlyIf(expect) {
                     ifDefined {
                         it < 3
@@ -54,14 +54,14 @@ class DescriptiveWithBasedOnSubjectSpec : Spek({
         },
         "showOnlyIfSubjectDefined" to addDescriptive { expect, builder ->
             builder.failing
-                .withFailureHint { assertionBuilder.explanatory.withExplanation("any hint").build() }
+                .withHelpOnFailure { assertionBuilder.explanatory.withExplanation("any hint").build() }
                 .showOnlyIfSubjectDefined(expect)
                 .withDescriptionAndRepresentation("what ever", 1)
                 .build()
         },
         "showBasedOnDefinedSubjectOnlyIf" to addDescriptive { expect, builder ->
             builder.failing
-                .withFailureHint { assertionBuilder.explanatory.withExplanation("any hint").build() }
+                .withHelpOnFailure { assertionBuilder.explanatory.withExplanation("any hint").build() }
                 .showBasedOnDefinedSubjectOnlyIf(expect) { it < 3 }
                 .withDescriptionAndRepresentation("what ever", 1)
                 .build()

logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultFloatingPointAssertions.kt

@@ -3,7 +3,7 @@ package ch.tutteli.atrium.logic.impl
 import ch.tutteli.atrium.assertions.Assertion
 import ch.tutteli.atrium.assertions.ExplanatoryAssertion
 import ch.tutteli.atrium.assertions.builders.assertionBuilder
-import ch.tutteli.atrium.assertions.builders.withFailureHintBasedOnDefinedSubject
+import ch.tutteli.atrium.assertions.builders.withHelpOnFailureBasedOnDefinedSubject
 import ch.tutteli.atrium.core.polyfills.formatFloatingPointNumber
 import ch.tutteli.atrium.core.polyfills.fullName
 import ch.tutteli.atrium.creating.AssertionContainer
@@ -74,7 +74,7 @@ internal fun <T : Comparable<T>> toBeWithErrorTolerance(
 ): Assertion =
     assertionBuilder.descriptive
     .withTest(container.toExpect()) { absDiff(it) <= tolerance }
-    .withFailureHintBasedOnDefinedSubject(container.toExpect()) { subject ->
+    .withHelpOnFailureBasedOnDefinedSubject(container.toExpect()) { subject ->
         //TODO 0.18.0 that's not nice in case we use it in an Iterable contains assertion, for instance contains...entry { toBeWithErrorTolerance(x, 0.01) }
         //we do not want to see the failure nor the exact check in the 'an entry which...' part
         //same problematic applies to feature assertions within an identification lambda

logic/atrium-logic-common/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultIterableLikeAssertions.kt

@@ -134,7 +134,7 @@ class DefaultIterableLikeAssertions : IterableLikeAssertions {
                 val (element, indices) = pair
                 assertionBuilder.descriptive
                     .failing
-                    .withFailureHint {
+                    .withHelpOnFailure {
                         assertionBuilder.explanatoryGroup
                             .withDefaultType
                             .withExplanatoryAssertion(

logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/creating/filesystem/hints/hints.kt

@@ -22,21 +22,46 @@ import java.nio.file.Path
 import java.nio.file.attribute.*
 import java.util.*
 
-inline fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withIOExceptionFailureHint(
+inline fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withHelpOnIOExceptionFailure(
     expect: Expect<IoResult<T>>,
     crossinline f: (Path, IOException) -> Assertion?
 ): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> =
-    withFailureHintBasedOnDefinedSubject(expect) { result ->
+    withHelpOnFailureBasedOnDefinedSubject(expect) { result ->
         explainForResolvedLink(result.path) { realPath ->
             val exception = (result as Failure).exception
             f(realPath, exception) ?: hintForIoException(realPath, exception)
         }
     }
 
+@Deprecated("Use withHelpOnIOExceptionFailure; will be removed with 1.0.0")
+inline fun <T> Descriptive.DescriptionOption<Descriptive.FinalStep>.withIOExceptionFailureHint(
+    expect: Expect<IoResult<T>>,
+    crossinline f: (Path, IOException) -> Assertion?
+): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> =
+    withHelpOnFailureBasedOnDefinedSubject(expect) { result ->
+        explainForResolvedLink(result.path) { realPath ->
+            val exception = (result as Failure).exception
+            f(realPath, exception) ?: hintForIoException(realPath, exception)
+        }
+    }
+
+fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withHelpOnFileAttributesFailure(
+    expect: Expect<IoResult<BasicFileAttributes>>
+): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> =
+    withHelpOnFailureBasedOnDefinedSubject(expect) { result ->
+        explainForResolvedLink(result.path) { realPath ->
+            when (result) {
+                is Success -> describeWas(result.value.fileType)
+                is Failure -> hintForIoException(realPath, result.exception)
+            }
+        }
+    }
+
+@Deprecated("Use withHelpOnFileAttributesFailure; will be removed with 1.0.0")
 fun Descriptive.DescriptionOption<Descriptive.FinalStep>.withFileAttributesFailureHint(
     expect: Expect<IoResult<BasicFileAttributes>>
 ): Descriptive.DescriptionOption<DescriptiveAssertionWithFailureHint.FinalStep> =
-    withFailureHintBasedOnDefinedSubject(expect) { result ->
+    withHelpOnFailureBasedOnDefinedSubject(expect) { result ->
         explainForResolvedLink(result.path) { realPath ->
             when (result) {
                 is Success -> describeWas(result.value.fileType)

logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultBigDecimalAssertions.kt

@@ -8,7 +8,7 @@ package ch.tutteli.atrium.logic.impl
 import ch.tutteli.atrium.assertions.Assertion
 import ch.tutteli.atrium.assertions.builders.assertionBuilder
 import ch.tutteli.atrium.assertions.builders.withExplanatoryAssertion
-import ch.tutteli.atrium.assertions.builders.withFailureHint
+import ch.tutteli.atrium.assertions.builders.withHelpOnFailure
 import ch.tutteli.atrium.creating.AssertionContainer
 import ch.tutteli.atrium.logic.BigDecimalAssertions
 import ch.tutteli.atrium.logic.createDescriptiveAssertion
@@ -37,7 +37,7 @@ class DefaultBigDecimalAssertions : BigDecimalAssertions {
     ): Assertion =
         assertionBuilder.descriptive
             .withTest(container.toExpect()) { it == expected }
-            .withFailureHint {
+            .withHelpOnFailure {
                 assertionBuilder.explanatoryGroup
                     .withInformationType(withIndent = true)
                     .withExplanatoryAssertion(

logic/atrium-logic-jvm/src/main/kotlin/ch/tutteli/atrium/logic/impl/DefaultPathAssertions.kt

@@ -8,7 +8,7 @@ package ch.tutteli.atrium.logic.impl
 import ch.tutteli.atrium.assertions.Assertion
 import ch.tutteli.atrium.assertions.builders.assertionBuilder
 import ch.tutteli.atrium.assertions.builders.invisibleGroup
-import ch.tutteli.atrium.assertions.builders.withFailureHintBasedOnDefinedSubject
+import ch.tutteli.atrium.assertions.builders.withHelpOnFailureBasedOnDefinedSubject
 import ch.tutteli.atrium.core.None
 import ch.tutteli.atrium.core.Some
 import ch.tutteli.atrium.creating.AssertionContainer
@@ -63,7 +63,7 @@ class DefaultPathAssertions : PathAssertions {
         changeSubjectToFileAttributes(container, linkOption) { fileAttributesExpect ->
             assertionBuilder.descriptive
                 .withTest(fileAttributesExpect) { it is Success }
-                .withIOExceptionFailureHint(fileAttributesExpect) { realPath, exception ->
+                .withHelpOnIOExceptionFailure(fileAttributesExpect) { realPath, exception ->
                     when (exception) {
                         // TODO remove group once https://github.com/robstoll/atrium-roadmap/issues/1 is implemented
                         is NoSuchFileException -> assertionBuilder.explanatoryGroup
@@ -82,7 +82,7 @@ class DefaultPathAssertions : PathAssertions {
         changeSubjectToFileAttributes(container, linkOption) { fileAttributesExpect ->
             assertionBuilder.descriptive
                 .withTest(fileAttributesExpect) { it is Failure && it.exception is NoSuchFileException }
-                .withFileAttributesFailureHint(fileAttributesExpect)
+                .withHelpOnFileAttributesFailure(fileAttributesExpect)
                 .withDescriptionAndRepresentation(DescriptionBasic.NOT_TO, EXIST)
                 .build()
         }
@@ -130,7 +130,7 @@ class DefaultPathAssertions : PathAssertions {
     }.let { checkAccessResultExpect ->
         assertionBuilder.descriptive
             .withTest(checkAccessResultExpect) { it is Success }
-            .withIOExceptionFailureHint(checkAccessResultExpect) { realPath, exception ->
+            .withHelpOnIOExceptionFailure(checkAccessResultExpect) { realPath, exception ->
                 when (exception) {
                     is AccessDeniedException -> findHintForProblemWithParent(realPath)
                         ?: assertionBuilder.explanatoryGroup
@@ -155,7 +155,7 @@ class DefaultPathAssertions : PathAssertions {
     ) = changeSubjectToFileAttributes(container, linkOption) { fileAttributesExpect ->
         assertionBuilder.descriptive
             .withTest(fileAttributesExpect) { it is Success && typeTest(it.value) }
-            .withFileAttributesFailureHint(fileAttributesExpect)
+            .withHelpOnFileAttributesFailure(fileAttributesExpect)
             .withDescriptionAndRepresentation(DescriptionBasic.IS, typeName)
             .build()
     }
@@ -204,7 +204,7 @@ class DefaultPathAssertions : PathAssertions {
             }.let { expectResult ->
                 assertionBuilder.descriptive
                     .withTest(expectResult) { it is Success && it.value.isEmpty() }
-                    .withFailureHintBasedOnDefinedSubject(expectResult) { ioResult ->
+                    .withHelpOnFailureBasedOnDefinedSubject(expectResult) { ioResult ->
                         explainForResolvedLink(ioResult.path) { realPath ->
                             when (ioResult) {
                                 is Success -> {