Add simple examples to Javadoc

[danieldietrich]

This is an ongoing issue. I would love to see contributions in form of several small PRs that successively add examples to our Javadoc.

The Javadoc should have the following general structure:

/**
 * <text text text>
 *
+* <pre>{@code
+* <example(s)>
+* }</pre>
 *
 * <@annotations>
 */

Example:

/**
    * Consumes the cause if this is a {@link Try.Failure} and the cause is instance of the given {@code exceptionType}.
    *
    * <pre>{@code
    * // (does not print anything)
    * Try.success(1).onFailure(Error.class, System.out::println);
    *
    * // prints "java.lang.Error"
    * Try.failure(new Error()).onFailure(Error.class, System.out::println);
    *
    * // (does not print anything)
    * Try.failure(new Exception()).onFailure(Error.class, System.out::println);
    * }</pre>
    *
    * @param <X>           Exception type
    * @param exceptionType The specific exception type that should be handled
    * @param action        An exception consumer
    * @return this
    * @throws NullPointerException if one of {@code exceptionType} or {@code action} is null
    */
public <X extends Throwable> Try<T> onFailure(Class<X> exceptionType, Consumer<? super Throwable> action) {
    Objects.requireNonNull(exceptionType, "exceptionType is null");
    Objects.requireNonNull(action, "action is null");
    if (isFailure() && exceptionType.isInstance(getCause())) {
        action.accept(getCause());
    }
    return this;
}

Please note that src-gen/**/*.java must not be edited directly. You can either skip these classes or edit generator/Generator.sc instead. Run ./gradlew generateSources to re-generate the code, if you do so.

Please run ./gradlew check && ./gradlew javadoc before submitting your PR.

[FuncGuy]

i'm ready to take this issue but i'm confused from where to start?

[danieldietrich]

@FuncGuy Great! It is meant to be on a fine-grained basis. Just pick methods of your choice. I expect several persons will participate over time! You might do several PRs over time. Thx!

[FuncGuy]

thanks for adding me to the contributor list.

[pepijno]

Hi, I would like to contribute. Can I add examples for Option or is someone already working on this?

[thiyagu-7]

Can I work on the Value class?

Happy to work on some other class too (if you have anything specific)

[danieldietrich]

We got many contributions here the last months. I will consider this issue as finished. Documentation is an ongoing task.