From 2e7f8689b2661ecf79f86b29200fb7e263d4c5d9 Mon Sep 17 00:00:00 2001 From: Joe Schmetzer Date: Fri, 2 Aug 2024 18:02:36 +1000 Subject: [PATCH 01/11] Move all package docs into package-info.java --- hamcrest/hamcrest.gradle | 1 + hamcrest/javadoc-overview.html | 17 +++++++++++++++++ .../java/org/hamcrest/beans/package-info.java | 4 ++++ .../main/java/org/hamcrest/beans/package.html | 7 ------- .../org/hamcrest/collection/package-info.java | 4 ++++ .../java/org/hamcrest/collection/package.html | 7 ------- .../org/hamcrest/comparator/package-info.java | 4 ++++ .../java/org/hamcrest/core/package-info.java | 4 ++++ .../main/java/org/hamcrest/core/package.html | 7 ------- .../org/hamcrest/internal/package-info.java | 4 ++++ .../main/java/org/hamcrest/io/package-info.java | 4 ++++ .../java/org/hamcrest/number/package-info.java | 4 ++++ .../main/java/org/hamcrest/number/package.html | 7 ------- .../java/org/hamcrest/object/package-info.java | 4 ++++ .../main/java/org/hamcrest/object/package.html | 7 ------- .../main/java/org/hamcrest/package-info.java | 4 ++++ .../java/org/hamcrest/text/package-info.java | 4 ++++ .../main/java/org/hamcrest/text/package.html | 7 ------- .../java/org/hamcrest/xml/package-info.java | 4 ++++ .../src/main/java/org/hamcrest/xml/package.html | 7 ------- settings.gradle | 3 +-- 21 files changed, 63 insertions(+), 51 deletions(-) create mode 100644 hamcrest/javadoc-overview.html create mode 100644 hamcrest/src/main/java/org/hamcrest/beans/package-info.java delete mode 100644 hamcrest/src/main/java/org/hamcrest/beans/package.html create mode 100644 hamcrest/src/main/java/org/hamcrest/collection/package-info.java delete mode 100644 hamcrest/src/main/java/org/hamcrest/collection/package.html create mode 100644 hamcrest/src/main/java/org/hamcrest/comparator/package-info.java create mode 100644 hamcrest/src/main/java/org/hamcrest/core/package-info.java delete mode 100644 hamcrest/src/main/java/org/hamcrest/core/package.html create mode 100644 hamcrest/src/main/java/org/hamcrest/internal/package-info.java create mode 100644 hamcrest/src/main/java/org/hamcrest/io/package-info.java create mode 100644 hamcrest/src/main/java/org/hamcrest/number/package-info.java delete mode 100644 hamcrest/src/main/java/org/hamcrest/number/package.html create mode 100644 hamcrest/src/main/java/org/hamcrest/object/package-info.java delete mode 100644 hamcrest/src/main/java/org/hamcrest/object/package.html create mode 100644 hamcrest/src/main/java/org/hamcrest/package-info.java create mode 100644 hamcrest/src/main/java/org/hamcrest/text/package-info.java delete mode 100644 hamcrest/src/main/java/org/hamcrest/text/package.html create mode 100644 hamcrest/src/main/java/org/hamcrest/xml/package-info.java delete mode 100644 hamcrest/src/main/java/org/hamcrest/xml/package.html diff --git a/hamcrest/hamcrest.gradle b/hamcrest/hamcrest.gradle index a93a7a5cf..87dfc4c85 100644 --- a/hamcrest/hamcrest.gradle +++ b/hamcrest/hamcrest.gradle @@ -34,3 +34,4 @@ jar { } javadoc.title = "Hamcrest ${version} API" +javadoc.options.overview = file("javadoc-overview.html") diff --git a/hamcrest/javadoc-overview.html b/hamcrest/javadoc-overview.html new file mode 100644 index 000000000..ba197fea2 --- /dev/null +++ b/hamcrest/javadoc-overview.html @@ -0,0 +1,17 @@ + + + + Hamcrest Overview + + +

Matchers that can be combined to create flexible expressions of intent.

+ +

For more information and documentation, see:

+ + + + + diff --git a/hamcrest/src/main/java/org/hamcrest/beans/package-info.java b/hamcrest/src/main/java/org/hamcrest/beans/package-info.java new file mode 100644 index 000000000..d122dc661 --- /dev/null +++ b/hamcrest/src/main/java/org/hamcrest/beans/package-info.java @@ -0,0 +1,4 @@ +/** + * Matchers of Java Bean properties and their values. + */ +package org.hamcrest.beans; \ No newline at end of file diff --git a/hamcrest/src/main/java/org/hamcrest/beans/package.html b/hamcrest/src/main/java/org/hamcrest/beans/package.html deleted file mode 100644 index 0dcc555d3..000000000 --- a/hamcrest/src/main/java/org/hamcrest/beans/package.html +++ /dev/null @@ -1,7 +0,0 @@ - - - - -

Matchers of Java Bean properties and their values.

- - diff --git a/hamcrest/src/main/java/org/hamcrest/collection/package-info.java b/hamcrest/src/main/java/org/hamcrest/collection/package-info.java new file mode 100644 index 000000000..f0e6d370d --- /dev/null +++ b/hamcrest/src/main/java/org/hamcrest/collection/package-info.java @@ -0,0 +1,4 @@ +/** + * Matchers of arrays and collections. + */ +package org.hamcrest.collection; diff --git a/hamcrest/src/main/java/org/hamcrest/collection/package.html b/hamcrest/src/main/java/org/hamcrest/collection/package.html deleted file mode 100644 index 6248d8da3..000000000 --- a/hamcrest/src/main/java/org/hamcrest/collection/package.html +++ /dev/null @@ -1,7 +0,0 @@ - - - - -

Matchers of arrays and collections.

- - diff --git a/hamcrest/src/main/java/org/hamcrest/comparator/package-info.java b/hamcrest/src/main/java/org/hamcrest/comparator/package-info.java new file mode 100644 index 000000000..6a934c9ce --- /dev/null +++ b/hamcrest/src/main/java/org/hamcrest/comparator/package-info.java @@ -0,0 +1,4 @@ +/** + * Helper classes for building matcher comparators. + */ +package org.hamcrest.comparator; \ No newline at end of file diff --git a/hamcrest/src/main/java/org/hamcrest/core/package-info.java b/hamcrest/src/main/java/org/hamcrest/core/package-info.java new file mode 100644 index 000000000..19c433d90 --- /dev/null +++ b/hamcrest/src/main/java/org/hamcrest/core/package-info.java @@ -0,0 +1,4 @@ +/** + * Fundamental matchers of objects and values, and composite matchers. + */ +package org.hamcrest.core; diff --git a/hamcrest/src/main/java/org/hamcrest/core/package.html b/hamcrest/src/main/java/org/hamcrest/core/package.html deleted file mode 100644 index 7bb0ffe10..000000000 --- a/hamcrest/src/main/java/org/hamcrest/core/package.html +++ /dev/null @@ -1,7 +0,0 @@ - - - - -

Fundamental matchers of objects and values, and composite matchers.

- - diff --git a/hamcrest/src/main/java/org/hamcrest/internal/package-info.java b/hamcrest/src/main/java/org/hamcrest/internal/package-info.java new file mode 100644 index 000000000..76947703e --- /dev/null +++ b/hamcrest/src/main/java/org/hamcrest/internal/package-info.java @@ -0,0 +1,4 @@ +/** + * Internal helper classes used by Hamcrest internals. + */ +package org.hamcrest.internal; \ No newline at end of file diff --git a/hamcrest/src/main/java/org/hamcrest/io/package-info.java b/hamcrest/src/main/java/org/hamcrest/io/package-info.java new file mode 100644 index 000000000..a187b6e7f --- /dev/null +++ b/hamcrest/src/main/java/org/hamcrest/io/package-info.java @@ -0,0 +1,4 @@ +/** + * Matchers that perform file comparisons. + */ +package org.hamcrest.io; \ No newline at end of file diff --git a/hamcrest/src/main/java/org/hamcrest/number/package-info.java b/hamcrest/src/main/java/org/hamcrest/number/package-info.java new file mode 100644 index 000000000..58782082d --- /dev/null +++ b/hamcrest/src/main/java/org/hamcrest/number/package-info.java @@ -0,0 +1,4 @@ +/** + * Matchers that perform numeric comparisons. + */ +package org.hamcrest.number; diff --git a/hamcrest/src/main/java/org/hamcrest/number/package.html b/hamcrest/src/main/java/org/hamcrest/number/package.html deleted file mode 100644 index 2fbb07fd0..000000000 --- a/hamcrest/src/main/java/org/hamcrest/number/package.html +++ /dev/null @@ -1,7 +0,0 @@ - - - - -

Matchers that perform numeric comparisons.

- - diff --git a/hamcrest/src/main/java/org/hamcrest/object/package-info.java b/hamcrest/src/main/java/org/hamcrest/object/package-info.java new file mode 100644 index 000000000..b6f56b574 --- /dev/null +++ b/hamcrest/src/main/java/org/hamcrest/object/package-info.java @@ -0,0 +1,4 @@ +/** + * Matchers that inspect objects and classes. + */ +package org.hamcrest.object; diff --git a/hamcrest/src/main/java/org/hamcrest/object/package.html b/hamcrest/src/main/java/org/hamcrest/object/package.html deleted file mode 100644 index 2fde62cea..000000000 --- a/hamcrest/src/main/java/org/hamcrest/object/package.html +++ /dev/null @@ -1,7 +0,0 @@ - - - - -

Matchers that inspect objects and classes.

- - diff --git a/hamcrest/src/main/java/org/hamcrest/package-info.java b/hamcrest/src/main/java/org/hamcrest/package-info.java new file mode 100644 index 000000000..220086b38 --- /dev/null +++ b/hamcrest/src/main/java/org/hamcrest/package-info.java @@ -0,0 +1,4 @@ +/** + * Top level matcher classes and interfaces. + */ +package org.hamcrest; \ No newline at end of file diff --git a/hamcrest/src/main/java/org/hamcrest/text/package-info.java b/hamcrest/src/main/java/org/hamcrest/text/package-info.java new file mode 100644 index 000000000..a9613e428 --- /dev/null +++ b/hamcrest/src/main/java/org/hamcrest/text/package-info.java @@ -0,0 +1,4 @@ +/** + * Matchers that perform text comparisons. + */ +package org.hamcrest.text; diff --git a/hamcrest/src/main/java/org/hamcrest/text/package.html b/hamcrest/src/main/java/org/hamcrest/text/package.html deleted file mode 100644 index 8cf576f73..000000000 --- a/hamcrest/src/main/java/org/hamcrest/text/package.html +++ /dev/null @@ -1,7 +0,0 @@ - - - - -

Matchers that perform text comparisons.

- - diff --git a/hamcrest/src/main/java/org/hamcrest/xml/package-info.java b/hamcrest/src/main/java/org/hamcrest/xml/package-info.java new file mode 100644 index 000000000..2c974c658 --- /dev/null +++ b/hamcrest/src/main/java/org/hamcrest/xml/package-info.java @@ -0,0 +1,4 @@ +/** + * Matchers of XML documents. + */ +package org.hamcrest.xml; diff --git a/hamcrest/src/main/java/org/hamcrest/xml/package.html b/hamcrest/src/main/java/org/hamcrest/xml/package.html deleted file mode 100644 index d9c5f97b9..000000000 --- a/hamcrest/src/main/java/org/hamcrest/xml/package.html +++ /dev/null @@ -1,7 +0,0 @@ - - - - -

Matchers of XML documents.

