[isis] branch master updated: ISIS-2297: java-doc polishing

[ah...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git


The following commit(s) were added to refs/heads/master by this push:
     new 48973d367d ISIS-2297: java-doc polishing
48973d367d is described below

commit 48973d367d9930a436f10844bb801e1e2972d9a9
Author: Andi Huber <ah...@apache.org>
AuthorDate: Wed Apr 6 20:30:34 2022 +0200

    ISIS-2297: java-doc polishing
---
 .../modules/commons/pages/index/functional/Try.adoc            | 10 ++++++----
 .../src/main/java/org/apache/isis/commons/functional/Try.java  |  7 +++++--
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/antora/components/refguide-index/modules/commons/pages/index/functional/Try.adoc b/antora/components/refguide-index/modules/commons/pages/index/functional/Try.adoc
index ba43780bbe..3ce988a4fc 100644
--- a/antora/components/refguide-index/modules/commons/pages/index/functional/Try.adoc
+++ b/antora/components/refguide-index/modules/commons/pages/index/functional/Try.adoc
@@ -5,6 +5,8 @@ The xref:refguide:commons:index/functional/Try.adoc[Try] type represents a value
 
 Factory methods _Try#success(Object)_ and _Try#failure(Throwable)_ correspond to the two possible values.
 
+Follows the *Railway Pattern* , that is, once failed, stays failed.
+
 == API
 
 [source,java]
@@ -91,12 +93,12 @@ Maps the contained _value_ or _failure_ to a new value of type _R_ using accordi
 <.> xref:#thenCall__Callable[thenCall(Callable)]
 +
 --
-If this is a _Success_ , maps it to another based on given _Callable_ . Otherwise if its a _Failure_ acts as identity operator.
+If this is a _Success_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _Callable_ . Otherwise if its a _Failure_ acts as identity operator.
 --
 <.> xref:#thenRun__ThrowingRunnable[thenRun(ThrowingRunnable)]
 +
 --
-If this is a _Success_ , maps it to another based on given _ThrowingRunnable_ . Otherwise if its a _Failure_ acts as identity operator.
+If this is a _Success_ , maps it to new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _ThrowingRunnable_ . Otherwise if its a _Failure_ acts as identity operator.
 --
 
 == Members
@@ -159,9 +161,9 @@ Maps the contained _value_ or _failure_ to a new value of type _R_ using accordi
 [#thenCall__Callable]
 === thenCall(Callable)
 
-If this is a _Success_ , maps it to another based on given _Callable_ . Otherwise if its a _Failure_ acts as identity operator.
+If this is a _Success_ , maps it to a new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _Callable_ . Otherwise if its a _Failure_ acts as identity operator.
 
 [#thenRun__ThrowingRunnable]
 === thenRun(ThrowingRunnable)
 
-If this is a _Success_ , maps it to another based on given _ThrowingRunnable_ . Otherwise if its a _Failure_ acts as identity operator.
+If this is a _Success_ , maps it to new xref:refguide:commons:index/functional/Try.adoc[Try] based on given _ThrowingRunnable_ . Otherwise if its a _Failure_ acts as identity operator.
diff --git a/commons/src/main/java/org/apache/isis/commons/functional/Try.java b/commons/src/main/java/org/apache/isis/commons/functional/Try.java
index 020625edd1..540f6beeea 100644
--- a/commons/src/main/java/org/apache/isis/commons/functional/Try.java
+++ b/commons/src/main/java/org/apache/isis/commons/functional/Try.java
@@ -40,6 +40,9 @@ import lombok.SneakyThrows;
  * <p>
  * Factory methods {@link Try#success(Object)} and {@link Try#failure(Throwable)}
  * correspond to the two possible values.
+ * <p>
+ * Follows the <em>Railway Pattern</em>, that is, once failed, stays failed.
+ * @see Railway
  *
  * @since 2.0 {@index}
  */
@@ -148,12 +151,12 @@ public interface Try<T> {
     // -- CONCATENATION
 
     /**
-     * If this is a {@link Success}, maps it to another based on given {@link Callable}.
+     * If this is a {@link Success}, maps it to a new {@link Try} based on given {@link Callable}.
      * Otherwise if its a {@link Failure} acts as identity operator.
      */
     <R> Try<R> thenCall(final @NonNull Callable<R> callable);
     /**
-     * If this is a {@link Success}, maps it to another based on given {@link ThrowingRunnable}.
+     * If this is a {@link Success}, maps it to new {@link Try} based on given {@link ThrowingRunnable}.
      * Otherwise if its a {@link Failure} acts as identity operator.
      */
     Try<Void> thenRun(final @NonNull ThrowingRunnable runnable);