Skip to content

Commit 21a0529

Browse files
tumbarumbatumbarumba
authored
Javadoc cleanup (#420)
* Move all package docs into package-info.java * Ensure tutorial examples fit in line * Remove broken links from related projects * Suppress warnings about Java 8 * Exclude `org.hamcrest.internal` package from javadoc * Add javadoc overview, with basic example code * Add missing javadoc and fix javadoc warnings
1 parent e4c5bdd commit 21a0529

File tree

97 files changed

+1090
-282
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

97 files changed

+1090
-282
lines changed

‎CHANGES.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
### Improvements
66

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

99
### Bugfixes
1010

‎build.gradle‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,12 @@ subprojects {
6666
}
6767
}
6868

69+
allprojects {
70+
tasks.withType(JavaCompile) {
71+
options.compilerArgs << '-Xlint:-options'
72+
}
73+
}
74+
6975
def pomConfigurationFor(String pomName, String pomDescription) {
7076
return {
7177
name = pomName

‎docs/related.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,8 @@ layout: default
99
Here are some projects that provide additional features and matchers
1010

1111
* [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)
12-
* [EZ Testing](https://github.com/EZGames/ez-testing) (contains base classes for defining chainable matchers that have a similar style to AssertJ)
1312
* [Hamcrest 1.3 Utility Matchers](https://github.com/NitorCreations/matchers) (Java matchers like CollectionMatchers, MapMatchers, FieldMatcher, SerializableMatcher etc)
1413
* [Hamcrest auto matcher](https://github.com/itsallcode/hamcrest-auto-matcher) (uses reflection to automatically match model classes)
15-
* [Hamcrest avro](https://github.com/Byhiras/avro-utils)
1614
* [Hamcrest Composites](https://github.com/Cornutum/hamcrest-composites) (for comparing complex Java objects with better testability)
1715
* [Hamcrest Date](https://github.com/modularit/hamcrest-date) (for comparing dates)
1816
* [Hamcrest HAR](https://github.com/roydekleijn/har-assert) (for HTTP archive files)

‎docs/tutorial.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,11 @@ The `assertThat` method is a stylized sentence for making a test assertion. In t
3434
If you have more than one assertion in your test you can include an identifier for the tested value in the assertion:
3535

3636
```java
37-
assertThat("chocolate chips", theBiscuit.getChocolateChipCount(), equalTo(10));
37+
assertThat("chocolate chips",
38+
theBiscuit.getChocolateChipCount(), equalTo(10));
3839

39-
assertThat("hazelnuts", theBiscuit.getHazelnutCount(), equalTo(3));
40+
assertThat("hazelnuts",
41+
theBiscuit.getHazelnutCount(), equalTo(3));
4042
```
4143

4244
### Other test frameworks
@@ -122,7 +124,7 @@ public void testSquareRootOfMinusOneIsNotANumber() {
122124
And here's the implementation:
123125

124126
```java
125-
package org.hamcrest.examples.tutorial;
127+
package org.hamcrest.examples;
126128

127129
import org.hamcrest.Description;
128130
import org.hamcrest.Matcher;
@@ -162,7 +164,7 @@ The third method in our matcher is a convenience factory method. We statically i
162164
import org.junit.jupiter.api.Test;
163165
import static org.hamcrest.MatcherAssert.assertThat;
164166
import static org.hamcrest.Matchers.*;
165-
import static org.hamcrest.examples.tutorial.IsNotANumber.notANumber;
167+
import static org.hamcrest.examples.IsNotANumber.notANumber;
166168

167169
public class NumberTest {
168170
@Test

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,9 @@
66
*/
77
@Deprecated
88
class HamcrestCoreIsDeprecated {
9+
/**
10+
* Unused
11+
*/
12+
private HamcrestCoreIsDeprecated() {
13+
}
914
}

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,9 @@
66
*/
77
@Deprecated
88
class HamcrestLibraryIsDeprecated {
9+
/**
10+
* Unused
11+
*/
12+
private HamcrestLibraryIsDeprecated() {
13+
}
914
}

‎hamcrest/hamcrest.gradle‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,4 +33,8 @@ jar {
3333
}
3434
}
3535

36-
javadoc.title = "Hamcrest ${version} API"
36+
javadoc {
37+
title = "Hamcrest ${version} API"
38+
exclude "org/hamcrest/internal/*"
39+
options.overview = file("javadoc-overview.html")
40+
}

‎hamcrest/javadoc-overview.html‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
<!DOCTYPE HTML>
2+
<html lang="en">
3+
<head>
4+
<title>Hamcrest Overview</title>
5+
</head>
6+
<body>
7+
<p>Matchers that can be combined to create flexible expressions of intent.</p>
8+
<p>For example:</p>
9+
<pre style="border: 1px solid #ccc; margin: 0; padding: 0.5em;"><code>import org.junit.jupiter.api.Test;
10+
import static org.hamcrest.MatcherAssert.assertThat;
11+
import static org.hamcrest.Matchers.*;
12+
13+
public class BiscuitTest {
14+
&#64;Test
15+
public void testEquals() {
16+
Biscuit theBiscuit = new Biscuit("Ginger");
17+
Biscuit myBiscuit = new Biscuit("Ginger");
18+
assertThat(theBiscuit, equalTo(myBiscuit));
19+
}
20+
}
21+
</code></pre>
22+
23+
<p>For more information and documentation, see:</p>
24+
<ul>
25+
<li>The <a href="https://hamcrest.org/JavaHamcrest/tutorial" target="_top">Getting Started</a> tutorial</li>
26+
<li>The <a href="https://github.com/hamcrest/JavaHamcrest" target="_top">source code on GitHub</a></li>
27+
</ul>
28+
29+
</body>
30+
</html>
31+

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@
1313
*/
1414
public abstract class BaseDescription implements Description {
1515

16+
/**
17+
* Default constructor
18+
*/
19+
public BaseDescription() {
20+
}
21+
1622
@Override
1723
public Description appendText(String text) {
1824
append(text);

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,14 @@
44
* BaseClass for all Matcher implementations.
55
*
66
* @see Matcher
7+
* @param <T> The Matcher type.
78
*/
89
public abstract class BaseMatcher<T> implements Matcher<T> {
10+
/**
11+
* Default constructor.
12+
*/
13+
public BaseMatcher() {
14+
}
915

1016
/**
1117
* @see Matcher#_dont_implement_Matcher___instead_extend_BaseMatcher_()

0 commit comments

Comments
 (0)