Javadoc cleanup (#420)

* Move all package docs into package-info.java
* Ensure tutorial examples fit in line
* Remove broken links from related projects
* Suppress warnings about Java 8
* Exclude `org.hamcrest.internal` package from javadoc
* Add javadoc overview, with basic example code
* Add missing javadoc and fix javadoc warnings

CHANGES.md

@@ -4,7 +4,7 @@
 
 ### Improvements
 
-* TBD
+* Javadoc improvements and cleanup ([PR #420](https://github.com/hamcrest/JavaHamcrest/pull/420))
 
 ### Bugfixes
 

build.gradle

@@ -66,6 +66,12 @@ subprojects {
     }
 }
 
+allprojects {
+    tasks.withType(JavaCompile) {
+        options.compilerArgs << '-Xlint:-options'
+    }
+}
+
 def pomConfigurationFor(String pomName, String pomDescription) {
     return {
         name = pomName

docs/related.md

@@ -9,10 +9,8 @@ layout: default
 Here are some projects that provide additional features and matchers
 
 * [Awaitility](https://github.com/jayway/awaitility) (a DSL that allows you to express expectations of an asynchronous system in a concise and easy to read manner)
-* [EZ Testing](https://github.com/EZGames/ez-testing) (contains base classes for defining chainable matchers that have a similar style to AssertJ)
 * [Hamcrest 1.3 Utility Matchers](https://github.com/NitorCreations/matchers) (Java matchers like CollectionMatchers, MapMatchers, FieldMatcher, SerializableMatcher etc)
 * [Hamcrest auto matcher](https://github.com/itsallcode/hamcrest-auto-matcher) (uses reflection to automatically match model classes)
-* [Hamcrest avro](https://github.com/Byhiras/avro-utils)
 * [Hamcrest Composites](https://github.com/Cornutum/hamcrest-composites) (for comparing complex Java objects with better testability)
 * [Hamcrest Date](https://github.com/modularit/hamcrest-date) (for comparing dates)
 * [Hamcrest HAR](https://github.com/roydekleijn/har-assert) (for HTTP archive files)

docs/tutorial.md

@@ -34,9 +34,11 @@ The `assertThat` method is a stylized sentence for making a test assertion. In t
 If you have more than one assertion in your test you can include an identifier for the tested value in the assertion:
 
 ```java
-assertThat("chocolate chips", theBiscuit.getChocolateChipCount(), equalTo(10)); 
+assertThat("chocolate chips",
+           theBiscuit.getChocolateChipCount(), equalTo(10));
 
-assertThat("hazelnuts", theBiscuit.getHazelnutCount(), equalTo(3));
+assertThat("hazelnuts",
+           theBiscuit.getHazelnutCount(), equalTo(3));
 ```
 
 ### Other test frameworks
@@ -122,7 +124,7 @@ public void testSquareRootOfMinusOneIsNotANumber() {
 And here's the implementation:
 
 ```java 
-package org.hamcrest.examples.tutorial;
+package org.hamcrest.examples;
 
 import org.hamcrest.Description; 
 import org.hamcrest.Matcher; 
@@ -162,7 +164,7 @@ The third method in our matcher is a convenience factory method. We statically i
 import org.junit.jupiter.api.Test;
 import static org.hamcrest.MatcherAssert.assertThat; 
 import static org.hamcrest.Matchers.*;
-import static org.hamcrest.examples.tutorial.IsNotANumber.notANumber;
+import static org.hamcrest.examples.IsNotANumber.notANumber;
 
 public class NumberTest {
   @Test

hamcrest-core/src/main/java/org/hamcrest/core/deprecated/HamcrestCoreIsDeprecated.java

@@ -6,4 +6,9 @@
  */
 @Deprecated
 class HamcrestCoreIsDeprecated {
+    /**
+     * Unused
+     */
+    private HamcrestCoreIsDeprecated() {
+    }
 }

hamcrest-library/src/main/java/org/hamcrest/library/deprecated/HamcrestLibraryIsDeprecated.java

@@ -6,4 +6,9 @@
  */
 @Deprecated
 class HamcrestLibraryIsDeprecated {
+    /**
+     * Unused
+     */
+    private HamcrestLibraryIsDeprecated() {
+    }
 }

hamcrest/hamcrest.gradle

@@ -33,4 +33,8 @@ jar {
     }
 }
 
-javadoc.title = "Hamcrest ${version} API"
+javadoc {
+    title = "Hamcrest ${version} API"
+    exclude "org/hamcrest/internal/*"
+    options.overview = file("javadoc-overview.html")
+}

hamcrest/javadoc-overview.html

@@ -0,0 +1,31 @@
+<!DOCTYPE HTML>
+<html lang="en">
+<head>
+    <title>Hamcrest Overview</title>
+</head>
+<body>
+<p>Matchers that can be combined to create flexible expressions of intent.</p>
+<p>For example:</p>
+<pre style="border: 1px solid #ccc; margin: 0; padding: 0.5em;"><code>import org.junit.jupiter.api.Test;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.*;
+
+public class BiscuitTest {
+  &#64;Test
+  public void testEquals() {
+    Biscuit theBiscuit = new Biscuit("Ginger");
+    Biscuit myBiscuit = new Biscuit("Ginger");
+    assertThat(theBiscuit, equalTo(myBiscuit));
+  }
+}
+</code></pre>
+
+<p>For more information and documentation, see:</p>
+<ul>
+    <li>The <a href="https://hamcrest.org/JavaHamcrest/tutorial" target="_top">Getting Started</a> tutorial</li>
+    <li>The <a href="https://github.com/hamcrest/JavaHamcrest" target="_top">source code on GitHub</a></li>
+</ul>
+
+</body>
+</html>
+

hamcrest/src/main/java/org/hamcrest/BaseDescription.java

@@ -13,6 +13,12 @@
  */
 public abstract class BaseDescription implements Description {
 
+    /**
+     * Default constructor
+     */
+    public BaseDescription() {
+    }
+
     @Override
     public Description appendText(String text) {
         append(text);

hamcrest/src/main/java/org/hamcrest/BaseMatcher.java

@@ -4,8 +4,14 @@
  * BaseClass for all Matcher implementations.
  *
  * @see Matcher
+ * @param <T> The Matcher type.
  */
 public abstract class BaseMatcher<T> implements Matcher<T> {
+    /**
+     * Default constructor.
+     */
+    public BaseMatcher() {
+    }
 
     /**
      * @see Matcher#_dont_implement_Matcher___instead_extend_BaseMatcher_()

hamcrest/src/main/java/org/hamcrest/Condition.java

@@ -3,33 +3,83 @@
 /**
  * A Condition implements part of a multi-step match. We sometimes need to write matchers
  * that have a sequence of steps, where each step depends on the result of the previous
- * step and we can stop processing as soon as a step fails. These classes provide
+ * step, and we can stop processing as soon as a step fails. These classes provide
  * infrastructure for writing such a sequence.
  *
- * Based on https://github.com/npryce/maybe-java
+ * <p>Based on Nat Pryce's <a href="https://github.com/npryce/maybe-java">maybe-java</a>.
+ * </p>
+ *
+ * @param <T> the matched value type
  * @author Steve Freeman 2012 http://www.hamcrest.com
  */
 public abstract class Condition<T> {
 
-    public static final NotMatched<Object> NOT_MATCHED = new NotMatched<>();
-
+    /**
+     * Represents a single step in a multi-step sequence
+     * @param <I> the initial value type
+     * @param <O> the next step value type
+     */
     public interface Step<I, O> {
+        /**
+         * Apply this condition to a value
+         * @param value the value to match
+         * @param mismatch the description for mismatches
+         * @return the next condition
+         */
         Condition<O> apply(I value, Description mismatch);
     }
 
     private Condition() { }
 
+    /**
+     * Applies the matcher as the final step in the sequence
+     * @param match the value matcher
+     * @param message a description of the value
+     * @return true if the matcher matches the value, otherwise false
+     */
     public abstract boolean matching(Matcher<T> match, String message);
-    public abstract <U> Condition<U> and(Step<? super T, U> mapping);
 
+    /**
+     * Applies the matcher as the final step in the sequence
+     * @param match the value matcher
+     * @return true if the matcher matches the value, otherwise false
+     */
     public final boolean matching(Matcher<T> match) { return matching(match, ""); }
+
+    /**
+     * Applies the mapping to the current value in the sequence
+     * @param mapping the current step in the sequence
+     * @return the condition for the next step in the sequence
+     * @param <U> the type of the next value
+     */
+    public abstract <U> Condition<U> and(Step<? super T, U> mapping);
+
+    /**
+     * An alias for {@link #and(Step)}, which applies the mapping to the current value in the
+     * sequence.
+     * @param mapping the current step in the sequence
+     * @return the condition for the next step in the sequence
+     * @param <U> the type of the next value
+     */
     public final <U> Condition<U> then(Step<? super T, U> mapping) { return and(mapping); }
 
+    /**
+     * Called by steps when a mismatch occurs.
+     * @return a condition in the not matched state
+     * @param <T> the type of the unmatched value
+     */
     @SuppressWarnings("unchecked")
     public static <T> Condition<T> notMatched() {
-        return (Condition<T>) NOT_MATCHED;
+        return (Condition<T>) NotMatched.NOT_MATCHED;
     }
 
+    /**
+     * Called by steps when a match occurs
+     * @param theValue the value that was matched
+     * @param mismatch a description for potential future mismatches
+     * @return the condition in a matched state
+     * @param <T> the type of the matched value
+     */
     public static <T> Condition<T> matched(final T theValue, final Description mismatch) {
         return new Matched<>(theValue, mismatch);
     }
@@ -60,6 +110,8 @@ public <U> Condition<U> and(Step<? super T, U> next) {
     }
 
     private static final class NotMatched<T> extends Condition<T> {
+        public static final NotMatched<Object> NOT_MATCHED = new NotMatched<>();
+
         @Override public boolean matching(Matcher<T> match, String message) { return false; }
 
         @Override public <U> Condition<U> and(Step<? super T, U> mapping) {