/*
 * Copyright (c) 2016 Google, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.google.common.truth;

import static com.google.common.truth.Truth.assertAbout;

import com.google.common.annotations.GwtIncompatible;
import java.nio.file.Path;
import java.util.Optional;
import java.util.OptionalDouble;
import java.util.OptionalInt;
import java.util.OptionalLong;
import java.util.stream.IntStream;
import java.util.stream.LongStream;
import java.util.stream.Stream;
import org.checkerframework.checker.nullness.compatqual.NullableDecl;

/**
 * A set of static methods to begin a Truth assertion chain for types that require java8.
 *
 * <p>Note: Usage of different failure strategies such as <em>assume</em> and <em>expect</em> should
 * rely on {@link
 * com.google.common.truth.StandardSubjectBuilder#about(com.google.common.truth.Subject.Factory)} to
 * begin a chain with those alternative behaviors.
 */
public final class Truth8 {
  public static OptionalSubject assertThat(@NullableDecl Optional<?> target) {
    return assertAbout(OptionalSubject.optionals()).that(target);
  }

  public static OptionalIntSubject assertThat(@NullableDecl OptionalInt target) {
    return assertAbout(OptionalIntSubject.optionalInts()).that(target);
  }

  public static OptionalLongSubject assertThat(@NullableDecl OptionalLong target) {
    return assertAbout(OptionalLongSubject.optionalLongs()).that(target);
  }

  public static OptionalDoubleSubject assertThat(@NullableDecl OptionalDouble target) {
    return assertAbout(OptionalDoubleSubject.optionalDoubles()).that(target);
  }

  public static StreamSubject assertThat(@NullableDecl Stream<?> target) {
    return assertAbout(StreamSubject.streams()).that(target);
  }

  public static IntStreamSubject assertThat(@NullableDecl IntStream target) {
    return assertAbout(IntStreamSubject.intStreams()).that(target);
  }

  public static LongStreamSubject assertThat(@NullableDecl LongStream target) {
    return assertAbout(LongStreamSubject.longStreams()).that(target);
  }

  // TODO(b/64757353): Add support for DoubleStream?

  // Not actually a Java 8 feature, but for now this is the best option since core Truth still has
  // to support Java environments without java.nio.file such as Android and J2CL.
  @GwtIncompatible
  public static PathSubject assertThat(@NullableDecl Path target) {
    return assertAbout(PathSubject.paths()).that(target);
  }

  private Truth8() {}
}

@@ -1068,367 +1068,699 @@
 %0A * 
-A set of static methods to begin a Truth assertion chain for types that require java8.%0A *%0A * %3Cp%3ENote: Usage of different failure strategies such as %3Cem%3Eassume%3C/em%3E and %3Cem%3Eexpect%3C/em%3E should%0A * rely on %7B@link%0A * com.google.common.truth.StandardSubjectBuilder#
+The primary entry point for assertions about Java 8 types.%0A *%0A * %3Cp%3ETo use %7B@link Truth#assertWithMessage%7D with a Java 8 type, use %7B@code%0A * assertWithMessage(...).about(%7D%7B@link OptionalSubject#optionals optionals()%7D%7B@code ).that(...)%7D%0A * (or similarly for the other types).%0A *%0A * %3Cp%3ELikewise, to use different failure strategies like %7B@link Expect%7D, use %7B@code%0A * expect.about(%7D%7B@link OptionalSubject#optionals optionals()%7D%7B@code ).that(...)%7D.%0A *%0A * %3Cp%3EFor more information 
 about
-(com.google.common.truth.Subject.Factory)%7D to%0A * begin a chain with those alternative behaviors
+ combining different messages, failure strategies, and subjects, see%0A * %3Ca href=%22https://truth.dev/faq#full-chain%22%3EHow do I specify a custom message/failure%0A * behavior/%7B@code Subject%7D type?%3C/a%3E in the Truth FAQ
 .%0A *

Document how to combine assertWithMessage with the Java 8 subjects.