javadoc improvements

all javadoc warnings fixed
xyzsd · Dec 18, 2023 · 5367bc0 · 5367bc0
1 parent 54097a1
commit 5367bc0
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 10 deletions.
diff --git a/src/main/java/net/xyzsd/dichotomy/Either.java b/src/main/java/net/xyzsd/dichotomy/Either.java
@@ -79,24 +79,28 @@ static <L, R> Either<L, R> ofRight(@NotNull R value) {
 
     /**
      * Returns {@code true} is this is a {@link Left} {@link Either}.
+     * @return true if this is a Left Either.
      */
     boolean isLeft();
 
     /**
      * Returns {@code true} is this is a {@link Right} {@link Either}.
+     * @return true if this is a Right Either.
      */
     boolean isRight();
 
 
     /**
      * If the {@link Either} is {@link Left}, return the value as an {@link Optional}.
      * Otherwise, return an empty {@link Optional}.
+     * @return Left value or Optional.Empty if this is Right
      */
     @NotNull Optional<L> left();
 
     /**
      * If the {@link Either} is {@link Right}, return the value as an {@link Optional}.
      * Otherwise, return an empty {@link Optional}.
+     * @return Right value or Optional.Empty if this is Left
      */
     @NotNull Optional<R> right();
 
@@ -245,6 +249,7 @@ static <L, R> Either<L, R> ofRight(@NotNull R value) {
      * if this is a {@link Right value}.
      *
      * @see #stream()
+     * @return Stream
      */
     @NotNull Stream<L> streamLeft();
 
@@ -484,6 +489,7 @@ default void consume(@NotNull Consumer<? super R> rightConsumer) {
      * @see #and(Supplier)
      * @see #or(Either)
      * @see #or(Supplier)
+     * @return this or nextEither
      */
     @NotNull <R2> Either<L, R2> and(@NotNull Either<L, R2> nextEither);
 
@@ -498,6 +504,7 @@ default void consume(@NotNull Consumer<? super R> rightConsumer) {
      * @see #and(Either)
      * @see #or(Either)
      * @see #or(Supplier)
+     * @return this or nextEither
      */
     @NotNull <R2> Either<L, R2> and(@NotNull Supplier<Either<L, R2>> nextEitherSupplier);
 
@@ -512,6 +519,7 @@ default void consume(@NotNull Consumer<? super R> rightConsumer) {
      * @see #or(Supplier)
      * @see #and(Either)
      * @see #and(Supplier)
+     * @return this or nextEither
      */
     @NotNull <L2> Either<L2, R> or(@NotNull Either<L2, R> nextEither);
 
@@ -527,6 +535,7 @@ default void consume(@NotNull Consumer<? super R> rightConsumer) {
      * @see #or(Either)
      * @see #and(Either)
      * @see #and(Supplier)
+     * @return this or nextEither
      */
     @NotNull <L2> Either<L2, R> or(@NotNull Supplier<Either<L2, R>> nextEitherSupplier);
 
@@ -639,6 +648,7 @@ record Left<L, R>(@NotNull L value) implements Either<L, R> {
 
         /**
          * Get the value. Never null.
+         * @return value
          */
         @NotNull
         public L get() {return value;}
@@ -991,6 +1001,7 @@ record Right<L, R>(@NotNull R value) implements Either<L, R> {
 
         /**
          * Get the value. Never null.
+         * @return value
          */
         @NotNull
         public R get() {return value;}

diff --git a/src/main/java/net/xyzsd/dichotomy/Maybe.java b/src/main/java/net/xyzsd/dichotomy/Maybe.java
@@ -180,7 +180,7 @@ static <T> Maybe<T> ofNullable(@Nullable T value) {
      * If this is a {@link Some}, return it. Otherwise, use the provided alternate value.
      *
      * @param alternate used if this is {@link None}
-     * @return value
+     * @return this or the given Maybe
      */
     @NotNull T orElse(@NotNull T alternate);
 
@@ -189,7 +189,7 @@ static <T> Maybe<T> ofNullable(@Nullable T value) {
      * The Supplier is only invoked if this is a {@link None}.
      *
      * @param supplier, used if this is {@link None}
-     * @return value
+     * @return this or the supplied Maybe
      */
     @NotNull T orElse(@NotNull Supplier<? extends T> supplier);
 
@@ -199,6 +199,7 @@ static <T> Maybe<T> ofNullable(@Nullable T value) {
      *
      * @param nextMaybe if this is not a {@link None}
      * @param <U>       type of Maybe returned
+     * @return this or the given Maybe
      */
     <U> @NotNull Maybe<U> and(@NotNull Maybe<? extends U> nextMaybe);
 
@@ -208,20 +209,23 @@ static <T> Maybe<T> ofNullable(@Nullable T value) {
      *
      * @param nextMaybeSupplier invoked this is not a {@link None}
      * @param <U>               type of Maybe returned
+     * @return this or the supplied Maybe
      */
     <U> @NotNull Maybe<U> and(@NotNull Supplier<Maybe<? extends U>> nextMaybeSupplier);
 
     /**
      * If this is a {@link Some}, return it. Otherwise, return {@code nextMaybe}.
      *
-     * @param nextMaybe (returned if this is a {@link None}
+     * @param nextMaybe the next Maybe
+     * @return nextMaybe (returned if this is a {@link None}
      */
     @NotNull Maybe<T> or(@NotNull Maybe<T> nextMaybe);
 
     /**
      * If this is a {@link Some}, return it. Otherwise, return the maybe via the provided {@link Supplier}.
      *
-     * @param nextMaybeSupplier (invoked if this is a {@link None}
+     * @param nextMaybeSupplier supplier of the next Maybe
+     * @return  nextMaybeSupplier (invoked if this is a {@link None}
      */
     @NotNull Maybe<T> or(@NotNull Supplier<Maybe<T>> nextMaybeSupplier);
 
@@ -237,6 +241,9 @@ static <T> Maybe<T> ofNullable(@Nullable T value) {
      * Get the value, if this is a {@link Some}; otherwise, throw an exception via the provided {@link Supplier}.
      *
      * @return value
+     * @param <X>  Exception to throw; if not a (subclass of) RuntimeException, it must be rethrown or caught
+     * @param supplier Supplier of exceptions to throw
+     * @throws X Exception to throw
      */
     @NotNull <X extends Throwable> T getOrThrow(@NotNull Supplier<X> supplier) throws X;
 

diff --git a/src/main/java/net/xyzsd/dichotomy/Result.java b/src/main/java/net/xyzsd/dichotomy/Result.java
@@ -118,7 +118,8 @@ static <E> Result<Empty, E> ofOK() {
      *         }
      *     </pre>
      *
-     * @param <V> Value, which may be null
+     * @param <V> Value type
+     * @param value given value, which may be null
      * @return A result containing {@code OK<None>} or {@code Err<E>}.
      */
     @NotNull
@@ -137,15 +138,14 @@ static <V> Result<V, Empty> ofNullable(@Nullable V value) {
      * <p>
      *     If the opposite behavior is desired ({@code null} is successful, and
      *     non-{@code null} values are failure) use {@link #swap()}, as follows:
-     *     <pre>
-     *         {@code
+     *     {@snippet :
      *              // Lets say RuntimeException is the error type
      *              Optional<RuntimeException> myValue = someFunction();
      *              Result<None, RuntimeException> result = Result.ofOK(myValue).swap();
-     *         }
-     *     </pre>
+     *     }
      *
      * @param <V> Value type
+     * @param opt the Optional from which we create the Result
      * @return A result containing {@code OK<V>} or {@code Err<None>}.
      * @see #ofNullable(Object)
      */
@@ -171,11 +171,13 @@ static <V, E> Result<V, E> ofErr(@NotNull E error) {
 
     /**
      * If this is an {@link OK}, return {@code true}.
+     * @return true if this is an OK result.
      */
     boolean isOK();
 
     /**
      * If this is an {@link Err}, return {@code true}.
+     * @return true if this is an error result.
      */
     boolean isErr();
 
@@ -211,6 +213,8 @@ static <V, E> Result<V, E> ofErr(@NotNull E error) {
      * @throws NullPointerException if the called action returns {@code null}.
      * @see #match(Consumer)
      * @see #matchErr(Consumer)
+     * @param okConsumer Consumer of OK values
+     * @param errConsumer Consumer of Err values
      */
     @NotNull Result<V, E> biMatch(@NotNull Consumer<? super V> okConsumer, @NotNull Consumer<? super E> errConsumer);
 
@@ -273,6 +277,7 @@ static <V, E> Result<V, E> ofErr(@NotNull E error) {
      * if this is an {@link Err} value.
      *
      * @see #streamErr()
+     * @return Stream
      */
     @NotNull Stream<V> stream();
 
@@ -302,7 +307,8 @@ static <V, E> Result<V, E> ofErr(@NotNull E error) {
      * @throws NullPointerException if the called action returns {@code null}.
      * @see #match(Consumer)
      * @see #biMatch(Consumer, Consumer)
-     */
+     * @param okConsumer Consumer of OK values
+     * */
     @NotNull Result<V, E> match(@NotNull Consumer<? super V> okConsumer);
 
 
@@ -433,6 +439,7 @@ default void consume(@NotNull Consumer<? super V> okConsumer) {
      * if this is an {@link OK} value.
      *
      * @see #stream()
+     * @return Stream
      */
     @NotNull Stream<E> streamErr();
 
@@ -443,6 +450,7 @@ default void consume(@NotNull Consumer<? super V> okConsumer) {
      * @throws NullPointerException if the called action returns {@code null}.
      * @see #match(Consumer)
      * @see #biMatch(Consumer, Consumer)
+     * @param errConsumer Consumer of Err values
      */
     @NotNull Result<V, E> matchErr(@NotNull Consumer<? super E> errConsumer);
 
@@ -582,6 +590,7 @@ default void consume(@NotNull Consumer<? super V> okConsumer) {
      * @see #and(Supplier)
      * @see #or(Result)
      * @see #or(Supplier)
+     * @return this or the given Result
      */
     @NotNull <V2> Result<V2, E> and(@NotNull Result<V2, E> nextResult);
 
@@ -596,6 +605,7 @@ default void consume(@NotNull Consumer<? super V> okConsumer) {
      * @see #and(Result)
      * @see #or(Result)
      * @see #or(Supplier)
+     * @return this or the supplied Result
      */
     @NotNull <V2> Result<V2, E> and(@NotNull Supplier<Result<V2, E>> nextResultSupplier);
 
@@ -610,6 +620,7 @@ default void consume(@NotNull Consumer<? super V> okConsumer) {
      * @see #or(Supplier)
      * @see #and(Result)
      * @see #and(Supplier)
+     * @return this or the given Result
      */
     @NotNull <E2> Result<V, E2> or(@NotNull Result<V, E2> nextResult);
 
@@ -625,6 +636,7 @@ default void consume(@NotNull Consumer<? super V> okConsumer) {
      * @see #or(Result)
      * @see #and(Result)
      * @see #and(Supplier)
+     * @return this or the supplied Result
      */
     @NotNull <E2> Result<V, E2> or(@NotNull Supplier<Result<V, E2>> nextResultSupplier);