Skip to content

Commit 80e1cc9

Browse files
TimvdLippeTimvdLippe
authored
Fix JavaDoc warnings and enforce zero errors in Gradle (mockito#2513)
Now, we ensure that our JavaDoc doesn't produce any warnings. The most common problems were using < instead of &lt; and & instead of the word "and".
1 parent 8319cc5 commit 80e1cc9

21 files changed

+72
-82
lines changed

‎gradle/mockito-core/javadoc.gradle

+3-15
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,6 @@ javadoc {
2222
// While there's errors the javadoc is still generated without those symbols or links ;
2323
// for this reason the javadoc output is suppressed and can be reactivated with --info option.
2424
exclude 'org/mockito/internal'
25-
logging.captureStandardError LogLevel.INFO
26-
logging.captureStandardOutput LogLevel.INFO // suppress "## warnings" message
2725

2826
options.docTitle = """<h1><a href="org/mockito/Mockito.html">Click to see examples</a>. Mockito ${project.version} API.</h1>"""
2927
options.windowTitle = "Mockito ${project.version} API"
@@ -41,9 +39,7 @@ javadoc {
4139
options.noNavBar = false
4240
options.noTree = false
4341
options.links = ['https://docs.oracle.com/javase/6/docs/api/',
44-
'http://junit.org/junit4/javadoc/4.12/']
45-
options.header("""<em id="mockito-version-header-javadoc7-header"><strong>Mockito ${project.version} API</strong></em>""")
46-
options.footer("""<em id="mockito-version-header-javadoc7-footer"><strong>Mockito ${project.version} API</strong></em>""")
42+
'https://junit.org/junit4/javadoc/4.12/']
4743
options.bottom("""
4844
<script type="text/javascript" src="{@docRoot}/js/jdk6-project-version-insert.min.js"></script>
4945
<script type="text/javascript" src="{@docRoot}/js/jquery-1.7.min.js"></script>
@@ -53,16 +49,8 @@ javadoc {
5349
<script type="text/javascript" src="{@docRoot}/js/index.js" async defer></script>
5450
""".replaceAll(/\r|\n|[ ]{8}/, ""))
5551
options.stylesheetFile rootProject.file("src/javadoc/stylesheet.css")
56-
options.addStringOption('Xdoclint:none', '-quiet')
57-
58-
def minorVersion = System.getProperty("java.version") =~ /1.8.0_(\d*)/
59-
60-
// Since JDK 8 version 121 scripts are not allowed in comments. However,
61-
// earlier version throw an error if an unknown option is passed.
62-
// Therefore only add this option if the JDK is actually correct.
63-
if (minorVersion.size() > 0 && Integer.valueOf(minorVersion[0][1]) >= 121 || JavaVersion.current().isJava9Compatible()) {
64-
options.addBooleanOption('-allow-script-in-comments', true)
65-
}
52+
options.addStringOption('Xwerror', '-quiet')
53+
options.addBooleanOption('-allow-script-in-comments', true)
6654

6755
doLast {
6856
copy {

‎src/main/java/org/mockito/AdditionalAnswers.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
*
3232
* <p>Currently offer answers that can return the parameter of an invocation at a certain position,
3333
* along with answers that draw on a strongly typed interface to provide a neater way to write custom answers
34-
* that either return a value or are void (see answer interfaces in {@link org.mockito.stubbing}).
34+
* that either return a value or are void (see answer interfaces in org.mockito.stubbing).
3535
*
3636
* <p>See factory methods for more information : {@link #returnsFirstArg}, {@link #returnsSecondArg},
3737
* {@link #returnsLastArg}, {@link #returnsArgAt}, {@link #answer} and {@link #answerVoid}

‎src/main/java/org/mockito/ArgumentCaptor.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
*
1616
* <p>
1717
* Mockito verifies argument values in natural java style: by using an equals() method.
18-
* This is also the recommended way of matching arguments because it makes tests clean & simple.
18+
* This is also the recommended way of matching arguments because it makes tests clean and simple.
1919
* In some situations though, it is helpful to assert on certain arguments after the actual verification.
2020
* For example:
2121
* <pre class="code"><code class="java">

‎src/main/java/org/mockito/ArgumentMatcher.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@
8080
* and use a lambda, e.g.:
8181
*
8282
* <pre class="code"><code class="java">
83-
* verify(mock).addAll(<b>argThat(list -> list.size() == 2)</b>);
83+
* verify(mock).addAll(<b>argThat(list -&gt; list.size() == 2)</b>);
8484
* </code></pre>
8585
*
8686
* <p>

‎src/main/java/org/mockito/MockSettings.java

+5-5
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,12 @@
2323
* <p/>
2424
* Don't use it too often.
2525
* Consider writing simple tests that use simple mocks.
26-
* Repeat after me: simple tests push simple, KISSy, readable & maintainable code.
26+
* Repeat after me: simple tests push simple, KISSy, readable and maintainable code.
2727
* If you cannot write a test in a simple way - refactor the code under test.
2828
* <p/>
2929
* Examples of mock settings:
3030
* <pre class="code"><code class="java">
31-
* //Creates mock with different default answer & name
31+
* //Creates mock with different default answer and name
3232
* Foo mock = mock(Foo.class, withSettings()
3333
* .defaultAnswer(RETURNS_SMART_NULLS)
3434
* .name("cool mockie")
@@ -51,8 +51,8 @@ public interface MockSettings extends Serializable {
5151
* Specifies extra interfaces the mock should implement. Might be useful for legacy code or some corner cases.
5252
* <p>
5353
* This mysterious feature should be used very occasionally.
54-
* The object under test should know exactly its collaborators & dependencies.
55-
* If you happen to use it often than please make sure you are really producing simple, clean & readable code.
54+
* The object under test should know exactly its collaborators and dependencies.
55+
* If you happen to use it often than please make sure you are really producing simple, clean and readable code.
5656
* <p>
5757
* Examples:
5858
* <pre class="code"><code class="java">
@@ -101,7 +101,7 @@ public interface MockSettings extends Serializable {
101101
* <p>
102102
* However, there are rare cases when partial mocks come handy:
103103
* dealing with code you cannot change easily (3rd party interfaces, interim refactoring of legacy code etc.)
104-
* However, I wouldn't use partial mocks for new, test-driven & well-designed code.
104+
* However, I wouldn't use partial mocks for new, test-driven and well-designed code.
105105
* <p>
106106
* Enough warnings about partial mocks, see an example how spiedInstance() works:
107107
* <pre class="code"><code class="java">

0 commit comments

Comments
 (0)