- - diff --git a/settings.gradle b/settings.gradle index d05ca0c7a..1b9ee2723 100644 --- a/settings.gradle +++ b/settings.gradle @@ -1,7 +1,6 @@ include 'hamcrest', 'hamcrest-core', - 'hamcrest-library', - 'hamcrest-integration' + 'hamcrest-library' rootProject.name = 'JavaHamcrest' From 3b566c7b399f7017f7b6b585c2250c97df6e0659 Mon Sep 17 00:00:00 2001 From: Joe Schmetzer Date: Fri, 2 Aug 2024 18:26:43 +1000 Subject: [PATCH 02/11] Ensure tuturial examples fit in line --- docs/tutorial.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index d123feb6e..4a9489103 100644 --- a/docs/tutorial.md +++ b/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 From 310df7d478e53cc7c3c49841a934ecd71a11cd03 Mon Sep 17 00:00:00 2001 From: Joe Schmetzer Date: Fri, 2 Aug 2024 18:54:44 +1000 Subject: [PATCH 03/11] Remove broken links from related projects --- docs/related.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/related.md b/docs/related.md index 049d2e847..5c208afb3 100644 --- a/docs/related.md +++ b/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) From 43f80bce2df8f5752868e84455e20c00456a9a47 Mon Sep 17 00:00:00 2001 From: Joe Schmetzer Date: Sun, 4 Aug 2024 15:01:11 +1000 Subject: [PATCH 04/11] Suppress warnings about Java 8 --- build.gradle | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/build.gradle b/build.gradle index da5c99dac..9883067e8 100644 --- a/build.gradle +++ b/build.gradle @@ -66,6 +66,12 @@ subprojects { } } +allprojects { + tasks.withType(JavaCompile) { + options.compilerArgs << '-Xlint:-options' + } +} + def pomConfigurationFor(String pomName, String pomDescription) { return { name = pomName From 00952898993d2d89f46b6745f8405e1add0bd779 Mon Sep 17 00:00:00 2001 From: Joe Schmetzer Date: Sun, 4 Aug 2024 15:01:40 +1000 Subject: [PATCH 05/11] Suppress javadoc warnings --- .../hamcrest/core/deprecated/HamcrestCoreIsDeprecated.java | 5 +++++ .../library/deprecated/HamcrestLibraryIsDeprecated.java | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/hamcrest-core/src/main/java/org/hamcrest/core/deprecated/HamcrestCoreIsDeprecated.java b/hamcrest-core/src/main/java/org/hamcrest/core/deprecated/HamcrestCoreIsDeprecated.java index 19482c3d7..afac0ea83 100644 --- a/hamcrest-core/src/main/java/org/hamcrest/core/deprecated/HamcrestCoreIsDeprecated.java +++ b/hamcrest-core/src/main/java/org/hamcrest/core/deprecated/HamcrestCoreIsDeprecated.java @@ -6,4 +6,9 @@ */ @Deprecated class HamcrestCoreIsDeprecated { + /** + * Unused + */ + private HamcrestCoreIsDeprecated() { + } } diff --git a/hamcrest-library/src/main/java/org/hamcrest/library/deprecated/HamcrestLibraryIsDeprecated.java b/hamcrest-library/src/main/java/org/hamcrest/library/deprecated/HamcrestLibraryIsDeprecated.java index b7ec20c3f..29d06fd98 100644 --- a/hamcrest-library/src/main/java/org/hamcrest/library/deprecated/HamcrestLibraryIsDeprecated.java +++ b/hamcrest-library/src/main/java/org/hamcrest/library/deprecated/HamcrestLibraryIsDeprecated.java @@ -6,4 +6,9 @@ */ @Deprecated class HamcrestLibraryIsDeprecated { + /** + * Unused + */ + private HamcrestLibraryIsDeprecated() { + } } From 52cb158689922ca995d81b36c1935a16fdfe523e Mon Sep 17 00:00:00 2001 From: Joe Schmetzer Date: Sun, 4 Aug 2024 16:40:59 +1000 Subject: [PATCH 06/11] Exlude internal pacakge from javadoc --- hamcrest/hamcrest.gradle | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/hamcrest/hamcrest.gradle b/hamcrest/hamcrest.gradle index 87dfc4c85..5799a43e5 100644 --- a/hamcrest/hamcrest.gradle +++ b/hamcrest/hamcrest.gradle @@ -33,5 +33,8 @@ jar { } } -javadoc.title = "Hamcrest ${version} API" -javadoc.options.overview = file("javadoc-overview.html") +javadoc { + title = "Hamcrest ${version} API" + exclude "org/hamcrest/internal/*" + options.overview = file("javadoc-overview.html") +} From 7e7f803415387b8b3d655046a21ecfd5fa012fbd Mon Sep 17 00:00:00 2001 From: Joe Schmetzer Date: Sun, 4 Aug 2024 19:35:17 +1000 Subject: [PATCH 07/11] Add basic example code to javadoc overview --- hamcrest/javadoc-overview.html | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/hamcrest/javadoc-overview.html b/hamcrest/javadoc-overview.html index ba197fea2..a9c2a6e81 100644 --- a/hamcrest/javadoc-overview.html +++ b/hamcrest/javadoc-overview.html @@ -5,6 +5,20 @@

Matchers that can be combined to create flexible expressions of intent.

+

For example:

+
import org.junit.jupiter.api.Test;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.*;
+
+public class BiscuitTest {
+  @Test
+  public void testEquals() {
+    Biscuit theBiscuit = new Biscuit("Ginger");
+    Biscuit myBiscuit = new Biscuit("Ginger");
+    assertThat(theBiscuit, equalTo(myBiscuit));
+  }
+}
+

For more information and documentation, see:

    From 0e31d698960d2740ea09eca8b05286a4d0f2cabf Mon Sep 17 00:00:00 2001 From: Joe Schmetzer Date: Sun, 11 Aug 2024 10:08:10 +1000 Subject: [PATCH 08/11] Add missing javadoc and fix javadoc warnings Javadoc warnings are all clean when compiling using JDK 21. There are still warnings when compiling with JDK 8 or 17 (will attempt to fix later). --- .../java/org/hamcrest/BaseDescription.java | 6 + .../main/java/org/hamcrest/BaseMatcher.java | 6 + .../src/main/java/org/hamcrest/Condition.java | 64 +++++++- .../main/java/org/hamcrest/CoreMatchers.java | 50 ++++--- .../main/java/org/hamcrest/CustomMatcher.java | 10 +- .../org/hamcrest/CustomTypeSafeMatcher.java | 6 +- .../main/java/org/hamcrest/Description.java | 137 ++++++++---------- .../java/org/hamcrest/DiagnosingMatcher.java | 21 ++- .../src/main/java/org/hamcrest/Matcher.java | 1 + .../main/java/org/hamcrest/MatcherAssert.java | 25 ++++ .../src/main/java/org/hamcrest/Matchers.java | 13 +- .../java/org/hamcrest/StringDescription.java | 7 + .../hamcrest/TypeSafeDiagnosingMatcher.java | 7 +- .../java/org/hamcrest/TypeSafeMatcher.java | 11 +- .../java/org/hamcrest/beans/HasProperty.java | 13 +- .../hamcrest/beans/HasPropertyWithValue.java | 38 +++-- .../java/org/hamcrest/beans/PropertyUtil.java | 10 +- .../hamcrest/beans/SamePropertyValuesAs.java | 32 ++-- .../collection/ArrayAsIterableMatcher.java | 18 +++ .../hamcrest/collection/ArrayMatching.java | 11 +- .../hamcrest/collection/HasItemInArray.java | 7 + .../java/org/hamcrest/collection/IsArray.java | 6 + .../IsArrayContainingInAnyOrder.java | 7 + .../collection/IsArrayContainingInOrder.java | 7 + .../hamcrest/collection/IsArrayWithSize.java | 9 +- .../collection/IsCollectionWithSize.java | 7 + .../collection/IsEmptyCollection.java | 11 +- .../hamcrest/collection/IsEmptyIterable.java | 11 +- .../java/org/hamcrest/collection/IsIn.java | 12 ++ .../IsIterableContainingInAnyOrder.java | 12 ++ .../IsIterableContainingInOrder.java | 14 ++ .../IsIterableContainingInRelativeOrder.java | 11 ++ .../collection/IsIterableWithSize.java | 10 ++ .../hamcrest/collection/IsMapContaining.java | 15 ++ .../hamcrest/collection/IsMapWithSize.java | 15 +- .../comparator/ComparatorMatcherBuilder.java | 4 + .../main/java/org/hamcrest/core/AllOf.java | 13 ++ .../main/java/org/hamcrest/core/AnyOf.java | 13 ++ .../org/hamcrest/core/CombinableMatcher.java | 52 ++++++- .../java/org/hamcrest/core/DescribedAs.java | 24 +-- .../main/java/org/hamcrest/core/Every.java | 9 ++ .../src/main/java/org/hamcrest/core/Is.java | 7 + .../java/org/hamcrest/core/IsAnything.java | 14 ++ .../hamcrest/core/IsCollectionContaining.java | 9 ++ .../main/java/org/hamcrest/core/IsEqual.java | 9 +- .../hamcrest/core/IsIterableContaining.java | 12 ++ .../main/java/org/hamcrest/core/IsNot.java | 7 + .../main/java/org/hamcrest/core/IsNull.java | 31 ++-- .../main/java/org/hamcrest/core/IsSame.java | 7 + .../hamcrest/core/ShortcutCombination.java | 15 ++ .../org/hamcrest/core/StringContains.java | 10 ++ .../org/hamcrest/core/StringEndsWith.java | 14 +- .../core/StringRegularExpression.java | 7 +- .../org/hamcrest/core/StringStartsWith.java | 14 +- .../org/hamcrest/core/SubstringMatcher.java | 20 +++ .../java/org/hamcrest/io/FileMatchers.java | 72 ++++++++- .../hamcrest/number/BigDecimalCloseTo.java | 9 ++ .../java/org/hamcrest/number/IsCloseTo.java | 4 + .../hamcrest/number/OrderingComparison.java | 3 + .../org/hamcrest/object/HasEqualValues.java | 8 + .../java/org/hamcrest/object/HasToString.java | 5 + .../org/hamcrest/object/IsCompatibleType.java | 9 ++ .../java/org/hamcrest/object/IsEventFrom.java | 5 + .../org/hamcrest/text/CharSequenceLength.java | 9 +- .../text/IsEqualCompressingWhiteSpace.java | 6 + .../hamcrest/text/IsEqualIgnoringCase.java | 4 + .../org/hamcrest/text/MatchesPattern.java | 11 +- .../hamcrest/text/StringContainsInOrder.java | 7 + .../main/java/org/hamcrest/xml/HasXPath.java | 15 +- 69 files changed, 903 insertions(+), 195 deletions(-) diff --git a/hamcrest/src/main/java/org/hamcrest/BaseDescription.java b/hamcrest/src/main/java/org/hamcrest/BaseDescription.java index fb06f5b65..373992459 100644 --- a/hamcrest/src/main/java/org/hamcrest/BaseDescription.java +++ b/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); diff --git a/hamcrest/src/main/java/org/hamcrest/BaseMatcher.java b/hamcrest/src/main/java/org/hamcrest/BaseMatcher.java index a142522a2..9ae9ea5f4 100644 --- a/hamcrest/src/main/java/org/hamcrest/BaseMatcher.java +++ b/hamcrest/src/main/java/org/hamcrest/BaseMatcher.java @@ -4,8 +4,14 @@ * BaseClass for all Matcher implementations. * * @see Matcher + * @param The Matcher type. */ public abstract class BaseMatcher implements Matcher { + /** + * Default constructor. + */ + public BaseMatcher() { + } /** * @see Matcher#_dont_implement_Matcher___instead_extend_BaseMatcher_() diff --git a/hamcrest/src/main/java/org/hamcrest/Condition.java b/hamcrest/src/main/java/org/hamcrest/Condition.java index 4012027aa..85293eb1a 100644 --- a/hamcrest/src/main/java/org/hamcrest/Condition.java +++ b/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 + *

    Based on Nat Pryce's maybe-java. + *

    + * + * @param the matched value type * @author Steve Freeman 2012 http://www.hamcrest.com */ public abstract class Condition { - public static final NotMatched NOT_MATCHED = new NotMatched<>(); - + /** + * Represents a single step in a multi-step sequence + * @param the initial value type + * @param the next step value type + */ public interface Step { + /** + * Apply this condition to a value + * @param value the value to match + * @param mismatch the description for mismatches + * @return the next condition + */ Condition 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 match, String message); - public abstract Condition and(Step 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 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 the type of the next value + */ + public abstract Condition and(Step 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 the type of the next value + */ public final Condition then(Step mapping) { return and(mapping); } + /** + * Called by steps when a mismatch occurs. + * @return a condition in the not matched state + * @param the type of the unmatched value + */ @SuppressWarnings("unchecked") public static Condition notMatched() { - return (Condition) NOT_MATCHED; + return (Condition) 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 the type of the matched value + */ public static Condition matched(final T theValue, final Description mismatch) { return new Matched<>(theValue, mismatch); } @@ -60,6 +110,8 @@ public Condition and(Step next) { } private static final class NotMatched extends Condition { + public static final NotMatched NOT_MATCHED = new NotMatched<>(); + @Override public boolean matching(Matcher match, String message) { return false; } @Override public Condition and(Step mapping) { diff --git a/hamcrest/src/main/java/org/hamcrest/CoreMatchers.java b/hamcrest/src/main/java/org/hamcrest/CoreMatchers.java index 3e2ce384c..f2a66cc87 100644 --- a/hamcrest/src/main/java/org/hamcrest/CoreMatchers.java +++ b/hamcrest/src/main/java/org/hamcrest/CoreMatchers.java @@ -2,9 +2,20 @@ import org.hamcrest.core.IsIterableContaining; +/** + * Builder methods for various matchers. + *

    + * CodeMatchers provides syntactic sugar for building matchers, or + * chains of matchers. By using static imports on these methods, concise and + * readable code calling the matchers can be maintained. + *

    + */ @SuppressWarnings("UnusedDeclaration") public class CoreMatchers { + private CoreMatchers() { + } + /** * Creates a matcher that matches if the examined object matches ALL of the specified matchers. * For example: @@ -75,7 +86,7 @@ public static org.hamcrest.core.AnyOf anyOf(org.hamcrest.Matcher * the matcher type. * @param matcher - * the matcher to combine, and both musth pass. + * the matcher to combine, and both must pass. * @return The matcher. */ public static org.hamcrest.core.CombinableMatcher.CombinableBothMatcher both(org.hamcrest.Matcher matcher) { @@ -110,7 +121,7 @@ public static org.hamcrest.core.CombinableMatcher.CombinableEitherMatcher< * @param matcher * the matcher to wrap * @param values - * optional values to insert into the tokenised description + * optional values to insert into the tokenized description * @return The matcher. */ public static org.hamcrest.Matcher describedAs(java.lang.String description, org.hamcrest.Matcher matcher, java.lang.Object... values) { @@ -145,7 +156,7 @@ public static org.hamcrest.Matcher> everyIte * @param * the matcher type. * @param matcher - * the matcher {@link org.hamcrest.core.Is#is}. + * the matcher to wrap. * @return The matcher. */ public static org.hamcrest.Matcher is(org.hamcrest.Matcher matcher) { @@ -162,7 +173,7 @@ public static org.hamcrest.Matcher is(org.hamcrest.Matcher matcher) { * @param * the matcher type. * @param value - * the value for matcher {@link org.hamcrest.core.Is#is}. + * the value to check. * @return The matcher. */ public static org.hamcrest.Matcher is(T value) { @@ -179,7 +190,7 @@ public static org.hamcrest.Matcher is(T value) { * @param * the matcher type. * @param type - * the type for matcher {@link org.hamcrest.core.Is#isA}. + * the type to check. * @return The matcher. */ public static org.hamcrest.Matcher isA(java.lang.Class type) { @@ -188,7 +199,6 @@ public static org.hamcrest.Matcher isA(java.lang.Class type) { /** * Creates a matcher that always matches, regardless of the examined object. - * * @return The matcher. */ public static org.hamcrest.Matcher anything() { @@ -305,7 +315,7 @@ public static org.hamcrest.Matcher> hasItems(T... item * @param * the matcher type. * @param operand - * for matcher {@link org.hamcrest.core.IsEqual#equalTo}. + * the value to check. * @return The matcher. */ public static org.hamcrest.Matcher equalTo(T operand) { @@ -317,7 +327,7 @@ public static org.hamcrest.Matcher equalTo(T operand) { * compared to be of the same static type. * * @param operand - * the object for matcher {@link org.hamcrest.core.IsEqual#equalToObject}. + * the value to check. * @return The matcher. */ public static org.hamcrest.Matcher equalToObject(java.lang.Object operand) { @@ -327,7 +337,7 @@ public static org.hamcrest.Matcher equalToObject(java.lang.Obj /** * Creates a matcher that matches when the examined object is an instance of the specified type, * as determined by calling the {@link java.lang.Class#isInstance(Object)} method on that type, passing the - * the examined object. + * examined object. * *

    The created matcher forces a relationship between specified type and the examined object, and should be * used when it is necessary to make generics conform, for example in the JMock clause @@ -338,7 +348,7 @@ public static org.hamcrest.Matcher equalToObject(java.lang.Obj * @param * the matcher type. * @param type - * the type for matcher {@link org.hamcrest.core.IsInstanceOf#any}. + * the type to check. * @return The matcher. */ public static org.hamcrest.Matcher any(java.lang.Class type) { @@ -357,7 +367,7 @@ public static org.hamcrest.Matcher any(java.lang.Class type) { * @param * the matcher type. * @param type - * the type for matcher {@link org.hamcrest.core.IsInstanceOf#instanceOf}. + * the type to check. * @return The matcher. */ public static org.hamcrest.Matcher instanceOf(java.lang.Class type) { @@ -493,7 +503,7 @@ public static org.hamcrest.Matcher theInstance(T target) { * the substring that the returned matcher will expect to find within any examined string * @return The matcher. */ - public static org.hamcrest.Matcher containsString(java.lang.String substring) { + public static Matcher containsString(java.lang.String substring) { return org.hamcrest.core.StringContains.containsString(substring); } @@ -501,13 +511,13 @@ public static org.hamcrest.Matcher containsString(java.lang.St * Creates a matcher that matches if the examined {@link String} contains the specified * {@link String} anywhere, ignoring case. * For example: - * 

    assertThat("myStringOfNote", containsString("ring"))
    + * 
    assertThat("myStringOfNote", containsStringIgnoringCase("Ring"))
    * * @param substring * the substring that the returned matcher will expect to find within any examined string * @return The matcher. */ - public static org.hamcrest.Matcher containsStringIgnoringCase(java.lang.String substring) { + public static Matcher containsStringIgnoringCase(java.lang.String substring) { return org.hamcrest.core.StringContains.containsStringIgnoringCase(substring); } @@ -523,7 +533,7 @@ public static org.hamcrest.Matcher containsStringIgnoringCase( * the substring that the returned matcher will expect at the start of any examined string * @return The matcher. */ - public static org.hamcrest.Matcher startsWith(java.lang.String prefix) { + public static Matcher startsWith(java.lang.String prefix) { return org.hamcrest.core.StringStartsWith.startsWith(prefix); } @@ -533,13 +543,13 @@ public static org.hamcrest.Matcher startsWith(java.lang.String * {@link String}, ignoring case *

    * For example: - * 
    assertThat("myStringOfNote", startsWith("my"))
    + * 
    assertThat("myStringOfNote", startsWithIgnoringCase("My"))
    * * @param prefix * the substring that the returned matcher will expect at the start of any examined string * @return The matcher. */ - public static org.hamcrest.Matcher startsWithIgnoringCase(java.lang.String prefix) { + public static Matcher startsWithIgnoringCase(java.lang.String prefix) { return org.hamcrest.core.StringStartsWith.startsWithIgnoringCase(prefix); } @@ -553,7 +563,7 @@ public static org.hamcrest.Matcher startsWithIgnoringCase(java * the substring that the returned matcher will expect at the end of any examined string * @return The matcher. */ - public static org.hamcrest.Matcher endsWith(java.lang.String suffix) { + public static Matcher endsWith(java.lang.String suffix) { return org.hamcrest.core.StringEndsWith.endsWith(suffix); } @@ -561,13 +571,13 @@ public static org.hamcrest.Matcher endsWith(java.lang.String s * Creates a matcher that matches if the examined {@link String} ends with the specified * {@link String}, ignoring case. * For example: - * 
    assertThat("myStringOfNote", endsWith("Note"))
    + * 
    assertThat("myStringOfNote", endsWithIgnoringCase("note"))
    * * @param suffix * the substring that the returned matcher will expect at the end of any examined string * @return The matcher. */ - public static org.hamcrest.Matcher endsWithIgnoringCase(java.lang.String suffix) { + public static Matcher endsWithIgnoringCase(java.lang.String suffix) { return org.hamcrest.core.StringEndsWith.endsWithIgnoringCase(suffix); } diff --git a/hamcrest/src/main/java/org/hamcrest/CustomMatcher.java b/hamcrest/src/main/java/org/hamcrest/CustomMatcher.java index 3b5006e77..0a63c8b27 100644 --- a/hamcrest/src/main/java/org/hamcrest/CustomMatcher.java +++ b/hamcrest/src/main/java/org/hamcrest/CustomMatcher.java @@ -13,17 +13,21 @@ *

    * This class is designed for scenarios where an anonymous inner class * matcher makes sense. It should not be used by API designers implementing - * matchers. + * matchers. See {@link CustomTypeSafeMatcher} for a type safe variant of + * this class that you probably want to use. * * @author Neil Dunn - * @see CustomTypeSafeMatcher for a type safe variant of this class that you probably - * want to use. * @param The type of object being matched. + * @see CustomTypeSafeMatcher */ public abstract class CustomMatcher extends BaseMatcher { private final String fixedDescription; + /** + * Constructor + * @param description the description of this matcher + */ public CustomMatcher(String description) { if (description == null) { throw new IllegalArgumentException("Description should be non null!"); diff --git a/hamcrest/src/main/java/org/hamcrest/CustomTypeSafeMatcher.java b/hamcrest/src/main/java/org/hamcrest/CustomTypeSafeMatcher.java index 3becc146e..3aff0d2e0 100644 --- a/hamcrest/src/main/java/org/hamcrest/CustomTypeSafeMatcher.java +++ b/hamcrest/src/main/java/org/hamcrest/CustomTypeSafeMatcher.java @@ -1,7 +1,7 @@ package org.hamcrest; /** - * Utility class for writing one off matchers. + * Utility class for writing one off matchers (with type safety and null checks). * For example: * 

      * Matcher<String> aNonEmptyString = new CustomTypeSafeMatcher<String>("a non empty string") {
@@ -24,6 +24,10 @@ public abstract class CustomTypeSafeMatcher extends TypeSafeMatcher {
 
     private final String fixedDescription;
 
+    /**
+     * Constructor
+     * @param description the description of this matcher
+     */
     public CustomTypeSafeMatcher(String description) {
         if (description == null) {
             throw new IllegalArgumentException("Description must be non null!");
diff --git a/hamcrest/src/main/java/org/hamcrest/Description.java b/hamcrest/src/main/java/org/hamcrest/Description.java
index cd9b86151..4f630f6c4 100644
--- a/hamcrest/src/main/java/org/hamcrest/Description.java
+++ b/hamcrest/src/main/java/org/hamcrest/Description.java
@@ -8,16 +8,16 @@
  */
 public interface Description {
 
-  /**
-   * A description that consumes input but does nothing.
-   */
-  static final Description NONE = new NullDescription();
+    /**
+     * A description that consumes input but does nothing, implemented by
+     * {@link NullDescription}.
+     */
+    Description NONE = new NullDescription();
 
     /**
      * Appends some plain text to the description.
      *
-     * @param text
-     *     the text to append.
+     * @param text the text to append.
      * @return the update description when displaying the matcher error.
      */
     Description appendText(String text);
@@ -25,8 +25,7 @@ public interface Description {
     /**
      * Appends the description of a {@link SelfDescribing} value to this description.
      *
-     * @param value
-     *     the value to append.
+     * @param value the value to append.
      * @return the update description when displaying the matcher error.
      */
     Description appendDescriptionOf(SelfDescribing value);
@@ -34,8 +33,7 @@ public interface Description {
     /**
      * Appends an arbitrary value to the description.
      *
-     * @param value
-     *     the object to append.
+     * @param value the object to append.
      * @return the update description when displaying the matcher error.
      */
     Description appendValue(Object value);
@@ -43,16 +41,11 @@ public interface Description {
     /**
      * Appends a list of values to the description.
      *
-     * @param 
-     *     the description type.
-     * @param start
-     *     the prefix.
-     * @param separator
-     *     the separator.
-     * @param end
-     *     the suffix.
-     * @param values
-     *     the values to append.
+     * @param        the description type.
+     * @param start     the prefix.
+     * @param separator the separator.
+     * @param end       the suffix.
+     * @param values    the values to append.
      * @return the update description when displaying the matcher error.
      */
      Description appendValueList(String start, String separator, String end,
@@ -61,16 +54,11 @@  Description appendValueList(String start, String separator, String end,
     /**
      * Appends a list of values to the description.
      *
-     * @param 
-     *     the description type.
-     * @param start
-     *     the prefix.
-     * @param separator
-     *     the separator.
-     * @param end
-     *     the suffix.
-     * @param values
-     *     the values to append.
+     * @param        the description type.
+     * @param start     the prefix.
+     * @param separator the separator.
+     * @param end       the suffix.
+     * @param values    the values to append.
      * @return the update description when displaying the matcher error.
      */
      Description appendValueList(String start, String separator, String end,
@@ -79,56 +67,57 @@  Description appendValueList(String start, String separator, String end,
     /**
      * Appends a list of {@link org.hamcrest.SelfDescribing} objects
      * to the description.
-     * @param start
-     *     the prefix.
-     * @param separator
-     *     the separator.
-     * @param end
-     *     the suffix.
-     * @param values
-     *     the values to append.
+     *
+     * @param start     the prefix.
+     * @param separator the separator.
+     * @param end       the suffix.
+     * @param values    the values to append.
      * @return the update description when displaying the matcher error.
      */
     Description appendList(String start, String separator, String end,
                            Iterable values);
 
-    public static final class NullDescription implements Description {
-      @Override
-      public Description appendDescriptionOf(SelfDescribing value) {
-        return this;
-      }
-
-      @Override
-      public Description appendList(String start, String separator,
-          String end, Iterable values) {
-        return this;
-      }
-
-      @Override
-      public Description appendText(String text) {
-        return this;
-      }
-
-      @Override
-      public Description appendValue(Object value) {
-        return this;
-      }
-
-      @Override
-      public  Description appendValueList(String start, String separator,
-          String end, T... values) {
-        return this;
-      }
-
-      @Override
-      public  Description appendValueList(String start, String separator,
-          String end, Iterable values) {
-        return this;
-      }
-
-      @Override
+    /**
+     * A description that consumes input but does nothing.
+     */
+    @SuppressWarnings("doclint")
+    final class NullDescription implements Description {
+        @Override
+        public Description appendDescriptionOf(SelfDescribing value) {
+            return this;
+        }
+
+        @Override
+        public Description appendList(String start, String separator,
+                                      String end, Iterable values) {
+            return this;
+        }
+
+        @Override
+        public Description appendText(String text) {
+            return this;
+        }
+
+        @Override
+        public Description appendValue(Object value) {
+            return this;
+        }
+
+        @Override
+        public  Description appendValueList(String start, String separator,
+                                               String end, T... values) {
+            return this;
+        }
+
+        @Override
+        public  Description appendValueList(String start, String separator,
+                                               String end, Iterable values) {
+            return this;
+        }
+
+        @Override
         public String toString() {
-          return "";
+            return "";
         }
     }
 
diff --git a/hamcrest/src/main/java/org/hamcrest/DiagnosingMatcher.java b/hamcrest/src/main/java/org/hamcrest/DiagnosingMatcher.java
index 54e9bf146..44a36c486 100644
--- a/hamcrest/src/main/java/org/hamcrest/DiagnosingMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/DiagnosingMatcher.java
@@ -1,12 +1,25 @@
 package org.hamcrest;
 
 /**
- * TODO(ngd): Document.
+ * Convenient base class for Matchers of a specific type and that will report why the
+ * received value has been rejected.
+ *
+ * Unlike the {@link TypeSafeDiagnosingMatcher}, this does not implement the null check
+ * or validate the type, so subclasses need to be prepared to handle these conditions.
+ *
+ * To use, implement {@link #matches(Object, Description)}
  *
  * @param  the type of matcher being diagnosed.
+ * @see TypeSafeDiagnosingMatcher
  */
 public abstract class DiagnosingMatcher extends BaseMatcher {
 
+    /**
+     * Constructor
+     */
+    public DiagnosingMatcher() {
+    }
+
     @Override
     public final boolean matches(Object item) {
         return matches(item, Description.NONE);
@@ -17,6 +30,12 @@ public final void describeMismatch(Object item, Description mismatchDescription)
         matches(item, mismatchDescription);
     }
 
+    /**
+     * Evaluates the matcher for argument item.
+     * @param item the value to check
+     * @param mismatchDescription the description for the matcher
+     * @return true if item matches, otherwise false.
+     */
     protected abstract boolean matches(Object item, Description mismatchDescription);
 
 }
diff --git a/hamcrest/src/main/java/org/hamcrest/Matcher.java b/hamcrest/src/main/java/org/hamcrest/Matcher.java
index dffc09abe..697009369 100644
--- a/hamcrest/src/main/java/org/hamcrest/Matcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/Matcher.java
@@ -21,6 +21,7 @@
  * N.B. Well designed matchers should be immutable.
  * 
    
  *
+ * @param  the matched value type
  * @see BaseMatcher
  */
 public interface Matcher extends SelfDescribing {
diff --git a/hamcrest/src/main/java/org/hamcrest/MatcherAssert.java b/hamcrest/src/main/java/org/hamcrest/MatcherAssert.java
index c8bd9a505..574f4f61b 100644
--- a/hamcrest/src/main/java/org/hamcrest/MatcherAssert.java
+++ b/hamcrest/src/main/java/org/hamcrest/MatcherAssert.java
@@ -1,11 +1,31 @@
 package org.hamcrest;
 
+/**
+ * The Hamcrest entrypoint, static methods to check if matchers match a
+ * given value.
+ */
 public class MatcherAssert {
 
+    private MatcherAssert() {
+    }
+
+    /**
+     * Checks that a value matches a matcher
+     * @param actual the value to check
+     * @param matcher the matcher
+     * @param  the type of the value
+     */
     public static  void assertThat(T actual, Matcher matcher) {
         assertThat("", actual, matcher);
     }
 
+    /**
+     * Checks that a value matches a matcher
+     * @param reason a description of what is being matched
+     * @param actual the value to check
+     * @param matcher the matcher
+     * @param  the type of the value
+     */
     public static  void assertThat(String reason, T actual, Matcher matcher) {
         if (!matcher.matches(actual)) {
             Description description = new StringDescription();
@@ -21,6 +41,11 @@ public static  void assertThat(String reason, T actual, Matcher ma
         }
     }
 
+    /**
+     * Checks that an assertion is true
+     * @param reason a description of what is being checked
+     * @param assertion the result of the check
+     */
     public static void assertThat(String reason, boolean assertion) {
         if (!assertion) {
             throw new AssertionError(reason);
diff --git a/hamcrest/src/main/java/org/hamcrest/Matchers.java b/hamcrest/src/main/java/org/hamcrest/Matchers.java
index 38907b1bd..85348ea04 100644
--- a/hamcrest/src/main/java/org/hamcrest/Matchers.java
+++ b/hamcrest/src/main/java/org/hamcrest/Matchers.java
@@ -7,9 +7,20 @@
 
 import java.util.regex.Pattern;
 
+/**
+ * Builder methods for various matchers.
+ * 
    
+ * Matchers provides syntactic sugar for building matchers, or
+ * chains of matchers. By using static imports on these methods, concise and
+ * readable code calling the matchers can be maintained.
+ * 
    
+ */
 @SuppressWarnings({"unused", "WeakerAccess"})
 public class Matchers {
 
+  private Matchers() {
+  }
+
   /**
    * Creates a matcher that matches if the examined object matches ALL of the specified matchers.
    * For example:
@@ -541,7 +552,7 @@ public static org.hamcrest.Matcher equalToObject(java.lang.Obj
   /**
    * Creates a matcher that matches when the examined object is an instance of the specified type,
    * as determined by calling the {@link java.lang.Class#isInstance(Object)} method on that type, passing the
-   * the examined object.
+   * examined object.
    *
    * 
    The created matcher forces a relationship between specified type and the examined object, and should be
    * used when it is necessary to make generics conform, for example in the JMock clause
diff --git a/hamcrest/src/main/java/org/hamcrest/StringDescription.java b/hamcrest/src/main/java/org/hamcrest/StringDescription.java
index 76fd39f8c..a8b3e8032 100644
--- a/hamcrest/src/main/java/org/hamcrest/StringDescription.java
+++ b/hamcrest/src/main/java/org/hamcrest/StringDescription.java
@@ -9,10 +9,17 @@ public class StringDescription extends BaseDescription {
 
     private final Appendable out;
 
+    /**
+     * Creates a new description.
+     */
     public StringDescription() {
         this(new StringBuilder());
     }
 
+    /**
+     * Creates a new description using the given appendable.
+     * @param out the place to append the description.
+     */
     public StringDescription(Appendable out) {
         this.out = out;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java b/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java
index 73edb8354..4bcf871b2 100644
--- a/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/TypeSafeDiagnosingMatcher.java
@@ -6,10 +6,11 @@
  * Convenient base class for Matchers that require a non-null value of a specific type
  * and that will report why the received value has been rejected.
  * This implements the null check, checks the type and then casts.
- * To use, implement 
    matchesSafely()
    .
+ * To use, implement {@link #matchesSafely(Object, Description)}.
+ *
+ * @param  the matcher type.
+ * @see DiagnosingMatcher
  *
- * @param 
- *     the matcher type.
  * @author Neil Dunn
  * @author Nat Pryce
  * @author Steve Freeman
diff --git a/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java b/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java
index d7f057b6e..4bad8e8a4 100644
--- a/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/TypeSafeMatcher.java
@@ -45,18 +45,17 @@ protected TypeSafeMatcher(ReflectiveTypeFinder typeFinder) {
     }
 
     /**
-     * Subclasses should implement this. The item will already have been checked for
-     * the specific type and will never be null.
+     * Check if the item matches. The item will already have been checked for
+     * the specific type and will never be null. Subclasses should implement this.
      *
-     * @param item
-     *     the type safe item to match against.
+     * @param item the type safe item to match against.
      * @return boolean true/false depending if item matches matcher.
      */
     protected abstract boolean matchesSafely(T item);
 
     /**
-     * Subclasses should override this. The item will already have been checked for
-     * the specific type and will never be null.
+     * Describe the mismatch. The item will already have been checked for
+     * the specific type and will never be null. Subclasses should override this.
      *
      * @param item
      *     the type safe item to match against.
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java b/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
index 8ddd0f880..b4db81f34 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
@@ -3,12 +3,14 @@
 import org.hamcrest.Description;
 import org.hamcrest.Matcher;
 import org.hamcrest.TypeSafeMatcher;
+import org.hamcrest.collection.ArrayMatching;
 
 /**
- * A Matcher that checks that an object has a JavaBean property
- * with the specified name. If an error occurs during introspection
- * of the object then this is treated as a mismatch.
+ * A matcher that checks if an object has a JavaBean property with the
+ * specified name. If an error occurs during introspection of the object
+ * then this is treated as a mismatch.
  *
+ * @param  The Matcher type.
  * @author Iain McGinniss
  * @author Nat Pryce
  * @author Steve Freeman
@@ -17,6 +19,11 @@ public class HasProperty extends TypeSafeMatcher {
 
     private final String propertyName;
 
+    /**
+     * Constructor, best called from {@link #hasProperty(String)}.
+     * @see #hasProperty(String) 
+     */
+    @SuppressWarnings("doclint")
     public HasProperty(String propertyName) {
         this.propertyName = propertyName;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java b/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
index 7c3de8a88..32f794eb1 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
@@ -17,9 +17,9 @@
 import static org.hamcrest.beans.PropertyUtil.NO_ARGUMENTS;
 
 /**
- * 
    Matcher that asserts that a JavaBean property on an argument passed to the
- * mock object meets the provided matcher. This is useful for when objects
- * are created within code under test and passed to a mock object, and you wish
+ * 
    A matcher that checks if an object has a JavaBean property with the
+ * specified name and an expected value. This is useful for when objects are
+ * created within code under test and passed to a mock object, and you wish
  * to assert that the created object has certain properties.
  * 
    
  *
@@ -27,8 +27,7 @@
  * Consider the situation where we have a class representing a person, which
  * follows the basic JavaBean convention of having get() and possibly set()
  * methods for it's properties:
- * 
    - * public class Person {
+ * 
    {@code  public class Person {
  *   private String name;
  *   public Person(String person) {
  *     this.person = person;
@@ -36,22 +35,20 @@
  *   public String getName() {
  *     return name;
  *   }
- * }
    
+ * } }
    
  *
  * And that these person objects are generated within a piece of code under test
  * (a class named PersonGenerator). This object is sent to one of our mock objects
  * which overrides the PersonGenerationListener interface:
- * 
    - * public interface PersonGenerationListener {
+ * 
    {@code  public interface PersonGenerationListener {
  *   public void personGenerated(Person person);
- * }
    
+ * } }
    
  *
  * In order to check that the code under test generates a person with name
  * "Iain" we would do the following:
- * 
    - * Mock personGenListenerMock = mock(PersonGenerationListener.class);
+ * 
    {@code  Mock personGenListenerMock = mock(PersonGenerationListener.class);
  * personGenListenerMock.expects(once()).method("personGenerated").with(and(isA(Person.class), hasProperty("Name", eq("Iain")));
- * PersonGenerationListener listener = (PersonGenerationListener)personGenListenerMock.proxy();
    
+ * PersonGenerationListener listener = (PersonGenerationListener)personGenListenerMock.proxy(); }
    
  *
  * 
    If an exception is thrown by the getter method for a property, the property
  * does not exist, is not readable, or a reflection related exception is thrown
@@ -59,11 +56,12 @@
  * the matches method will return false.
  * 
    
  * 
    This matcher class will also work with JavaBean objects that have explicit
- * bean descriptions via an associated BeanInfo description class. See the
- * JavaBeans specification for more information:
- * http://java.sun.com/products/javabeans/docs/index.html
+ * bean descriptions via an associated BeanInfo description class.
+ * See https://docs.oracle.com/javase/8/docs/technotes/guides/beans/index.html for
+ * more information on JavaBeans.
  * 
    
  *
+ * @param  the Matcher type
  * @author Iain McGinniss
  * @author Nat Pryce
  * @author Steve Freeman
@@ -76,10 +74,20 @@ public class HasPropertyWithValue extends TypeSafeDiagnosingMatcher {
     private final Matcher valueMatcher;
     private final String messageFormat;
 
+    /**
+     * Constructor, best called from {@link #hasProperty(String, Matcher)} or
+     * {@link #hasPropertyAtPath(String, Matcher)}.
+     */
+    @SuppressWarnings("doclint")
     public HasPropertyWithValue(String propertyName, Matcher valueMatcher) {
         this(propertyName, valueMatcher, " property '%s' ");
     }
 
+    /**
+     * Constructor, best called from {@link #hasProperty(String, Matcher)} or
+     * {@link #hasPropertyAtPath(String, Matcher)}.
+     */
+    @SuppressWarnings("doclint")
     public HasPropertyWithValue(String propertyName, Matcher valueMatcher, String messageFormat) {
         this.propertyName = propertyName;
         this.valueMatcher = nastyGenericsWorkaround(valueMatcher);
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/PropertyUtil.java b/hamcrest/src/main/java/org/hamcrest/beans/PropertyUtil.java
index 79a51298b..71b7dceae 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/PropertyUtil.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/PropertyUtil.java
@@ -5,8 +5,8 @@
 import java.beans.PropertyDescriptor;
 
 /**
- * Utility class for accessing properties on JavaBean objects.
- * See http://java.sun.com/products/javabeans/docs/index.html for
+ * Utility class with static methods for accessing properties on JavaBean objects.
+ * See https://docs.oracle.com/javase/8/docs/technotes/guides/beans/index.html for
  * more information on JavaBeans.
  *
  * @author Iain McGinniss
@@ -15,6 +15,9 @@
  */
 public class PropertyUtil {
 
+    private PropertyUtil() {
+    }
+
     /**
      * Returns the description of the property with the provided
      * name on the provided object's interface.
@@ -52,6 +55,9 @@ public static PropertyDescriptor[] propertyDescriptorsFor(Object fromObj, Class<
       }
     }
 
+    /**
+     * Empty object array, used for documenting that we are deliberately passing no arguments to a method.
+     */
     public static final Object[] NO_ARGUMENTS = new Object[0];
 
 }
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java b/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
index 3928647b6..958289a06 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
@@ -13,6 +13,12 @@
 import static org.hamcrest.beans.PropertyUtil.propertyDescriptorsFor;
 import static org.hamcrest.core.IsEqual.equalTo;
 
+/**
+ * A matcher that checks if a given bean has the same property values
+ * as an example bean.
+ * @param  the matcher value type.
+ * @see #samePropertyValuesAs(Object, String...)
+ */
 public class SamePropertyValuesAs extends DiagnosingMatcher {
 
     private final T expectedBean;
@@ -20,7 +26,10 @@ public class SamePropertyValuesAs extends DiagnosingMatcher {
     private final List propertyMatchers;
     private final List ignoredFields;
 
-    @SuppressWarnings("WeakerAccess")
+    /**
+     * Constructor, best called from {@link #samePropertyValuesAs(Object, String...)}.
+     */
+    @SuppressWarnings({"WeakerAccess", "doclint"})
     public SamePropertyValuesAs(T expectedBean, List ignoredProperties) {
         PropertyDescriptor[] descriptors = propertyDescriptorsFor(expectedBean, Object.class);
         this.expectedBean = expectedBean;
@@ -138,21 +147,22 @@ private static Object readProperty(Method method, Object target) {
     }
 
     /**
-     * Creates a matcher that matches when the examined object has values for all of
+     * 
    Creates a matcher that matches when the examined object has values for all of
      * its JavaBean properties that are equal to the corresponding values of the
      * specified bean. If any properties are marked as ignored, they will be dropped from
      * both the expected and actual bean. Note that the ignored properties use JavaBean
-     * display names, for example 
    age
     rather than method names such as 
    getAge
    .
+     * display names, for example "age" rather than method names such as
+     * "getAge".
+     * 
    
      * For example:
-     * 
    assertThat(myBean, samePropertyValuesAs(myExpectedBean))
    
-     * 
    assertThat(myBean, samePropertyValuesAs(myExpectedBean), "age", "height")
    
+     * 
    {@code
+     * assertThat(myBean, samePropertyValuesAs(myExpectedBean))
+     * assertThat(myBean, samePropertyValuesAs(myExpectedBean), "age", "height")
+     * }
    
      *
-     * @param 
-     *     the matcher type.
-     * @param expectedBean
-     *     the bean against which examined beans are compared
-     * @param ignoredProperties
-     *     do not check any of these named properties.
+     * @param  the matcher value type.
+     * @param expectedBean the bean against which examined beans are compared
+     * @param ignoredProperties do not check any of these named properties.
      * @return The matcher.
      */
     public static  Matcher samePropertyValuesAs(B expectedBean, String... ignoredProperties) {
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java b/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java
index f6328bfad..8effc57ad 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java
@@ -10,14 +10,32 @@
 import static java.util.Arrays.asList;
 
 /**
+ * A matcher for arrays that matches when each item in the examined array satisfies the
+ * corresponding matcher in the specified list of matchers.
+ *
+ * @param  the collection element type
  * @author Steve Freeman 2016 http://www.hamcrest.com
  */
 public class ArrayAsIterableMatcher extends TypeSafeMatcher {
 
+  /**
+   * The matchers to match iterable against
+   */
   protected final TypeSafeDiagnosingMatcher> iterableMatcher;
+
   private final String message;
+
+  /**
+   * The matchers to match items against
+   */
   protected final Collection> matchers;
 
+
+  /**
+   * Constructor, best called from {@link ArrayMatching#arrayContainingInAnyOrder(Matcher[])}.
+   * @see ArrayMatching#arrayContainingInAnyOrder(Matcher[])
+   */
+  @SuppressWarnings("doclint")
   public ArrayAsIterableMatcher(
         TypeSafeDiagnosingMatcher> iterableMatcher,
         Collection> matchers,
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java b/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java
index 86805ae1f..f160ce7be 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/ArrayMatching.java
@@ -11,10 +11,13 @@
 import static org.hamcrest.core.IsEqual.equalTo;
 
 /**
- * @author Steve Freeman 2016 http://www.hamcrest.com
  * Collected helper code for converting matchers between lists and iterables.
+ *
+ * @author Steve Freeman 2016 http://www.hamcrest.com
  */
 public class ArrayMatching {
+  private ArrayMatching() {
+  }
 
   /**
    * Creates a matcher for arrays that matches when the examined array contains at least one item
@@ -187,6 +190,12 @@ public static  Matcher arrayContaining(List> itemMatc
       return new ArrayAsIterableMatcher<>(new IsIterableContainingInOrder<>(itemMatchers), itemMatchers, "");
   }
 
+  /**
+   * Converts item array to corresponding array of equalTo matchers
+   * @param items items to convert
+   * @return list of corresponding equaTo matchers
+   * @param  type of array items
+   */
   public static  List> asEqualMatchers(E[] items) {
     final List> matchers = new ArrayList<>();
     for (E item : items) {
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java b/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java
index 538d56ad6..df63dafc4 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java
@@ -10,12 +10,19 @@
 
 /**
  * Matches if an array contains an item satisfying a nested matcher.
+ *
+ * @param  the array element type
  */
 public class HasItemInArray extends TypeSafeMatcher {
 
     private final Matcher elementMatcher;
     private final TypeSafeDiagnosingMatcher> collectionMatcher;
 
+    /**
+     * Constructor, best called from {@link ArrayMatching}.
+     * @see ArrayMatching#hasItemInArray(Matcher)
+     */
+    @SuppressWarnings("doclint")
     public HasItemInArray(Matcher elementMatcher) {
         this.elementMatcher = elementMatcher;
         this.collectionMatcher = new IsIterableContaining<>(elementMatcher);
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
index 181bcbebb..69d163bd8 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
@@ -9,11 +9,17 @@
 /**
  * Matcher for array whose elements satisfy a sequence of matchers.
  * The array size must equal the number of element matchers.
+ *
+ * @param  the array element type
  */
 public class IsArray extends TypeSafeMatcher {
 
     private final Matcher[] elementMatchers;
 
+    /**
+     * Constructor, best called from {@link #array(Matcher[])}.
+     */
+    @SuppressWarnings("doclint")
     public IsArray(Matcher[] elementMatchers) {
         this.elementMatchers = elementMatchers.clone();
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
index 93490de36..cf374d711 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
@@ -12,6 +12,7 @@
 import static org.hamcrest.core.IsEqual.equalTo;
 
 /**
+ * @param  the collection element type
  * @deprecated As of release 2.1, replaced by {@link ArrayMatching}.
  */
 @Deprecated
@@ -20,6 +21,12 @@ public class IsArrayContainingInAnyOrder extends TypeSafeMatcher {
     private final IsIterableContainingInAnyOrder iterableMatcher;
     private final Collection> matchers;
 
+    /**
+     * Constructor, best called from {@link #arrayContainingInAnyOrder(Object[])},
+     * {@link #arrayContainingInAnyOrder(Matcher[])}, or
+     * {@link #arrayContainingInAnyOrder(Collection)}.
+     */
+    @SuppressWarnings("doclint")
     public IsArrayContainingInAnyOrder(Collection> matchers) {
         this.iterableMatcher = new IsIterableContainingInAnyOrder<>(matchers);
         this.matchers = matchers;
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
index 291ed1db5..51200f7f5 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
@@ -12,6 +12,8 @@
 import static org.hamcrest.core.IsEqual.equalTo;
 
 /**
+ * @param  the array element type
+ *
  * @deprecated As of release 2.1, replaced by {@link ArrayMatching}.
  */
 public class IsArrayContainingInOrder extends TypeSafeMatcher {
@@ -19,6 +21,11 @@ public class IsArrayContainingInOrder extends TypeSafeMatcher {
     private final Collection> matchers;
     private final IsIterableContainingInOrder iterableMatcher;
 
+    /**
+     * Constructor, best called from {@link #arrayContaining(Object[])},
+     * {@link #arrayContaining(Matcher[])}, or {@link #arrayContaining(List)}.
+     */
+    @SuppressWarnings("doclint")
     public IsArrayContainingInOrder(List> matchers) {
         this.iterableMatcher = new IsIterableContainingInOrder<>(matchers);
         this.matchers = matchers;
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
index c0814cc04..5b074a660 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
@@ -7,10 +7,17 @@
 import static org.hamcrest.core.IsEqual.equalTo;
 
 /**
- * Matches if array size satisfies a nested matcher.
+ * Matches if array size satisfies a size matcher.
+ *
+ * @param  the array element type
  */
 public class IsArrayWithSize extends FeatureMatcher {
 
+    /**
+     * Constructor, best called from {@link #emptyArray()},
+     * {@link #arrayWithSize(int)} or {@link #arrayWithSize(Matcher)}.
+     */
+    @SuppressWarnings("doclint")
     public IsArrayWithSize(Matcher sizeMatcher) {
         super(sizeMatcher, "an array with size","array size");
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
index 81c5fc61d..ddf313031 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
@@ -9,9 +9,16 @@
 
 /**
  * Matches if collection size satisfies a nested matcher.
+ *
+ * @param  the collection element type
  */
 public class IsCollectionWithSize extends FeatureMatcher, Integer> {
 
+    /**
+     * Constructor, best called from {@link #hasSize(int)} or
+     * {@link #hasSize(Matcher)}.
+     */
+    @SuppressWarnings("doclint")
     public IsCollectionWithSize(Matcher sizeMatcher) {
       super(sizeMatcher, "a collection with size", "collection size");
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java
index 25e6da2cc..9109d31cb 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyCollection.java
@@ -7,10 +7,19 @@
 import java.util.Collection;
 
 /**
- * Tests if collection is empty.
+ * Tests if a collection is empty.
+ *
+ * @param  the collection element type
  */
 public class IsEmptyCollection extends TypeSafeMatcher> {
 
+    /**
+     * Constructor, best called from {@link #empty()} or
+     * {@link #emptyCollectionOf(Class)}.
+     */
+    public IsEmptyCollection() {
+    }
+
     @Override
     public boolean matchesSafely(Collection item) {
         return item.isEmpty();
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java
index d1dc03946..c5aab514c 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsEmptyIterable.java
@@ -5,10 +5,19 @@
 import org.hamcrest.TypeSafeMatcher;
 
 /**
- * Tests if collection is empty.
+ * Tests if an iterable is empty.
+ *
+ * @param  the iterable element type
  */
 public class IsEmptyIterable extends TypeSafeMatcher> {
 
+    /**
+     * Constructor, best called from {@link #emptyIterable()} or
+     * {@link #emptyIterableOf(Class)}.
+     */
+    public IsEmptyIterable() {
+    }
+
     @Override
     public boolean matchesSafely(Iterable iterable) {
         return !iterable.iterator().hasNext();
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
index f18c2bd65..9ff5f0a7f 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
@@ -7,14 +7,26 @@
 import java.util.Arrays;
 import java.util.Collection;
 
+/**
+ * Tests if a collection contains a matching object.
+ * @param  the type of the objects in the collection
+ */
 public class IsIn extends BaseMatcher {
 
     private final Collection collection;
 
+    /**
+     * Constructor, best called from {@link #in(Collection)}.
+     */
+    @SuppressWarnings("doclint")
     public IsIn(Collection collection) {
         this.collection = collection;
     }
 
+    /**
+     * Constructor, best called from {@link #in(Object[])}.
+     */
+    @SuppressWarnings("doclint")
     public IsIn(T[] elements) {
         collection = Arrays.asList(elements);
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
index 087570cd4..8dc180f8a 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
@@ -11,10 +11,22 @@
 
 import static org.hamcrest.core.IsEqual.equalTo;
 
+/**
+ * Tests if an iterable contains matching elements in any order.
+ *
+ * @param  the type of items in the iterable.
+ */
 public class IsIterableContainingInAnyOrder extends TypeSafeDiagnosingMatcher> {
 
     private final Collection> matchers;
 
+    /**
+     * Constructor, best called from one of the static factory methods.
+     * @see #containsInAnyOrder(Object[])
+     * @see #containsInAnyOrder(Collection)
+     * @see #containsInAnyOrder(Matcher[])
+     */
+    @SuppressWarnings("doclint")
     public IsIterableContainingInAnyOrder(Collection> matchers) {
         this.matchers = matchers;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
index 00b89ea7f..e41c0ce77 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
@@ -11,10 +11,24 @@
 import static java.util.Collections.singletonList;
 import static org.hamcrest.collection.ArrayMatching.asEqualMatchers;
 
+/**
+ * Tests if an iterable contains matching elements in order.
+ *
+ * @param  the type of items in the iterable.
+ */
 public class IsIterableContainingInOrder extends TypeSafeDiagnosingMatcher> {
 
     private final List> matchers;
 
+    /**
+     * Constructor, best called from one of the static factory methods.
+     *
+     * @see #contains(Object[])
+     * @see #contains(Matcher)
+     * @see #contains(Matcher[])
+     * @see #contains(List)
+     */
+    @SuppressWarnings("doclint")
     public IsIterableContainingInOrder(List> matchers) {
         this.matchers = matchers;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
index 6aca721ec..eb1535258 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
@@ -10,9 +10,20 @@
 import static java.util.Arrays.asList;
 import static org.hamcrest.core.IsEqual.equalTo;
 
+/**
+ * Tests if an iterable contains matching elements in relative order.
+ *
+ * @param  the type of items in the iterable.
+ */
 public class IsIterableContainingInRelativeOrder extends TypeSafeDiagnosingMatcher> {
     private final List> matchers;
 
+    /**
+     * Constructor, best called from {@link #containsInRelativeOrder(Object[])} ,
+     * {@link #containsInRelativeOrder(Matcher[])},
+     * or {@link #containsInRelativeOrder(List)}.
+     */
+    @SuppressWarnings("doclint")
     public IsIterableContainingInRelativeOrder(List> matchers) {
         this.matchers = matchers;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java
index 586dfcef6..ea36fb441 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableWithSize.java
@@ -7,8 +7,18 @@
 
 import static org.hamcrest.core.IsEqual.equalTo;
 
+/**
+ * Matches if iterable size satisfies a size matcher.
+ *
+ * @param  the iterable element type
+ */
 public class IsIterableWithSize extends FeatureMatcher, Integer> {
 
+    /**
+     * Constructor, best called from {@link #iterableWithSize(int)} or
+     * {@link #iterableWithSize(Matcher)}.
+     * @param sizeMatcher checks the expected size of the iterable
+     */
     public IsIterableWithSize(Matcher sizeMatcher) {
         super(sizeMatcher, "an iterable with size", "iterable size");
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java b/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
index d81dbd9a5..5a6b3833e 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
@@ -10,11 +10,26 @@
 import static org.hamcrest.core.IsAnything.anything;
 import static org.hamcrest.core.IsEqual.equalTo;
 
+/**
+ * Matches if map keys, values or entries match the value matchers.
+ * @param  the type of the map keys
+ * @param  the type of the map values
+ */
 public class IsMapContaining extends TypeSafeMatcher> {
 
     private final Matcher keyMatcher;
     private final Matcher valueMatcher;
 
+    /**
+     * Constructor, best called from one of the static factory methods.
+     * @see #hasKey(Object) 
+     * @see #hasKey(Matcher) 
+     * @see #hasValue(Object)
+     * @see #hasValue(Matcher)
+     * @see #hasEntry(Object, Object) 
+     * @see #hasEntry(Matcher, Matcher) 
+     */
+    @SuppressWarnings("doclint")
     public IsMapContaining(Matcher keyMatcher, Matcher valueMatcher) {
         this.keyMatcher = keyMatcher;
         this.valueMatcher = valueMatcher;
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
index b4670c329..2e7e422b6 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
@@ -9,10 +9,17 @@
 
 /**
  * Matches if map size satisfies a nested matcher.
+ *
+ * @param  the map key type.
+ * @param  the map value type.
  */
 public final class IsMapWithSize extends FeatureMatcher, Integer> {
 
-    @SuppressWarnings("WeakerAccess")
+    /**
+     * Constructor, best called from {@link #aMapWithSize(int)},
+     * {@link #aMapWithSize(Matcher)}, or {@link #anEmptyMap()}
+     */
+    @SuppressWarnings({"WeakerAccess", "doclint"})
     public IsMapWithSize(Matcher sizeMatcher) {
       super(sizeMatcher, "a map with size", "map size");
     }
@@ -64,10 +71,8 @@ protected Integer featureValueOf(Map actual) {
      * For example:
      * 
    assertThat(myMap, is(anEmptyMap()))
    
      *
-     * @param 
-     *     the map key type.
-     * @param 
-     *     the map value type.
+     * @param  the map key type.
+     * @param  the map value type.
      * @return The matcher.
      */
     public static  Matcher> anEmptyMap() {
diff --git a/hamcrest/src/main/java/org/hamcrest/comparator/ComparatorMatcherBuilder.java b/hamcrest/src/main/java/org/hamcrest/comparator/ComparatorMatcherBuilder.java
index 022e519cf..3f0cbc48d 100644
--- a/hamcrest/src/main/java/org/hamcrest/comparator/ComparatorMatcherBuilder.java
+++ b/hamcrest/src/main/java/org/hamcrest/comparator/ComparatorMatcherBuilder.java
@@ -8,6 +8,10 @@
 
 import static java.lang.Integer.signum;
 
+/**
+ * Builder for matchers that allow matchers to use a corresponding Compartor
+ * @param  the type of the value being compared/matched.
+ */
 public final class ComparatorMatcherBuilder {
 
     private final Comparator comparator;
diff --git a/hamcrest/src/main/java/org/hamcrest/core/AllOf.java b/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
index 549f16817..7b6e917f9 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
@@ -3,22 +3,35 @@
 import org.hamcrest.Description;
 import org.hamcrest.DiagnosingMatcher;
 import org.hamcrest.Matcher;
+import org.hamcrest.collection.ArrayMatching;
 
 import java.util.Arrays;
 
 /**
  * Calculates the logical conjunction of multiple matchers. Evaluation is shortcut, so
  * subsequent matchers are not called if an earlier matcher returns false.
+ *
+ * @param  the matched value type
  */
 public class AllOf extends DiagnosingMatcher {
 
     private final Iterable> matchers;
 
+    /**
+     * Constructor, best called from {@link #allOf(Matcher[])}.
+     * @see #allOf(Matcher[])
+     */
+    @SuppressWarnings("doclint")
     @SafeVarargs
     public AllOf(Matcher ... matchers) {
         this(Arrays.asList(matchers));
     }
 
+    /**
+     * Constructor, best called from {@link #allOf(Iterable)}.
+     * @see #allOf(Iterable)
+     */
+    @SuppressWarnings("doclint")
     public AllOf(Iterable> matchers) {
         this.matchers = matchers;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java b/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
index 91c664d95..ba72140b1 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
@@ -2,20 +2,33 @@
 
 import org.hamcrest.Description;
 import org.hamcrest.Matcher;
+import org.hamcrest.collection.ArrayMatching;
 
 import java.util.Arrays;
 
 /**
  * Calculates the logical disjunction of multiple matchers. Evaluation is shortcut, so
  * subsequent matchers are not called if an earlier matcher returns true.
+ *
+ * @param  the matched value type
  */
 public class AnyOf extends ShortcutCombination {
 
+    /**
+     * Constructor, best called from {@link #anyOf(Matcher[])}.
+     * @see #anyOf(Matcher[]) 
+     */
+    @SuppressWarnings("doclint")
     @SafeVarargs
     public AnyOf(Matcher ... matchers) {
         this(Arrays.asList(matchers));
     }
 
+    /**
+     * Constructor, best called from {@link #anyOf(Iterable)}.
+     * @see #anyOf(Iterable) 
+     */
+    @SuppressWarnings("doclint")
     public AnyOf(Iterable> matchers) {
         super(matchers);
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java b/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
index 52a134aff..ec4370be8 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
@@ -7,14 +7,34 @@
 import java.util.ArrayList;
 
 /**
- * TODO: Finish Class Level Documentation.
+ * Allows matchers of the same type to be combined using
+ * either/or, or
+ * both/and.
+ *
+ * For example:
+ *
+ * 
    {@code  import static org.hamcrest.core.CombinableMatcher.either;
+ * import static org.hamcrest.core.CombinableMatcher.both;
+ * import static org.hamcrest.Matchers.equalTo;
+ * import static org.hamcrest.Matchers.not;
+ *
+ * Matcher either_3_or_4 = either(equalTo(3)).or(equalTo(4));
+ * Matcher neither_3_nor_4 = both(not(equalTo(3))).and(not(equalTo(4)));}
    
  *
  * @param  the type of matcher being combined.
+ * @see #either(Matcher)
+ * @see #both(Matcher)
  */
 public class CombinableMatcher extends TypeSafeDiagnosingMatcher {
 
   private final Matcher matcher;
 
+  /**
+   * Constructor, best called from either or both.
+   * @see #either(Matcher)
+   * @see #both(Matcher) 
+   */
+  @SuppressWarnings("doclint")
   public CombinableMatcher(Matcher matcher) {
     this.matcher = matcher;
   }
@@ -33,10 +53,20 @@ public void describeTo(Description description) {
     description.appendDescriptionOf(matcher);
   }
 
+  /**
+   * Specify the second matcher in a CombinableMatcher pair.
+   * @param other the second matcher
+   * @return the combined matcher
+   */
   public CombinableMatcher and(Matcher other) {
     return new CombinableMatcher<>(new AllOf<>(templatedListWith(other)));
   }
 
+  /**
+   * Specify the second matcher in a CombinableMatcher pair.
+   * @param other the second matcher
+   * @return the combined matcher
+   */
   public CombinableMatcher or(Matcher other) {
     return new CombinableMatcher<>(new AnyOf<>(templatedListWith(other)));
   }
@@ -63,11 +93,21 @@ public static  CombinableBothMatcher both(Matcher matcher
     return new CombinableBothMatcher<>(matcher);
   }
 
+  /**
+   * Allows syntactic sugar of using both and and.
+   * @param  the combined matcher type
+   * @see #both(Matcher)
+   * @see #and(Matcher)
+   */
   public static final class CombinableBothMatcher {
     private final Matcher first;
+
+    @SuppressWarnings("doclint")
     public CombinableBothMatcher(Matcher matcher) {
         this.first = matcher;
     }
+
+    @SuppressWarnings("doclint")
     public CombinableMatcher and(Matcher other) {
       return new CombinableMatcher(first).and(other);
     }
@@ -88,11 +128,21 @@ public static  CombinableEitherMatcher either(Matcher mat
     return new CombinableEitherMatcher<>(matcher);
   }
 
+  /**
+   * Allows syntactic sugar of using either and or.
+   * @param  the combined matcher type
+   * @see #either(Matcher)
+   * @see #or(Matcher)
+   */
   public static final class CombinableEitherMatcher {
     private final Matcher first;
+
+    @SuppressWarnings("doclint")
     public CombinableEitherMatcher(Matcher matcher) {
         this.first = matcher;
     }
+
+    @SuppressWarnings("doclint")
     public CombinableMatcher or(Matcher other) {
       return new CombinableMatcher(first).or(other);
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java b/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java
index b4138d7f6..c89451e66 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/DescribedAs.java
@@ -10,6 +10,8 @@
 
 /**
  * Provides a custom description to another matcher.
+ *
+ * @param  the matched value type
  */
 public class DescribedAs extends BaseMatcher {
 
@@ -19,6 +21,12 @@ public class DescribedAs extends BaseMatcher {
 
     private final static Pattern ARG_PATTERN = Pattern.compile("%([0-9]+)");
 
+    /**
+     * Constructor, best called from {@link #describedAs(String, Matcher, Object...)}.
+     * @param descriptionTemplate the new description for the wrapped matcher
+     * @param matcher the matcher to wrap
+     * @param values optional values to insert into the tokenised description
+     */
     public DescribedAs(String descriptionTemplate, Matcher matcher, Object[] values) {
         this.descriptionTemplate = descriptionTemplate;
         this.matcher = matcher;
@@ -57,18 +65,14 @@ public void describeMismatch(Object item, Description description) {
      * For example:
      * 
    describedAs("a big decimal equal to %0", equalTo(myBigDecimal), myBigDecimal.toPlainString())
    
      *
-     * @param 
-     *     the matcher type.
-     * @param description
-     *     the new description for the wrapped matcher
-     * @param matcher
-     *     the matcher to wrap
-     * @param values
-     *     optional values to insert into the tokenised description
+     * @param  the matcher type.
+     * @param descriptionTemplate the new description for the wrapped matcher
+     * @param matcher the matcher to wrap
+     * @param values optional values to insert into the tokenised description
      * @return The matcher.
      */
-    public static  Matcher describedAs(String description, Matcher matcher, Object... values) {
-        return new DescribedAs<>(description, matcher, values);
+    public static  Matcher describedAs(String descriptionTemplate, Matcher matcher, Object... values) {
+        return new DescribedAs<>(descriptionTemplate, matcher, values);
     }
 
 }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/Every.java b/hamcrest/src/main/java/org/hamcrest/core/Every.java
index 6e25fcda9..bf3d809fb 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/Every.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/Every.java
@@ -4,10 +4,19 @@
 import org.hamcrest.Matcher;
 import org.hamcrest.TypeSafeDiagnosingMatcher;
 
+/**
+ * A matcher that applies a delegate matcher to every item in an  {@link Iterable}.
+ *
+ * @param  the type of the items in the iterable
+ */
 public class Every extends TypeSafeDiagnosingMatcher> {
 
     private final Matcher matcher;
 
+    /**
+     * Constructor, best called from {@link #everyItem(Matcher)}.
+     * @param matcher a matcher used to check every item in the iterable.
+     */
     public Every(Matcher matcher) {
         this.matcher= matcher;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/Is.java b/hamcrest/src/main/java/org/hamcrest/core/Is.java
index a23dd73cb..f5b82c5b7 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/Is.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/Is.java
@@ -12,11 +12,18 @@
  *
  * For example:  assertThat(cheese, equalTo(smelly))
  *          vs.  assertThat(cheese, is(equalTo(smelly)))
+ *
+ * @param  the matched value type
  */
 public class Is extends BaseMatcher {
 
     private final Matcher matcher;
 
+    /**
+     * Constructor, best called from {@link #is(Object)},
+     * {@link #is(Matcher)}, or {@link #isA(Class)}.
+     */
+    @SuppressWarnings("doclint")
     public Is(Matcher matcher) {
         this.matcher = matcher;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java b/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
index 7e23e6893..49ac359a9 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
@@ -6,19 +6,33 @@
 
 /**
  * A matcher that always returns true.
+ *
+ * @param  the matched value type
  */
 public class IsAnything extends BaseMatcher {
 
     private final String message;
 
+    /**
+     * Constructor, best called from {@link #anything()}.
+     */
     public IsAnything() {
         this("ANYTHING");
     }
 
+    /**
+     * Constructor, best called from {@link #anything(String)}.
+     */
+    @SuppressWarnings("doclint")
     public IsAnything(String message) {
         this.message = message;
     }
 
+    /**
+     * Always returns true.
+     * @param o the object against which the matcher is evaluated.
+     * @return true
+     */
     @Override
     public boolean matches(Object o) {
         return true;
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java b/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
index fec503997..821eaf29a 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
@@ -5,6 +5,7 @@
 import org.hamcrest.TypeSafeDiagnosingMatcher;
 
 /**
+ * @param  the collection element type
  * @deprecated As of release 2.1, replaced by {@link IsIterableContaining}.
  */
 @Deprecated
@@ -12,6 +13,14 @@ public class IsCollectionContaining extends TypeSafeDiagnosingMatcher delegate;
 
+    /**
+     * Constructor, best called from one of the static factory methods.
+     * @see #hasItem(Object)
+     * @see #hasItem(Matcher)
+     * @see #hasItems(Object[])
+     * @see #hasItems(Matcher[])
+     */
+    @SuppressWarnings("doclint")
     public IsCollectionContaining(Matcher elementMatcher) {
         this.delegate = new IsIterableContaining<>(elementMatcher);
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java b/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
index ddb91c501..8ff4a20e5 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
@@ -8,12 +8,19 @@
 
 /**
  * Is the value equal to another value, as tested by the
- * {@link java.lang.Object#equals} invokedMethod?
+ * {@link java.lang.Object#equals} method.
+ *
+ * @param  the matched value type
  */
 public class IsEqual extends BaseMatcher {
 
     private final Object expectedValue;
 
+    /**
+     * Constructor, best called from {@link #equalTo(Object)} or
+     * {@link #equalToObject(Object)}.
+     */
+    @SuppressWarnings("doclint")
     public IsEqual(T equalArg) {
         expectedValue = equalArg;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java b/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
index 915e56c3a..2cbd2ec14 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
@@ -10,10 +10,22 @@
 import static org.hamcrest.core.AllOf.allOf;
 import static org.hamcrest.core.IsEqual.equalTo;
 
+/**
+ * Tests if an iterable contains matching elements.
+ * @param  the type of items in the iterable
+ */
 public class IsIterableContaining extends TypeSafeDiagnosingMatcher> {
 
     private final Matcher elementMatcher;
 
+    /**
+     * Constructor, best called from one of the static factory methods.
+     * @see #hasItem(Object)
+     * @see #hasItem(Matcher)
+     * @see #hasItems(Object[])
+     * @see #hasItems(Matcher[])
+     */
+    @SuppressWarnings("doclint")
     public IsIterableContaining(Matcher elementMatcher) {
         this.elementMatcher = elementMatcher;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsNot.java b/hamcrest/src/main/java/org/hamcrest/core/IsNot.java
index 1e5db96e2..20e411505 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsNot.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsNot.java
@@ -8,11 +8,18 @@
 
 /**
  * Calculates the logical negation of a matcher.
+ *
+ * @param  the matched value type
  */
 public class IsNot extends BaseMatcher  {
 
     private final Matcher matcher;
 
+    /**
+     * Constructor, best called from {@link #not(Object)} or
+     * {@link #not(Matcher)}.
+     * @param matcher the matcher to negate
+     */
     public IsNot(Matcher matcher) {
         this.matcher = matcher;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsNull.java b/hamcrest/src/main/java/org/hamcrest/core/IsNull.java
index 6977968ba..f79719f28 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsNull.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsNull.java
@@ -8,9 +8,19 @@
 
 /**
  * Is the value null?
+ *
+ * @param  the matched value type
  */
 public class IsNull extends BaseMatcher {
 
+    /**
+     * Constructor, best called from {@link #nullValue()},
+     * {@link #nullValue(Class)}, {@link #notNullValue()},
+     * or {@link #notNullValue(Class)}.
+     */
+    public IsNull() {
+    }
+
     @Override
     public boolean matches(Object o) {
         return o == null;
@@ -22,11 +32,11 @@ public void describeTo(Description description) {
     }
 
     /**
-     * Creates a matcher that matches if examined object is null.
+     * 
    Creates a matcher that matches if examined object is null.
+     * 
    
      * For example:
-     * 
    assertThat(cheese, is(nullValue())
    
-     *
-     * @return The matcher.
+     * 
    {@code assertThat(cheese, is(nullValue())}
    
+     * @return The matcher
      */
     public static Matcher nullValue() {
         return new IsNull<>();
@@ -46,15 +56,14 @@ public static Matcher notNullValue() {
     }
 
     /**
-     * Creates a matcher that matches if examined object is null. Accepts a
-     * single dummy argument to facilitate type inference.
+     * 
    Creates a matcher that matches if examined object is null>.
+     * Accepts a single dummy argument to facilitate type inference.
+     * 
    
      * For example:
-     * 
    assertThat(cheese, is(nullValue(Cheese.class))
    
+     * 
    {@code assertThat(cheese, is(nullValue(Cheese.class))}
    
      *
-     * @param 
-     *     the matcher type.
-     * @param type
-     *     dummy parameter used to infer the generic type of the returned matcher
+     * @param  the matcher type.
+     * @param type dummy parameter used to infer the generic type of the returned matcher
      * @return The matcher.
      */
     public static  Matcher nullValue(Class type) {
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsSame.java b/hamcrest/src/main/java/org/hamcrest/core/IsSame.java
index 7bd9ef89d..f27f232ab 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsSame.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsSame.java
@@ -6,11 +6,18 @@
 
 /**
  * Is the value the same object as another value?
+ *
+ * @param  the matched value type
  */
 public class IsSame extends BaseMatcher {
 
     private final T object;
 
+    /**
+     * Constructor, best called from {@link #sameInstance(Object)} or
+     * {@link #theInstance(Object)}.
+     * @param object the object to check
+     */
     public IsSame(T object) {
         this.object = object;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/ShortcutCombination.java b/hamcrest/src/main/java/org/hamcrest/core/ShortcutCombination.java
index 7cfd04a7d..b21eaa876 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/ShortcutCombination.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/ShortcutCombination.java
@@ -18,6 +18,16 @@ public ShortcutCombination(Iterable> matchers) {
     @Override
     public abstract void describeTo(Description description);
 
+    /**
+     * Evaluates the argument o against the delegate matchers.
+     *
+     * Evaluation will stop at the first matcher that evaluates to the value of the
+     * shortcut argument.
+     *
+     * @param o the value to check
+     * @param shortcut the match result to be checked against all delegate matchers
+     * @return the value of shortcut if all delegate matchers give the same value
+     */
     protected boolean matches(Object o, boolean shortcut) {
         for (Matcher matcher : matchers) {
             if (matcher.matches(o) == shortcut) {
@@ -27,6 +37,11 @@ protected boolean matches(Object o, boolean shortcut) {
         return !shortcut;
     }
 
+    /**
+     * Describe this matcher to description
+     * @param description the description target
+     * @param operator the separate to use when joining the matcher descriptions
+     */
     public void describeTo(Description description, String operator) {
         description.appendList("(", " " + operator + " ", ")", matchers);
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/StringContains.java b/hamcrest/src/main/java/org/hamcrest/core/StringContains.java
index 3c3cb9cf8..a46f47878 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/StringContains.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/StringContains.java
@@ -7,8 +7,18 @@
  */
 public class StringContains extends SubstringMatcher {
 
+    /**
+     * Constructor, best used with {@link #containsString(String)}.
+     * @param substring the expected substring.
+     */
     public StringContains(String substring) { this(false, substring); }
 
+    /**
+     * Constructor, best used with {@link #containsString(String)}  or
+     * {@link #containsStringIgnoringCase(String)}.
+     * @param ignoringCase whether to ignore case when matching
+     * @param substring the expected substring.
+     */
     public StringContains(boolean ignoringCase, String substring) {
         super("containing", ignoringCase, substring);
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/StringEndsWith.java b/hamcrest/src/main/java/org/hamcrest/core/StringEndsWith.java
index bff915772..9734b3911 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/StringEndsWith.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/StringEndsWith.java
@@ -7,9 +7,19 @@
  */
 public class StringEndsWith extends SubstringMatcher {
 
-    public StringEndsWith(String substring) { this(false, substring); }
+    /**
+     * Constructor, best used with {@link #endsWith(String)}.
+     * @param suffix the expected end of the string.
+     */
+    public StringEndsWith(String suffix) { this(false, suffix); }
 
-    public StringEndsWith(boolean ignoringCase, String substring) { super("ending with", ignoringCase, substring); }
+    /**
+     * Constructor, best used with {@link #endsWith(String)} or
+     * {@link #endsWithIgnoringCase(String)}.
+     * @param ignoringCase whether to ignore case when matching
+     * @param suffix the expected end of the string.
+     */
+    public StringEndsWith(boolean ignoringCase, String suffix) { super("ending with", ignoringCase, suffix); }
 
     @Override
     protected boolean evalSubstringOf(String s) {
diff --git a/hamcrest/src/main/java/org/hamcrest/core/StringRegularExpression.java b/hamcrest/src/main/java/org/hamcrest/core/StringRegularExpression.java
index 38ce1b1d9..790aeb505 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/StringRegularExpression.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/StringRegularExpression.java
@@ -7,12 +7,17 @@
 import org.hamcrest.TypeSafeDiagnosingMatcher;
 
 /**
+ * A matcher that checks a string against a regular expression.
+ *
  * @author borettim
  * @author sf105
- *
  */
 public class StringRegularExpression extends TypeSafeDiagnosingMatcher {
 
+  /**
+   * Constructor, best used from {@link #matchesRegex(String)}.
+   * @param pattern the regular expression to match against
+   */
   protected StringRegularExpression(Pattern pattern) {
     this.pattern = pattern;
   }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/StringStartsWith.java b/hamcrest/src/main/java/org/hamcrest/core/StringStartsWith.java
index 0f1459840..75713d42e 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/StringStartsWith.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/StringStartsWith.java
@@ -7,9 +7,19 @@
  */
 public class StringStartsWith extends SubstringMatcher {
 
-    public StringStartsWith(String substring) { this(false, substring); }
+    /**
+     * Constructor, best used with {@link #startsWith(String)}.
+     * @param prefix the expected start of the string.
+     */
+    public StringStartsWith(String prefix) { this(false, prefix); }
 
-    public StringStartsWith(boolean ignoringCase, String substring) { super("starting with", ignoringCase, substring); }
+    /**
+     * Constructor, best used with {@link #startsWith(String)} or
+     * {@link #startsWithIgnoringCase(String)}.
+     * @param ignoringCase whether to ignore case when matching
+     * @param prefix the expected start of the string.
+     */
+    public StringStartsWith(boolean ignoringCase, String prefix) { super("starting with", ignoringCase, prefix); }
 
     @Override
     protected boolean evalSubstringOf(String s) { return converted(s).startsWith(converted(substring)); }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/SubstringMatcher.java b/hamcrest/src/main/java/org/hamcrest/core/SubstringMatcher.java
index 75625958d..333d995fe 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/SubstringMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/SubstringMatcher.java
@@ -3,6 +3,13 @@
 import org.hamcrest.Description;
 import org.hamcrest.TypeSafeMatcher;
 
+/**
+ * Common behaviour for matchers that check substrings.
+ *
+ * @see StringContains
+ * @see StringEndsWith
+ * @see StringStartsWith
+ */
 public abstract class SubstringMatcher extends TypeSafeMatcher {
 
     // TODO: Replace String with CharSequence to allow for easy interoperability between
@@ -10,8 +17,10 @@ public abstract class SubstringMatcher extends TypeSafeMatcher {
 
     private final String relationship;
     private final boolean ignoringCase;
+    @SuppressWarnings("doclint")
     protected final String substring;
 
+    @SuppressWarnings("doclint")
     protected SubstringMatcher(String relationship, boolean ignoringCase, String substring) {
         this.relationship = relationship;
         this.ignoringCase = ignoringCase;
@@ -41,7 +50,18 @@ public void describeTo(Description description) {
         }
     }
 
+    /**
+     * Helper method to allow subclasses to handle case insensitivity.
+     * @param arg the string to adjust for case
+     * @return the input string in lowercase if ignoring case, otherwise the original string
+     */
     protected String converted(String arg) { return ignoringCase ? arg.toLowerCase() : arg; }
+
+    /**
+     * Checks if the input matches the specific substring.
+     * @param string the string to check
+     * @return the result of the match
+     */
     protected abstract boolean evalSubstringOf(String string);
 
 }
diff --git a/hamcrest/src/main/java/org/hamcrest/io/FileMatchers.java b/hamcrest/src/main/java/org/hamcrest/io/FileMatchers.java
index 77a26591c..ea517f4f3 100644
--- a/hamcrest/src/main/java/org/hamcrest/io/FileMatchers.java
+++ b/hamcrest/src/main/java/org/hamcrest/io/FileMatchers.java
@@ -10,44 +10,86 @@
 
 import static org.hamcrest.core.IsEqual.equalTo;
 
+/**
+ * Matchers for properties of files.
+ */
 public final class FileMatchers {
 
+    private FileMatchers() {
+    }
+
+    /**
+     * A matcher that checks if a directory exists.
+     */
+    @SuppressWarnings("doclint")
     public static Matcher anExistingDirectory() {
         return fileChecker(IS_DIRECTORY, "an existing directory", "is not a directory");
     }
 
+    /**
+     * A matcher that checks if a file or directory exists.
+     */
+    @SuppressWarnings("doclint")
     public static Matcher anExistingFileOrDirectory() {
         return fileChecker(EXISTS, "an existing file or directory", "does not exist");
     }
 
+    /**
+     * A matcher that checks if a file exists.
+     */
+    @SuppressWarnings("doclint")
     public static Matcher anExistingFile() {
         return fileChecker(IS_FILE, "an existing File", "is not a file");
     }
 
+    /**
+     * A matcher that checks if a file is readable.
+     */
+    @SuppressWarnings("doclint")
     public static Matcher aReadableFile() {
         return fileChecker(CAN_READ, "a readable File", "cannot be read");
     }
 
+    /**
+     * A matcher that checks if a directory is writable.
+     */
+    @SuppressWarnings("doclint")
     public static Matcher aWritableFile() {
         return fileChecker(CAN_WRITE, "a writable File", "cannot be written to");
     }
 
+    /**
+     * A matcher that checks if a file has a specific size.
+     */
+    @SuppressWarnings("doclint")
     public static Matcher aFileWithSize(long size) {
         return aFileWithSize(equalTo(size));
     }
 
+    /**
+     * A matcher that checks if a file size matches an expected size.
+     */
+    @SuppressWarnings("doclint")
     public static Matcher aFileWithSize(final Matcher expected) {
         return new FeatureMatcher(expected, "A file with size", "size") {
             @Override protected Long featureValueOf(File actual) { return actual.length(); }
         };
     }
 
+    /**
+     * A matcher that checks if a file name matches an expected name.
+     */
+    @SuppressWarnings("doclint")
     public static Matcher aFileNamed(final Matcher expected) {
         return new FeatureMatcher(expected, "A file with name", "name") {
             @Override protected String featureValueOf(File actual) { return actual.getName(); }
         };
     }
 
+    /**
+     * A matcher that checks if a file canonical path matches an expected path.
+     */
+    @SuppressWarnings("doclint")
     public static Matcher aFileWithCanonicalPath(final Matcher expected) {
         return new FeatureMatcher(expected, "A file with canonical path", "path") {
             @Override protected String featureValueOf(File actual) {
@@ -60,31 +102,59 @@ public static Matcher aFileWithCanonicalPath(final Matcher expecte
         };
     }
 
+    /**
+     * A matcher that checks if a file absolute path matches an expected path.
+     */
+    @SuppressWarnings("doclint")
     public static Matcher aFileWithAbsolutePath(final Matcher expected) {
         return new FeatureMatcher(expected, "A file with absolute path", "path") {
             @Override protected String featureValueOf(File actual) { return actual.getAbsolutePath(); }
         };
     }
 
-    public static interface FileStatus {
+    /**
+     * Checks the status of a {@link File}.
+     */
+    public interface FileStatus {
+        /**
+         * Checks the give file against a status.
+         * @param actual the file to check
+         * @return true if the file status matches, otherwise false.
+         */
         boolean check(File actual);
     }
 
+    /**
+     * Checks if a {@link File} is writable.
+     */
     public static final FileStatus CAN_WRITE = new FileStatus() {
         @Override public boolean check(File actual) { return actual.canWrite(); }
     };
+
+    /**
+     * Checks if a {@link File} is readable.
+     */
     public static final FileStatus CAN_READ = new FileStatus() {
         @Override public boolean check(File actual) { return actual.canRead(); }
     };
 
+    /**
+     * Checks if a {@link File} is a file.
+     */
     public static final FileStatus IS_FILE = new FileStatus() {
         @Override public boolean check(File actual) { return actual.isFile(); }
     };
 
+    /**
+     * Checks if a {@link File} is a directory.
+     */
     public static final FileStatus IS_DIRECTORY = new FileStatus() {
         @Override public boolean check(File actual) { return actual.isDirectory(); }
     };
 
+    /**
+     * Checks if a {@link File} is a exists.
+     */
     public static final FileStatus EXISTS = new FileStatus() {
         @Override public boolean check(File actual) { return actual.exists(); }
     };
diff --git a/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java b/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java
index edb817554..3a3b247f3 100644
--- a/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java
+++ b/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java
@@ -3,15 +3,24 @@
 import org.hamcrest.Description;
 import org.hamcrest.Matcher;
 import org.hamcrest.TypeSafeMatcher;
+import org.hamcrest.collection.ArrayMatching;
 
 import java.math.BigDecimal;
 import java.math.MathContext;
 
+/**
+ * A matcher that checks a {@link BigDecimal} is close to an expected value.
+ */
 public class BigDecimalCloseTo extends TypeSafeMatcher {
 
   private final BigDecimal delta;
   private final BigDecimal value;
 
+  /**
+   * Constructor, best called from {@link #closeTo(BigDecimal, BigDecimal)}.
+   * @see #closeTo(BigDecimal, BigDecimal)
+   */
+  @SuppressWarnings("doclint")
   public BigDecimalCloseTo(BigDecimal value, BigDecimal error) {
       this.delta = error;
       this.value = value;
diff --git a/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java b/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java
index 515f9e9ea..a73e2b71c 100644
--- a/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java
+++ b/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java
@@ -15,6 +15,10 @@ public class IsCloseTo extends TypeSafeMatcher {
     private final double delta;
     private final double value;
 
+    /**
+     * Constructor, best called from {@link #closeTo(double, double)}.
+     */
+    @SuppressWarnings("doclint")
     public IsCloseTo(double value, double error) {
         this.delta = error;
         this.value = value;
diff --git a/hamcrest/src/main/java/org/hamcrest/number/OrderingComparison.java b/hamcrest/src/main/java/org/hamcrest/number/OrderingComparison.java
index c450e22a2..d3fe15453 100644
--- a/hamcrest/src/main/java/org/hamcrest/number/OrderingComparison.java
+++ b/hamcrest/src/main/java/org/hamcrest/number/OrderingComparison.java
@@ -3,6 +3,9 @@
 import org.hamcrest.Matcher;
 import org.hamcrest.comparator.ComparatorMatcherBuilder;
 
+/**
+ * Static methods for building ordering comparisons.
+ */
 public class OrderingComparison {
 
     private OrderingComparison() {
diff --git a/hamcrest/src/main/java/org/hamcrest/object/HasEqualValues.java b/hamcrest/src/main/java/org/hamcrest/object/HasEqualValues.java
index 2d0479cdb..dfd55c4f0 100644
--- a/hamcrest/src/main/java/org/hamcrest/object/HasEqualValues.java
+++ b/hamcrest/src/main/java/org/hamcrest/object/HasEqualValues.java
@@ -12,11 +12,19 @@
 
 import static java.lang.String.format;
 
+/**
+ * A matcher that checks if an object as equal fields values to an expected object.
+ * @param  the type of the object being matched.
+ */
 public class HasEqualValues extends TypeSafeDiagnosingMatcher {
 
     private final T expectedObject;
     private final List fieldMatchers;
 
+    /**
+     * Constructor
+     * @param expectedObject the object with expected field values.
+     */
     public HasEqualValues(T expectedObject) {
         super(expectedObject.getClass());
         this.expectedObject = expectedObject;
diff --git a/hamcrest/src/main/java/org/hamcrest/object/HasToString.java b/hamcrest/src/main/java/org/hamcrest/object/HasToString.java
index 74261761e..17de0baf2 100644
--- a/hamcrest/src/main/java/org/hamcrest/object/HasToString.java
+++ b/hamcrest/src/main/java/org/hamcrest/object/HasToString.java
@@ -5,8 +5,13 @@
 
 import static org.hamcrest.core.IsEqual.equalTo;
 
+/**
+ * A Matcher that checks the output of the toString() method.
+ * @param  The Matcher type.
+ */
 public class HasToString extends FeatureMatcher {
 
+    @SuppressWarnings("doclint")
     public HasToString(Matcher toStringMatcher) {
       super(toStringMatcher, "with toString()", "toString()");
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java b/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java
index ab7d8a242..221244c15 100644
--- a/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java
+++ b/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java
@@ -4,10 +4,19 @@
 import org.hamcrest.Matcher;
 import org.hamcrest.TypeSafeMatcher;
 
+/**
+ * A matcher of {@link Class} that matches when the specified baseType is
+ * assignable from the examined class.
+ * @param  the type of the class
+ */
 public class IsCompatibleType extends TypeSafeMatcher> {
 
     private final Class type;
 
+    /**
+     * Constructor, best called from {@link #typeCompatibleWith(Class)}.
+     */
+    @SuppressWarnings("doclint")
     public IsCompatibleType(Class type) {
         this.type = type;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java b/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java
index 5ab8b3063..5a7181138 100644
--- a/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java
+++ b/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java
@@ -14,6 +14,11 @@ public class IsEventFrom extends TypeSafeDiagnosingMatcher {
     private final Class eventClass;
     private final Object source;
 
+    /**
+     * Constructor, best called from {@link #eventFrom(Object)} or
+     * {@link #eventFrom(Class, Object)}.
+     */
+    @SuppressWarnings("doclint")
     public IsEventFrom(Class eventClass, Object source) {
         this.eventClass = eventClass;
         this.source = source;
diff --git a/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java b/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java
index 496d3fec5..cf82a3a1c 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java
@@ -3,18 +3,23 @@
 import org.hamcrest.FeatureMatcher;
 import org.hamcrest.Matcher;
 
+import java.math.BigDecimal;
+
 import static org.hamcrest.CoreMatchers.equalTo;
 
 /**
+ * A Matcher that checks the length of a string.
  * @author Marco Leichsenring
  * @author Steve Freeman
  */
 public class CharSequenceLength extends FeatureMatcher {
 
+
     /**
-     * @param lengthMatcher         The matcher to apply to the feature
+     * Constructor, best called from {@link #hasLength(Matcher)}.
+     * @see #hasLength(Matcher)
      */
-    @SuppressWarnings("WeakerAccess")
+    @SuppressWarnings({"WeakerAccess", "doclint"})
     public CharSequenceLength(Matcher lengthMatcher) {
         super(lengthMatcher, "a CharSequence with length", "length");
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java b/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java
index 544c203b0..c04a820fc 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java
@@ -14,6 +14,10 @@ public class IsEqualCompressingWhiteSpace extends TypeSafeMatcher {
 
     private final String string;
 
+    /**
+     * Constructor, best called from {@link #equalToCompressingWhiteSpace(String)}.
+     */
+    @SuppressWarnings("doclint")
     public IsEqualCompressingWhiteSpace(String string) {
         if (string == null) {
             throw new IllegalArgumentException("Non-null value required");
@@ -21,6 +25,7 @@ public IsEqualCompressingWhiteSpace(String string) {
         this.string = string;
     }
 
+    @SuppressWarnings("doclint")
     protected String getString() {
         return string;
     }
@@ -42,6 +47,7 @@ public void describeTo(Description description) {
                 .appendText(" compressing white space");
     }
 
+    @SuppressWarnings("doclint")
     public String stripSpaces(String toBeStripped) {
         return toBeStripped.replaceAll("[\\p{Z}\\p{C}]+", " ").trim();
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java b/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java
index 1ecba2579..3cacf5a96 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java
@@ -14,6 +14,10 @@ public class IsEqualIgnoringCase extends TypeSafeMatcher {
 
     private final String string;
 
+    /**
+     * Constructor, best called from {@link #equalToIgnoringCase(String)}.
+     */
+    @SuppressWarnings("doclint")
     public IsEqualIgnoringCase(String string) {
         if (string == null) {
             throw new IllegalArgumentException("Non-null value required");
diff --git a/hamcrest/src/main/java/org/hamcrest/text/MatchesPattern.java b/hamcrest/src/main/java/org/hamcrest/text/MatchesPattern.java
index 2b3ebefe2..a211f96b4 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/MatchesPattern.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/MatchesPattern.java
@@ -6,10 +6,18 @@
 
 import java.util.regex.Pattern;
 
+/**
+ * Tests if a string matches a regular expression.
+ */
 public class MatchesPattern extends TypeSafeMatcher {
 
     private final Pattern pattern;
 
+    /**
+     * Constructor, best called from {@link #matchesPattern(String)} or
+     * {@link #matchesPattern(Pattern)}.
+     * @param pattern the regular expression to match
+     */
     public MatchesPattern(Pattern pattern) {
         this.pattern = pattern;
     }
@@ -40,8 +48,7 @@ public static Matcher matchesPattern(Pattern pattern) {
      * Creates a matcher of {@link java.lang.String} that matches when the examined string
      * exactly matches the given regular expression, treated as a {@link java.util.regex.Pattern}.
      *
-     * @param regex
-     *     the regex to match.
+     * @param regex the regex to match.
      * @return The matcher.
      */
     public static Matcher matchesPattern(String regex) {
diff --git a/hamcrest/src/main/java/org/hamcrest/text/StringContainsInOrder.java b/hamcrest/src/main/java/org/hamcrest/text/StringContainsInOrder.java
index 9e2ec30a6..8b70f2943 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/StringContainsInOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/StringContainsInOrder.java
@@ -6,10 +6,17 @@
 
 import java.util.Arrays;
 
+/**
+ * Tests if a string contains the given substrings in order.
+ */
 public class StringContainsInOrder extends TypeSafeMatcher {
 
     private final Iterable substrings;
 
+    /**
+     * Constructor, best called from {@link #stringContainsInOrder(Iterable)}
+     * @param substrings the substrings that must be contained within matching strings
+     */
     public StringContainsInOrder(Iterable substrings) {
         this.substrings = substrings;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/xml/HasXPath.java b/hamcrest/src/main/java/org/hamcrest/xml/HasXPath.java
index 6b220f4f4..b86af5da5 100644
--- a/hamcrest/src/main/java/org/hamcrest/xml/HasXPath.java
+++ b/hamcrest/src/main/java/org/hamcrest/xml/HasXPath.java
@@ -23,6 +23,10 @@
  */
 public class HasXPath extends TypeSafeDiagnosingMatcher {
 
+    /**
+     * Null NamespaceContext, used to document deliberate use
+     * of no namespace.
+     */
     public static final NamespaceContext NO_NAMESPACE_CONTEXT = null;
     private static final IsAnything WITH_ANY_CONTENT = new IsAnything<>("");
     private static final Condition.Step NODE_EXISTS = nodeExists();
@@ -32,20 +36,17 @@ public class HasXPath extends TypeSafeDiagnosingMatcher {
     private final QName evaluationMode;
 
     /**
-     * @param xPathExpression XPath expression.
-     * @param valueMatcher Matcher to use at given XPath.
-     *                     May be null to specify that the XPath must exist but the value is irrelevant.
+     * Constructor, best called from one of the hasXPath static factory methods.
      */
+    @SuppressWarnings("doclint")
     public HasXPath(String xPathExpression, Matcher valueMatcher) {
         this(xPathExpression, NO_NAMESPACE_CONTEXT, valueMatcher);
     }
 
     /**
-     * @param xPathExpression XPath expression.
-     * @param namespaceContext Resolves XML namespace prefixes in the XPath expression
-     * @param valueMatcher Matcher to use at given XPath.
-     *                     May be null to specify that the XPath must exist but the value is irrelevant.
+     * Constructor, best called from one of the hasXPath static factory methods.
      */
+    @SuppressWarnings("doclint")
     public HasXPath(String xPathExpression, NamespaceContext namespaceContext, Matcher valueMatcher) {
         this(xPathExpression, namespaceContext, valueMatcher, STRING);
     }

From cf8d6ba4f39e50ad9d31f0b4e79787a2ebf390f0 Mon Sep 17 00:00:00 2001
From: Joe Schmetzer 
Date: Sun, 11 Aug 2024 10:17:16 +1000
Subject: [PATCH 09/11] Fix javadoc error

---
 hamcrest/src/main/java/org/hamcrest/core/IsNull.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsNull.java b/hamcrest/src/main/java/org/hamcrest/core/IsNull.java
index f79719f28..4cc390bad 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsNull.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsNull.java
@@ -56,7 +56,7 @@ public static Matcher notNullValue() {
     }
 
     /**
-     * 
    Creates a matcher that matches if examined object is null>.
+     * 
    Creates a matcher that matches if examined object is null.
      * Accepts a single dummy argument to facilitate type inference.
      * 
    
      * For example:

From 8047047693c53d110b69e2976ed8187da2939923 Mon Sep 17 00:00:00 2001
From: Joe Schmetzer 
Date: Wed, 14 Aug 2024 13:46:08 +1000
Subject: [PATCH 10/11] Fix javadoc warnings for older jdks

---
 .../main/java/org/hamcrest/Description.java   |  7 ++-
 .../java/org/hamcrest/beans/HasProperty.java  |  2 +-
 .../hamcrest/beans/HasPropertyWithValue.java  |  7 ++-
 .../hamcrest/beans/SamePropertyValuesAs.java  |  4 +-
 .../collection/ArrayAsIterableMatcher.java    |  4 +-
 .../hamcrest/collection/HasItemInArray.java   |  2 +-
 .../java/org/hamcrest/collection/IsArray.java |  2 +-
 .../IsArrayContainingInAnyOrder.java          |  5 +--
 .../collection/IsArrayContainingInOrder.java  |  2 +-
 .../hamcrest/collection/IsArrayWithSize.java  |  2 +-
 .../collection/IsCollectionWithSize.java      |  5 +--
 .../java/org/hamcrest/collection/IsIn.java    |  4 +-
 .../IsIterableContainingInAnyOrder.java       |  4 +-
 .../IsIterableContainingInOrder.java          |  4 +-
 .../IsIterableContainingInRelativeOrder.java  |  5 +--
 .../hamcrest/collection/IsMapContaining.java  |  6 ++-
 .../hamcrest/collection/IsMapWithSize.java    |  7 +--
 .../main/java/org/hamcrest/core/AllOf.java    |  4 +-
 .../main/java/org/hamcrest/core/AnyOf.java    |  4 +-
 .../org/hamcrest/core/CombinableMatcher.java  | 36 +++++++++------
 .../src/main/java/org/hamcrest/core/Is.java   |  5 +--
 .../java/org/hamcrest/core/IsAnything.java    |  2 +-
 .../hamcrest/core/IsCollectionContaining.java |  2 +-
 .../main/java/org/hamcrest/core/IsEqual.java  |  5 +--
 .../hamcrest/core/IsIterableContaining.java   |  2 +-
 .../org/hamcrest/core/SubstringMatcher.java   |  9 +++-
 .../internal/ReflectiveTypeFinder.java        | 44 ++++++++++++-------
 .../java/org/hamcrest/io/FileMatchers.java    | 25 ++++++-----
 .../hamcrest/number/BigDecimalCloseTo.java    |  3 +-
 .../java/org/hamcrest/number/IsCloseTo.java   |  6 +--
 .../java/org/hamcrest/object/HasToString.java |  5 ++-
 .../org/hamcrest/object/IsCompatibleType.java |  5 +--
 .../java/org/hamcrest/object/IsEventFrom.java |  6 +--
 .../org/hamcrest/text/CharSequenceLength.java |  3 +-
 .../text/IsEqualCompressingWhiteSpace.java    | 13 ++++--
 .../hamcrest/text/IsEqualIgnoringCase.java    |  2 +-
 .../main/java/org/hamcrest/xml/HasXPath.java  | 16 +++----
 37 files changed, 162 insertions(+), 107 deletions(-)

diff --git a/hamcrest/src/main/java/org/hamcrest/Description.java b/hamcrest/src/main/java/org/hamcrest/Description.java
index 4f630f6c4..31031742d 100644
--- a/hamcrest/src/main/java/org/hamcrest/Description.java
+++ b/hamcrest/src/main/java/org/hamcrest/Description.java
@@ -80,8 +80,13 @@ Description appendList(String start, String separator, String end,
     /**
      * A description that consumes input but does nothing.
      */
-    @SuppressWarnings("doclint")
     final class NullDescription implements Description {
+        /**
+         * Constructor.
+         */
+        public NullDescription() {
+        }
+
         @Override
         public Description appendDescriptionOf(SelfDescribing value) {
             return this;
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java b/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
index b4db81f34..cce9a8b3c 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/HasProperty.java
@@ -21,9 +21,9 @@ public class HasProperty extends TypeSafeMatcher {
 
     /**
      * Constructor, best called from {@link #hasProperty(String)}.
+     * @param propertyName the name of the property
      * @see #hasProperty(String) 
      */
-    @SuppressWarnings("doclint")
     public HasProperty(String propertyName) {
         this.propertyName = propertyName;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java b/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
index 32f794eb1..a734f8000 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/HasPropertyWithValue.java
@@ -77,8 +77,9 @@ public class HasPropertyWithValue extends TypeSafeDiagnosingMatcher {
     /**
      * Constructor, best called from {@link #hasProperty(String, Matcher)} or
      * {@link #hasPropertyAtPath(String, Matcher)}.
+     * @param propertyName the name of the property
+     * @param valueMatcher matcher for the expected value
      */
-    @SuppressWarnings("doclint")
     public HasPropertyWithValue(String propertyName, Matcher valueMatcher) {
         this(propertyName, valueMatcher, " property '%s' ");
     }
@@ -86,8 +87,10 @@ public HasPropertyWithValue(String propertyName, Matcher valueMatcher) {
     /**
      * Constructor, best called from {@link #hasProperty(String, Matcher)} or
      * {@link #hasPropertyAtPath(String, Matcher)}.
+     * @param propertyName the name of the property
+     * @param valueMatcher matcher for the expected value
+     * @param messageFormat format string for the description
      */
-    @SuppressWarnings("doclint")
     public HasPropertyWithValue(String propertyName, Matcher valueMatcher, String messageFormat) {
         this.propertyName = propertyName;
         this.valueMatcher = nastyGenericsWorkaround(valueMatcher);
diff --git a/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java b/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
index 958289a06..94f4dba15 100644
--- a/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
+++ b/hamcrest/src/main/java/org/hamcrest/beans/SamePropertyValuesAs.java
@@ -28,8 +28,10 @@ public class SamePropertyValuesAs extends DiagnosingMatcher {
 
     /**
      * Constructor, best called from {@link #samePropertyValuesAs(Object, String...)}.
+     * @param expectedBean the bean object with the expected values
+     * @param ignoredProperties list of property names that should be excluded from the match
      */
-    @SuppressWarnings({"WeakerAccess", "doclint"})
+    @SuppressWarnings("WeakerAccess")
     public SamePropertyValuesAs(T expectedBean, List ignoredProperties) {
         PropertyDescriptor[] descriptors = propertyDescriptorsFor(expectedBean, Object.class);
         this.expectedBean = expectedBean;
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java b/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java
index 8effc57ad..5ea3e2d3e 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/ArrayAsIterableMatcher.java
@@ -33,9 +33,11 @@ public class ArrayAsIterableMatcher extends TypeSafeMatcher {
 
   /**
    * Constructor, best called from {@link ArrayMatching#arrayContainingInAnyOrder(Matcher[])}.
+   * @param iterableMatcher the iterable matchers
+   * @param matchers the matchers
+   * @param message the description of this matcher
    * @see ArrayMatching#arrayContainingInAnyOrder(Matcher[])
    */
-  @SuppressWarnings("doclint")
   public ArrayAsIterableMatcher(
         TypeSafeDiagnosingMatcher> iterableMatcher,
         Collection> matchers,
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java b/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java
index df63dafc4..102565b75 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/HasItemInArray.java
@@ -20,9 +20,9 @@ public class HasItemInArray extends TypeSafeMatcher {
 
     /**
      * Constructor, best called from {@link ArrayMatching}.
+     * @param elementMatcher matcher for the expected item
      * @see ArrayMatching#hasItemInArray(Matcher)
      */
-    @SuppressWarnings("doclint")
     public HasItemInArray(Matcher elementMatcher) {
         this.elementMatcher = elementMatcher;
         this.collectionMatcher = new IsIterableContaining<>(elementMatcher);
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
index 69d163bd8..fb123bd39 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArray.java
@@ -18,8 +18,8 @@ public class IsArray extends TypeSafeMatcher {
 
     /**
      * Constructor, best called from {@link #array(Matcher[])}.
+     * @param elementMatchers matchers for expected values
      */
-    @SuppressWarnings("doclint")
     public IsArray(Matcher[] elementMatchers) {
         this.elementMatchers = elementMatchers.clone();
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
index cf374d711..82b4b59ce 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInAnyOrder.java
@@ -23,10 +23,9 @@ public class IsArrayContainingInAnyOrder extends TypeSafeMatcher {
 
     /**
      * Constructor, best called from {@link #arrayContainingInAnyOrder(Object[])},
-     * {@link #arrayContainingInAnyOrder(Matcher[])}, or
-     * {@link #arrayContainingInAnyOrder(Collection)}.
+     * {@link #arrayContainingInAnyOrder(Matcher[])}, or {@link #arrayContainingInAnyOrder(Collection)}.
+     * @param matchers matchers for expected values
      */
-    @SuppressWarnings("doclint")
     public IsArrayContainingInAnyOrder(Collection> matchers) {
         this.iterableMatcher = new IsIterableContainingInAnyOrder<>(matchers);
         this.matchers = matchers;
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
index 51200f7f5..3c748cfbe 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayContainingInOrder.java
@@ -24,8 +24,8 @@ public class IsArrayContainingInOrder extends TypeSafeMatcher {
     /**
      * Constructor, best called from {@link #arrayContaining(Object[])},
      * {@link #arrayContaining(Matcher[])}, or {@link #arrayContaining(List)}.
+     * @param matchers matchers for expected values
      */
-    @SuppressWarnings("doclint")
     public IsArrayContainingInOrder(List> matchers) {
         this.iterableMatcher = new IsIterableContainingInOrder<>(matchers);
         this.matchers = matchers;
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
index 5b074a660..9c2dbb85c 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsArrayWithSize.java
@@ -16,8 +16,8 @@ public class IsArrayWithSize extends FeatureMatcher {
     /**
      * Constructor, best called from {@link #emptyArray()},
      * {@link #arrayWithSize(int)} or {@link #arrayWithSize(Matcher)}.
+     * @param sizeMatcher the expected size
      */
-    @SuppressWarnings("doclint")
     public IsArrayWithSize(Matcher sizeMatcher) {
         super(sizeMatcher, "an array with size","array size");
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
index ddf313031..ce403a7d7 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsCollectionWithSize.java
@@ -15,10 +15,9 @@
 public class IsCollectionWithSize extends FeatureMatcher, Integer> {
 
     /**
-     * Constructor, best called from {@link #hasSize(int)} or
-     * {@link #hasSize(Matcher)}.
+     * Constructor, best called from {@link #hasSize(int)} or {@link #hasSize(Matcher)}.
+     * @param sizeMatcher the expected size
      */
-    @SuppressWarnings("doclint")
     public IsCollectionWithSize(Matcher sizeMatcher) {
       super(sizeMatcher, "a collection with size", "collection size");
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
index 9ff5f0a7f..2be7b2fc5 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIn.java
@@ -17,16 +17,16 @@ public class IsIn extends BaseMatcher {
 
     /**
      * Constructor, best called from {@link #in(Collection)}.
+     * @param collection the expected element matchers
      */
-    @SuppressWarnings("doclint")
     public IsIn(Collection collection) {
         this.collection = collection;
     }
 
     /**
      * Constructor, best called from {@link #in(Object[])}.
+     * @param elements the expected elements
      */
-    @SuppressWarnings("doclint")
     public IsIn(T[] elements) {
         collection = Arrays.asList(elements);
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
index 8dc180f8a..84c744d4b 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInAnyOrder.java
@@ -21,12 +21,12 @@ public class IsIterableContainingInAnyOrder extends TypeSafeDiagnosingMatcher
     private final Collection> matchers;
 
     /**
-     * Constructor, best called from one of the static factory methods.
+     * Constructor, best called from one of the static "containsInAnyOrder" factory methods.
+     * @param matchers the matchers
      * @see #containsInAnyOrder(Object[])
      * @see #containsInAnyOrder(Collection)
      * @see #containsInAnyOrder(Matcher[])
      */
-    @SuppressWarnings("doclint")
     public IsIterableContainingInAnyOrder(Collection> matchers) {
         this.matchers = matchers;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
index e41c0ce77..dfb9d1289 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInOrder.java
@@ -21,14 +21,14 @@ public class IsIterableContainingInOrder extends TypeSafeDiagnosingMatcher> matchers;
 
     /**
-     * Constructor, best called from one of the static factory methods.
+     * Constructor, best called from one of the static "contains" factory methods.
+     * @param matchers the matchers
      *
      * @see #contains(Object[])
      * @see #contains(Matcher)
      * @see #contains(Matcher[])
      * @see #contains(List)
      */
-    @SuppressWarnings("doclint")
     public IsIterableContainingInOrder(List> matchers) {
         this.matchers = matchers;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
index eb1535258..5d39f7527 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsIterableContainingInRelativeOrder.java
@@ -20,10 +20,9 @@ public class IsIterableContainingInRelativeOrder extends TypeSafeDiagnosingMa
 
     /**
      * Constructor, best called from {@link #containsInRelativeOrder(Object[])} ,
-     * {@link #containsInRelativeOrder(Matcher[])},
-     * or {@link #containsInRelativeOrder(List)}.
+     * {@link #containsInRelativeOrder(Matcher[])}, or {@link #containsInRelativeOrder(List)}.
+     * @param matchers the matchers
      */
-    @SuppressWarnings("doclint")
     public IsIterableContainingInRelativeOrder(List> matchers) {
         this.matchers = matchers;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java b/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
index 5a6b3833e..1c0d38de1 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsMapContaining.java
@@ -21,7 +21,10 @@ public class IsMapContaining extends TypeSafeMatcher valueMatcher;
 
     /**
-     * Constructor, best called from one of the static factory methods.
+     * Constructor, best called from one of the static factory methods (hasKey, hasValue,
+     * or hasEntry).
+     * @param keyMatcher matcher for expected keys
+     * @param valueMatcher matcher for expected values
      * @see #hasKey(Object) 
      * @see #hasKey(Matcher) 
      * @see #hasValue(Object)
@@ -29,7 +32,6 @@ public class IsMapContaining extends TypeSafeMatcher keyMatcher, Matcher valueMatcher) {
         this.keyMatcher = keyMatcher;
         this.valueMatcher = valueMatcher;
diff --git a/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java b/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
index 2e7e422b6..cce315b09 100644
--- a/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
+++ b/hamcrest/src/main/java/org/hamcrest/collection/IsMapWithSize.java
@@ -16,10 +16,11 @@
 public final class IsMapWithSize extends FeatureMatcher, Integer> {
 
     /**
-     * Constructor, best called from {@link #aMapWithSize(int)},
-     * {@link #aMapWithSize(Matcher)}, or {@link #anEmptyMap()}
+     * Constructor, best called from {@link #aMapWithSize(int)}, {@link #aMapWithSize(Matcher)},
+     * or {@link #anEmptyMap()}.
+     * @param sizeMatcher matcher for the expected size of the map
      */
-    @SuppressWarnings({"WeakerAccess", "doclint"})
+    @SuppressWarnings("WeakerAccess")
     public IsMapWithSize(Matcher sizeMatcher) {
       super(sizeMatcher, "a map with size", "map size");
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/AllOf.java b/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
index 7b6e917f9..8d43b84a8 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/AllOf.java
@@ -19,9 +19,9 @@ public class AllOf extends DiagnosingMatcher {
 
     /**
      * Constructor, best called from {@link #allOf(Matcher[])}.
+     * @param matchers the matchers
      * @see #allOf(Matcher[])
      */
-    @SuppressWarnings("doclint")
     @SafeVarargs
     public AllOf(Matcher ... matchers) {
         this(Arrays.asList(matchers));
@@ -29,9 +29,9 @@ public AllOf(Matcher ... matchers) {
 
     /**
      * Constructor, best called from {@link #allOf(Iterable)}.
+     * @param matchers the matchers
      * @see #allOf(Iterable)
      */
-    @SuppressWarnings("doclint")
     public AllOf(Iterable> matchers) {
         this.matchers = matchers;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java b/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
index ba72140b1..0b08488c6 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/AnyOf.java
@@ -16,9 +16,9 @@ public class AnyOf extends ShortcutCombination {
 
     /**
      * Constructor, best called from {@link #anyOf(Matcher[])}.
+     * @param matchers the matchers
      * @see #anyOf(Matcher[]) 
      */
-    @SuppressWarnings("doclint")
     @SafeVarargs
     public AnyOf(Matcher ... matchers) {
         this(Arrays.asList(matchers));
@@ -26,9 +26,9 @@ public AnyOf(Matcher ... matchers) {
 
     /**
      * Constructor, best called from {@link #anyOf(Iterable)}.
+     * @param matchers the matchers
      * @see #anyOf(Iterable) 
      */
-    @SuppressWarnings("doclint")
     public AnyOf(Iterable> matchers) {
         super(matchers);
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java b/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
index ec4370be8..f17c9afb6 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/CombinableMatcher.java
@@ -31,10 +31,10 @@ public class CombinableMatcher extends TypeSafeDiagnosingMatcher {
 
   /**
    * Constructor, best called from either or both.
+   * @param matcher the starting matcher
    * @see #either(Matcher)
    * @see #both(Matcher) 
    */
-  @SuppressWarnings("doclint")
   public CombinableMatcher(Matcher matcher) {
     this.matcher = matcher;
   }
@@ -83,10 +83,8 @@ private ArrayList> templatedListWith(Matcher other
    * For example:
    * 
    assertThat("fab", both(containsString("a")).and(containsString("b")))
    
    *
-   * @param 
-   *     the matcher type.
-   * @param matcher
-   *     the matcher to combine, and both must pass.
+   * @param  the matcher type.
+   * @param matcher the matcher to combine, and both must pass.
    * @return The matcher.
    */
   public static  CombinableBothMatcher both(Matcher matcher) {
@@ -102,12 +100,19 @@ public static  CombinableBothMatcher both(Matcher matcher
   public static final class CombinableBothMatcher {
     private final Matcher first;
 
-    @SuppressWarnings("doclint")
+    /**
+     * Constructor, best called from {@link #both(Matcher)}.
+     * @param matcher the first matcher
+     */
     public CombinableBothMatcher(Matcher matcher) {
         this.first = matcher;
     }
 
-    @SuppressWarnings("doclint")
+    /**
+     * Specify the second matcher in a CombinableMatcher pair.
+     * @param other the second matcher
+     * @return the combined matcher
+     */
     public CombinableMatcher and(Matcher other) {
       return new CombinableMatcher(first).and(other);
     }
@@ -118,10 +123,8 @@ public CombinableMatcher and(Matcher other) {
    * For example:
    * 
    assertThat("fan", either(containsString("a")).or(containsString("b")))
    
    *
-   * @param 
-   *     the matcher type.
-   * @param matcher
-   *     the matcher to combine, and either must pass.
+   * @param  the matcher type.
+   * @param matcher the matcher to combine, and either must pass.
    * @return The matcher.
    */
   public static  CombinableEitherMatcher either(Matcher matcher) {
@@ -137,12 +140,19 @@ public static  CombinableEitherMatcher either(Matcher mat
   public static final class CombinableEitherMatcher {
     private final Matcher first;
 
-    @SuppressWarnings("doclint")
+    /**
+     * Constructor, best called from {@link #either(Matcher)}
+     * @param matcher the matcher
+     */
     public CombinableEitherMatcher(Matcher matcher) {
         this.first = matcher;
     }
 
-    @SuppressWarnings("doclint")
+    /**
+     * Specify the second matcher in a CombinableMatcher pair.
+     * @param other the second matcher
+     * @return the combined matcher
+     */
     public CombinableMatcher or(Matcher other) {
       return new CombinableMatcher(first).or(other);
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/Is.java b/hamcrest/src/main/java/org/hamcrest/core/Is.java
index f5b82c5b7..3fc323322 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/Is.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/Is.java
@@ -20,10 +20,9 @@ public class Is extends BaseMatcher {
     private final Matcher matcher;
 
     /**
-     * Constructor, best called from {@link #is(Object)},
-     * {@link #is(Matcher)}, or {@link #isA(Class)}.
+     * Constructor, best called from {@link #is(Object)}, {@link #is(Matcher)}, or {@link #isA(Class)}.
+     * @param matcher the matcher to wrap
      */
-    @SuppressWarnings("doclint")
     public Is(Matcher matcher) {
         this.matcher = matcher;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java b/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
index 49ac359a9..9d1a51b86 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsAnything.java
@@ -22,8 +22,8 @@ public IsAnything() {
 
     /**
      * Constructor, best called from {@link #anything(String)}.
+     * @param message matcher description
      */
-    @SuppressWarnings("doclint")
     public IsAnything(String message) {
         this.message = message;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java b/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
index 821eaf29a..f3279bbd4 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsCollectionContaining.java
@@ -15,12 +15,12 @@ public class IsCollectionContaining extends TypeSafeDiagnosingMatcher elementMatcher) {
         this.delegate = new IsIterableContaining<>(elementMatcher);
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java b/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
index 8ff4a20e5..388ac52fc 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsEqual.java
@@ -17,10 +17,9 @@ public class IsEqual extends BaseMatcher {
     private final Object expectedValue;
 
     /**
-     * Constructor, best called from {@link #equalTo(Object)} or
-     * {@link #equalToObject(Object)}.
+     * Constructor, best called from {@link #equalTo(Object)} or {@link #equalToObject(Object)}.
+     * @param equalArg the expected value
      */
-    @SuppressWarnings("doclint")
     public IsEqual(T equalArg) {
         expectedValue = equalArg;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java b/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
index 2cbd2ec14..070e3e95b 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/IsIterableContaining.java
@@ -20,12 +20,12 @@ public class IsIterableContaining extends TypeSafeDiagnosingMatcher elementMatcher) {
         this.elementMatcher = elementMatcher;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/core/SubstringMatcher.java b/hamcrest/src/main/java/org/hamcrest/core/SubstringMatcher.java
index 333d995fe..80b6a4fe1 100644
--- a/hamcrest/src/main/java/org/hamcrest/core/SubstringMatcher.java
+++ b/hamcrest/src/main/java/org/hamcrest/core/SubstringMatcher.java
@@ -17,10 +17,15 @@ public abstract class SubstringMatcher extends TypeSafeMatcher {
 
     private final String relationship;
     private final boolean ignoringCase;
-    @SuppressWarnings("doclint")
+    /** The substring to match */
     protected final String substring;
 
-    @SuppressWarnings("doclint")
+    /**
+     * Build a SubstringMatcher.
+     * @param relationship a description of the matcher, such as "containing", "ending with", or "starting with"
+     * @param ignoringCase true for case-insensitive match
+     * @param substring the substring to match
+     */
     protected SubstringMatcher(String relationship, boolean ignoringCase, String substring) {
         this.relationship = relationship;
         this.ignoringCase = ignoringCase;
diff --git a/hamcrest/src/main/java/org/hamcrest/internal/ReflectiveTypeFinder.java b/hamcrest/src/main/java/org/hamcrest/internal/ReflectiveTypeFinder.java
index fbf738712..b04d5701f 100644
--- a/hamcrest/src/main/java/org/hamcrest/internal/ReflectiveTypeFinder.java
+++ b/hamcrest/src/main/java/org/hamcrest/internal/ReflectiveTypeFinder.java
@@ -1,44 +1,58 @@
+package org.hamcrest.internal;
+
+import java.lang.reflect.Method;
+
 /**
- * The TypeSafe classes, and their descendants, need a mechanism to find out what type has been used as a parameter
- * for the concrete matcher. Unfortunately, this type is lost during type erasure so we need to use reflection
+ * 
    Find the declared type of a parameterized type at runtime, bypassing normal type erasure problems.
+ * 
    
+ * 
    The TypeSafe classes, and their descendants, need a mechanism to find out what type has been used as a parameter
+ * for the concrete matcher. Unfortunately, this type is lost during type erasure, so we need to use reflection
  * to get it back, by picking out the type of a known parameter to a known method.
  * The catch is that, with bridging methods, this type is only visible in the class that actually implements
  * the expected method, so the ReflectiveTypeFinder needs to be applied to that class or a subtype.
- *
- * For example, the abstract TypeSafeDiagnosingMatcher<T> defines an abstract method
- * 
    protected abstract boolean matchesSafely(T item, Description mismatchDescription);
    
- * By default it uses new ReflectiveTypeFinder("matchesSafely", 2, 0);  to find the
+ * 
    
+ * 
    For example, the abstract TypeSafeDiagnosingMatcher<T> defines an abstract method
+ * protected abstract boolean matchesSafely(T item, Description mismatchDescription);
+ * By default, it uses new ReflectiveTypeFinder("matchesSafely", 2, 0); to find the
  * parameterised type. If we create a TypeSafeDiagnosingMatcher<String>, the type
  * finder will return String.class.
- *
- * A FeatureMatcher is an abstract subclass of TypeSafeDiagnosingMatcher.
+ * 
    
+ * 
    Another example: a FeatureMatcher is an abstract subclass of TypeSafeDiagnosingMatcher.
  * Although it has a templated implementation of matchesSafely(<T>, Description);, the
  * actual run-time signature of this is matchesSafely(Object, Description);. Instead,
  * we must find the type by reflecting on the concrete implementation of
- * 
    protected abstract U featureValueOf(T actual);
    
+ * protected abstract U featureValueOf(T actual);,
  * a method which is declared in FeatureMatcher.
- *
- * In short, use this to extract a type from a method in the leaf class of a templated class hierarchy.
+ * 
    
+ * 
    In short, use this to extract a type from a method in the leaf class of a templated class hierarchy.
+ * 
    
  *
  * @author Steve Freeman
  * @author Nat Pryce
  */
-package org.hamcrest.internal;
-
-import java.lang.reflect.Method;
-
 public class ReflectiveTypeFinder {
 
   private final String methodName;
   private final int expectedNumberOfParameters;
   private final int typedParameter;
 
+    /**
+     * Create a ReflectiveTypeFinder for a specific parameter on a specific method.
+     * @param methodName the name of a method in the leaf class that has a templated type
+     * @param expectedNumberOfParameters the expected number of parameters to the method
+     * @param typedParameter the index of the parameter that has the type information we want to look up
+     */
   public ReflectiveTypeFinder(String methodName, int expectedNumberOfParameters, int typedParameter) {
     this.methodName = methodName;
     this.expectedNumberOfParameters = expectedNumberOfParameters;
     this.typedParameter = typedParameter;
   }
 
+    /**
+     * Find the parameterized type from the specified parameter on the specified method.
+     * @param fromClass the class containing the method with the parameterized type
+     * @return the method parameter type
+     */
   public Class findExpectedType(Class fromClass) {
     for (Class c = fromClass; c != Object.class; c = c.getSuperclass()) {
         for (Method method : c.getDeclaredMethods()) {
diff --git a/hamcrest/src/main/java/org/hamcrest/io/FileMatchers.java b/hamcrest/src/main/java/org/hamcrest/io/FileMatchers.java
index ea517f4f3..cd4d354a5 100644
--- a/hamcrest/src/main/java/org/hamcrest/io/FileMatchers.java
+++ b/hamcrest/src/main/java/org/hamcrest/io/FileMatchers.java
@@ -20,56 +20,58 @@ private FileMatchers() {
 
     /**
      * A matcher that checks if a directory exists.
+     * @return the file matcher
      */
-    @SuppressWarnings("doclint")
     public static Matcher anExistingDirectory() {
         return fileChecker(IS_DIRECTORY, "an existing directory", "is not a directory");
     }
 
     /**
      * A matcher that checks if a file or directory exists.
+     * @return the file matcher
      */
-    @SuppressWarnings("doclint")
     public static Matcher anExistingFileOrDirectory() {
         return fileChecker(EXISTS, "an existing file or directory", "does not exist");
     }
 
     /**
      * A matcher that checks if a file exists.
+     * @return the file matcher
      */
-    @SuppressWarnings("doclint")
     public static Matcher anExistingFile() {
         return fileChecker(IS_FILE, "an existing File", "is not a file");
     }
 
     /**
      * A matcher that checks if a file is readable.
+     * @return the file matcher
      */
-    @SuppressWarnings("doclint")
     public static Matcher aReadableFile() {
         return fileChecker(CAN_READ, "a readable File", "cannot be read");
     }
 
     /**
      * A matcher that checks if a directory is writable.
+     * @return the file matcher
      */
-    @SuppressWarnings("doclint")
     public static Matcher aWritableFile() {
         return fileChecker(CAN_WRITE, "a writable File", "cannot be written to");
     }
 
     /**
      * A matcher that checks if a file has a specific size.
+     * @param size the expected size
+     * @return the file matcher
      */
-    @SuppressWarnings("doclint")
     public static Matcher aFileWithSize(long size) {
         return aFileWithSize(equalTo(size));
     }
 
     /**
      * A matcher that checks if a file size matches an expected size.
+     * @param expected matcher for the expected size
+     * @return the file matcher
      */
-    @SuppressWarnings("doclint")
     public static Matcher aFileWithSize(final Matcher expected) {
         return new FeatureMatcher(expected, "A file with size", "size") {
             @Override protected Long featureValueOf(File actual) { return actual.length(); }
@@ -78,8 +80,9 @@ public static Matcher aFileWithSize(final Matcher expected) {
 
     /**
      * A matcher that checks if a file name matches an expected name.
+     * @param expected the expected name
+     * @return the file matcher
      */
-    @SuppressWarnings("doclint")
     public static Matcher aFileNamed(final Matcher expected) {
         return new FeatureMatcher(expected, "A file with name", "name") {
             @Override protected String featureValueOf(File actual) { return actual.getName(); }
@@ -88,8 +91,9 @@ public static Matcher aFileNamed(final Matcher expected) {
 
     /**
      * A matcher that checks if a file canonical path matches an expected path.
+     * @param expected the expected path
+     * @return the file matcher
      */
-    @SuppressWarnings("doclint")
     public static Matcher aFileWithCanonicalPath(final Matcher expected) {
         return new FeatureMatcher(expected, "A file with canonical path", "path") {
             @Override protected String featureValueOf(File actual) {
@@ -104,8 +108,9 @@ public static Matcher aFileWithCanonicalPath(final Matcher expecte
 
     /**
      * A matcher that checks if a file absolute path matches an expected path.
+     * @param expected the expected path
+     * @return the file matcher
      */
-    @SuppressWarnings("doclint")
     public static Matcher aFileWithAbsolutePath(final Matcher expected) {
         return new FeatureMatcher(expected, "A file with absolute path", "path") {
             @Override protected String featureValueOf(File actual) { return actual.getAbsolutePath(); }
diff --git a/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java b/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java
index 3a3b247f3..d2f23f937 100644
--- a/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java
+++ b/hamcrest/src/main/java/org/hamcrest/number/BigDecimalCloseTo.java
@@ -18,9 +18,10 @@ public class BigDecimalCloseTo extends TypeSafeMatcher {
 
   /**
    * Constructor, best called from {@link #closeTo(BigDecimal, BigDecimal)}.
+   * @param value the expected value
+   * @param error the acceptable difference from the expected value
    * @see #closeTo(BigDecimal, BigDecimal)
    */
-  @SuppressWarnings("doclint")
   public BigDecimalCloseTo(BigDecimal value, BigDecimal error) {
       this.delta = error;
       this.value = value;
diff --git a/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java b/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java
index a73e2b71c..34c0aa532 100644
--- a/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java
+++ b/hamcrest/src/main/java/org/hamcrest/number/IsCloseTo.java
@@ -7,8 +7,7 @@
 import static java.lang.Math.abs;
 
 /**
- * Is the value a number equal to a value within some range of
- * acceptable error?
+ * Is the value a number equal to a value within some range of acceptable error?
  */
 public class IsCloseTo extends TypeSafeMatcher {
 
@@ -17,8 +16,9 @@ public class IsCloseTo extends TypeSafeMatcher {
 
     /**
      * Constructor, best called from {@link #closeTo(double, double)}.
+     * @param value the expected value
+     * @param error the acceptable difference from the expected value
      */
-    @SuppressWarnings("doclint")
     public IsCloseTo(double value, double error) {
         this.delta = error;
         this.value = value;
diff --git a/hamcrest/src/main/java/org/hamcrest/object/HasToString.java b/hamcrest/src/main/java/org/hamcrest/object/HasToString.java
index 17de0baf2..336b8227e 100644
--- a/hamcrest/src/main/java/org/hamcrest/object/HasToString.java
+++ b/hamcrest/src/main/java/org/hamcrest/object/HasToString.java
@@ -11,7 +11,10 @@
  */
 public class HasToString extends FeatureMatcher {
 
-    @SuppressWarnings("doclint")
+    /**
+     * Constructor, best called from {@link #hasToString(String)} or {@link #hasToString(Matcher)}.
+     * @param toStringMatcher expected result from calling toString()
+     */
     public HasToString(Matcher toStringMatcher) {
       super(toStringMatcher, "with toString()", "toString()");
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java b/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java
index 221244c15..10b86f085 100644
--- a/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java
+++ b/hamcrest/src/main/java/org/hamcrest/object/IsCompatibleType.java
@@ -5,8 +5,7 @@
 import org.hamcrest.TypeSafeMatcher;
 
 /**
- * A matcher of {@link Class} that matches when the specified baseType is
- * assignable from the examined class.
+ * A matcher of {@link Class} that matches when the specified baseType is assignable from the examined class.
  * @param  the type of the class
  */
 public class IsCompatibleType extends TypeSafeMatcher> {
@@ -15,8 +14,8 @@ public class IsCompatibleType extends TypeSafeMatcher> {
 
     /**
      * Constructor, best called from {@link #typeCompatibleWith(Class)}.
+     * @param type the expected type
      */
-    @SuppressWarnings("doclint")
     public IsCompatibleType(Class type) {
         this.type = type;
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java b/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java
index 5a7181138..b31a14784 100644
--- a/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java
+++ b/hamcrest/src/main/java/org/hamcrest/object/IsEventFrom.java
@@ -15,10 +15,10 @@ public class IsEventFrom extends TypeSafeDiagnosingMatcher {
     private final Object source;
 
     /**
-     * Constructor, best called from {@link #eventFrom(Object)} or
-     * {@link #eventFrom(Class, Object)}.
+     * Constructor, best called from {@link #eventFrom(Object)} or {@link #eventFrom(Class, Object)}.
+     * @param eventClass the expected class of the event
+     * @param source the expected source of the event
      */
-    @SuppressWarnings("doclint")
     public IsEventFrom(Class eventClass, Object source) {
         this.eventClass = eventClass;
         this.source = source;
diff --git a/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java b/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java
index cf82a3a1c..06ca9676c 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/CharSequenceLength.java
@@ -17,9 +17,10 @@ public class CharSequenceLength extends FeatureMatcher {
 
     /**
      * Constructor, best called from {@link #hasLength(Matcher)}.
+     * @param lengthMatcher the expected length
      * @see #hasLength(Matcher)
      */
-    @SuppressWarnings({"WeakerAccess", "doclint"})
+    @SuppressWarnings("WeakerAccess")
     public CharSequenceLength(Matcher lengthMatcher) {
         super(lengthMatcher, "a CharSequence with length", "length");
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java b/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java
index c04a820fc..4a4c4c677 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/IsEqualCompressingWhiteSpace.java
@@ -16,8 +16,8 @@ public class IsEqualCompressingWhiteSpace extends TypeSafeMatcher {
 
     /**
      * Constructor, best called from {@link #equalToCompressingWhiteSpace(String)}.
+     * @param string the expected string
      */
-    @SuppressWarnings("doclint")
     public IsEqualCompressingWhiteSpace(String string) {
         if (string == null) {
             throw new IllegalArgumentException("Non-null value required");
@@ -25,7 +25,10 @@ public IsEqualCompressingWhiteSpace(String string) {
         this.string = string;
     }
 
-    @SuppressWarnings("doclint")
+    /**
+     * Gets the string
+     * @return the string
+     */
     protected String getString() {
         return string;
     }
@@ -47,7 +50,11 @@ public void describeTo(Description description) {
                 .appendText(" compressing white space");
     }
 
-    @SuppressWarnings("doclint")
+    /**
+     * Strips spaces
+     * @param toBeStripped the string to be stripped
+     * @return the stripped string
+     */
     public String stripSpaces(String toBeStripped) {
         return toBeStripped.replaceAll("[\\p{Z}\\p{C}]+", " ").trim();
     }
diff --git a/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java b/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java
index 3cacf5a96..482265d8a 100644
--- a/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java
+++ b/hamcrest/src/main/java/org/hamcrest/text/IsEqualIgnoringCase.java
@@ -16,8 +16,8 @@ public class IsEqualIgnoringCase extends TypeSafeMatcher {
 
     /**
      * Constructor, best called from {@link #equalToIgnoringCase(String)}.
+     * @param string the expected string
      */
-    @SuppressWarnings("doclint")
     public IsEqualIgnoringCase(String string) {
         if (string == null) {
             throw new IllegalArgumentException("Non-null value required");
diff --git a/hamcrest/src/main/java/org/hamcrest/xml/HasXPath.java b/hamcrest/src/main/java/org/hamcrest/xml/HasXPath.java
index b86af5da5..fcaa9a077 100644
--- a/hamcrest/src/main/java/org/hamcrest/xml/HasXPath.java
+++ b/hamcrest/src/main/java/org/hamcrest/xml/HasXPath.java
@@ -37,16 +37,19 @@ public class HasXPath extends TypeSafeDiagnosingMatcher {
 
     /**
      * Constructor, best called from one of the hasXPath static factory methods.
+     * @param xPathExpression the target xpath
+     * @param valueMatcher matcher for the expected value
      */
-    @SuppressWarnings("doclint")
     public HasXPath(String xPathExpression, Matcher valueMatcher) {
         this(xPathExpression, NO_NAMESPACE_CONTEXT, valueMatcher);
     }
 
     /**
      * Constructor, best called from one of the hasXPath static factory methods.
+     * @param xPathExpression the target xpath
+     * @param namespaceContext the namespace for matching nodes
+     * @param valueMatcher matcher for the expected value
      */
-    @SuppressWarnings("doclint")
     public HasXPath(String xPathExpression, NamespaceContext namespaceContext, Matcher valueMatcher) {
         this(xPathExpression, namespaceContext, valueMatcher, STRING);
     }
@@ -148,8 +151,7 @@ public static Matcher hasXPath(String xPath, NamespaceContext namespaceCon
      * For example:
      * 
    assertThat(xml, hasXPath("/root/something[2]/cheese"))
    
      *
-     * @param xPath
-     *     the target xpath
+     * @param xPath the target xpath
      * @return The matcher.
      */
     public static Matcher hasXPath(String xPath) {
@@ -162,10 +164,8 @@ public static Matcher hasXPath(String xPath) {
      * For example:
      * 
    assertThat(xml, hasXPath("/root/something[2]/cheese", myNs))
    
      *
-     * @param xPath
-     *     the target xpath
-     * @param namespaceContext
-     *     the namespace for matching nodes
+     * @param xPath the target xpath
+     * @param namespaceContext the namespace for matching nodes
      * @return The matcher.
      */
     public static Matcher hasXPath(String xPath, NamespaceContext namespaceContext) {

From a66041e7327399902acb455abd8d8e0d1c3301b9 Mon Sep 17 00:00:00 2001
From: Joe Schmetzer 
Date: Wed, 14 Aug 2024 14:57:36 +1000
Subject: [PATCH 11/11] Add javadoc improvements to CHANGES.md

---
 CHANGES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 82e1bc4bd..5458ae6a1 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,7 +4,7 @@
 
 ### Improvements
 
-* TBD
+* Javadoc improvements and cleanup ([PR #420](https://github.com/hamcrest/JavaHamcrest/pull/420))
 
 ### Bugfixes