Fix Javadoc for recent version of JDK 8, few formatting improvements

pom.xml

@@ -231,6 +231,7 @@
             <script src="http://cdn.jsdelivr.net/highlight.js/8.6/highlight.min.js"></script>
           ]]></top>
           <!-- init Highlight -->
+          <additionalparam>--allow-script-in-comments</additionalparam>
           <footer><![CDATA[
             <script type="text/javascript">
               hljs.initHighlightingOnLoad();

src/main/java/org/assertj/core/api/AbstractAssert.java

@@ -558,7 +558,7 @@ public int hashCode() {
    * <p>
    * Example :
    *
-   * <pre><code class='java'> assertThat(player).matches(p -> p.isRookie());</code></pre>
+   * <pre><code class='java'> assertThat(player).matches(p -&gt; p.isRookie());</code></pre>
    *
    * @param predicate the {@link Predicate} to match
    * @return {@code this} assertion object.
@@ -576,7 +576,7 @@ public SELF matches(Predicate<? super ACTUAL> predicate) {
    * <p>
    * Example :
    *
-   * <pre><code class='java'> assertThat(player).matches(p -> p.isRookie(), "is rookie");</code></pre>
+   * <pre><code class='java'> assertThat(player).matches(p -&gt; p.isRookie(), "is rookie");</code></pre>
    *
    * The error message contains the predicate description, if the previous assertion fails, it will be:
    *
@@ -605,7 +605,7 @@ public SELF matches(Predicate<? super ACTUAL> predicate, String predicateDescrip
    * Jedi yoda = new Jedi("Yoda", "Green");
    * Jedi luke = new Jedi("Luke Skywalker", "Green");
    *
-   * Consumer&lt;Jedi&gt; jediRequirements = jedi -> {
+   * Consumer&lt;Jedi&gt; jediRequirements = jedi -&gt; {
    *   assertThat(jedi.getLightSaberColor()).isEqualTo("Green");
    *   assertThat(jedi.getName()).doesNotContain("Dark");
    * };
@@ -620,7 +620,7 @@ public SELF matches(Predicate<? super ACTUAL> predicate, String predicateDescrip
    * <p>
    * In the following example, {@code satisfies} prevents the need of define a local variable in order to run multiple assertions:
    * <pre><code class='java'> // no need to define team.getPlayers().get(0).getStats() as a local variable
-   * assertThat(team.getPlayers().get(0).getStats()).satisfies(stats -> {
+   * assertThat(team.getPlayers().get(0).getStats()).satisfies(stats -&gt; {
    *   assertThat(stats.pointPerGame).isGreaterThan(25.7);
    *   assertThat(stats.assistsPerGame).isGreaterThan(7.2);
    *   assertThat(stats.reboundsPerGame).isBetween(9, 12);

src/main/java/org/assertj/core/api/AbstractBDDSoftAssertions.java

@@ -251,6 +251,7 @@ public LongPredicateAssert then(LongPredicate actual) {
    * possible to use it again.</b> Calling multiple methods on the returned {@link ListAssert} is safe as it only
    * interacts with the {@link List} built from the {@link Stream}.
    *
+   * @param <ELEMENT> the type of elements.
    * @param actual the actual {@link Stream} value.
    * @return the created assertion object.
    */

src/main/java/org/assertj/core/api/AbstractBigDecimalAssert.java

@@ -237,6 +237,8 @@ public SELF isEqualTo(String expected) {
    * 
    * // assertion will fail
    * assertThat(new BigDecimal(&quot;8.0&quot;)).isEqualByComparingTo(&quot;2.0&quot;);</code></pre>
+   * @param expected the expected {@link BigDecimal} passed as a String
+   * @return {@code this} assertion object.
    */
   public SELF isEqualByComparingTo(String expected) {
     return isEqualByComparingTo(new BigDecimal(expected));
@@ -252,9 +254,11 @@ public SELF isEqualByComparingTo(String expected) {
    *
    * // assertion will fail
    * assertThat(new BigDecimal(&quot;8.0&quot;)).isNotEqualByComparingTo(&quot;8.00&quot;);</code></pre>
+   * @param notExpected the {@link BigDecimal} value passed as a String not to expect.
+   * @return {@code this} assertion object.
    */
-  public SELF isNotEqualByComparingTo(String expected) {
-    return isNotEqualByComparingTo(new BigDecimal(expected));
+  public SELF isNotEqualByComparingTo(String notExpected) {
+    return isNotEqualByComparingTo(new BigDecimal(notExpected));
   }
 
   @Override

src/main/java/org/assertj/core/api/AbstractBigIntegerAssert.java

@@ -375,6 +375,7 @@ public SELF isEqualTo(String expected) {
    * // assertion will fail
    * assertThat(new BigInteger(&quot;8&quot;)).isEqualTo(2);</code></pre>
    *
+   * @param expected the expected value
    * @return {@code this} assertion object.
    * @since 2.7.0 / 3.7.0
    */
@@ -393,6 +394,7 @@ public SELF isEqualTo(int expected) {
    * // assertion will fail
    * assertThat(new BigInteger(&quot;8&quot;)).isEqualTo(2L);</code></pre>
    *
+   * @param expected the expected value
    * @return {@code this} assertion object.
    * @since 2.7.0 / 3.7.0
    */

src/main/java/org/assertj/core/api/AbstractClassAssert.java

@@ -304,6 +304,8 @@ public SELF hasAnnotation(Class<? extends Annotation> annotation) {
 
   /**
    * @deprecated use {@link #hasPublicFields(String...)} instead.
+   * @param fields the fields who must be in the class.
+   * @return {@code this} assertions object
    */
   @Deprecated
   public SELF hasFields(String... fields) {

src/main/java/org/assertj/core/api/AbstractCompletableFutureAssert.java

@@ -217,6 +217,7 @@ public SELF isNotCompleted() {
    * <pre><code class='java'> assertThat(CompletableFuture.completedFuture("something"))
    *           .isCompletedWithValue("something else");</code></pre>
    *
+   * @param expected the expected result value of the {@link CompletableFuture}.
    * @return this assertion object.
    */
   public SELF isCompletedWithValue(RESULT expected) {
@@ -234,12 +235,13 @@ public SELF isCompletedWithValue(RESULT expected) {
    * <p>
    * Assertion will pass :
    * <pre><code class='java'> assertThat(CompletableFuture.completedFuture("something"))
-   *           .isCompletedWithValueMatching(result -> result.equals("something"));</code></pre>
+   *           .isCompletedWithValueMatching(result -&gt; result.equals("something"));</code></pre>
    *
    * Assertion will fail :
    * <pre><code class='java'> assertThat(CompletableFuture.completedFuture("something"))
-   *           .isCompletedWithValueMatching(result -> result.equals("something else"));</code></pre>
+   *           .isCompletedWithValueMatching(result -&gt; result.equals("something else"));</code></pre>
    *
+   * @param predicate the {@link Predicate} to apply.
    * @return this assertion object.
    */
   public SELF isCompletedWithValueMatching(Predicate<? super RESULT> predicate) {
@@ -252,16 +254,18 @@ public SELF isCompletedWithValueMatching(Predicate<? super RESULT> predicate) {
    * <p>
    * Assertion will pass :
    * <pre><code class='java'> assertThat(CompletableFuture.completedFuture("something"))
-   *           .isCompletedWithValueMatching(result -> result != null, "expected not null");</code></pre>
+   *           .isCompletedWithValueMatching(result -&gt; result != null, "expected not null");</code></pre>
    *
    * Assertion will fail :
    * <pre><code class='java'> assertThat(CompletableFuture.completedFuture("something"))
-   *           .isCompletedWithValueMatching(result -> result == null, "expected null");</code></pre>
+   *           .isCompletedWithValueMatching(result -&gt; result == null, "expected null");</code></pre>
    * Error message is:            
    * <pre><code class='java'> Expecting:
-   *   <"something">
+   *   &lt;"something"&gt;
    * to match 'expected null' predicate.</code></pre>
    *
+   * @param predicate the {@link Predicate} to apply on the resulting value.
+   * @param description the {@link Predicate} description.
    * @return this assertion object.
    */
   public SELF isCompletedWithValueMatching(Predicate<? super RESULT> predicate, String description) {

src/main/java/org/assertj/core/api/AbstractDateAssert.java

@@ -1300,6 +1300,8 @@ public SELF hasYear(int year) {
 
   /**
    * @deprecated use {@link #hasYear(int)} instead.
+   * @param year the year to compare actual year to
+   * @return this assertion object.
    */
   @Deprecated
   public SELF isWithinYear(int year) {
@@ -1333,6 +1335,8 @@ public SELF hasMonth(int month) {
 
   /**
    * @deprecated use {@link #hasMonth(int)} instead.
+   * @param month the month to compare actual month to, <b>month value starting at 1</b> (January=1, February=2, ...).
+   * @return this assertion object.
    */
   @Deprecated
   public SELF isWithinMonth(int month) {
@@ -1365,6 +1369,8 @@ public SELF hasDayOfMonth(int dayOfMonth) {
 
   /**
    * @deprecated use {@link #hasDayOfMonth(int)} instead.
+   * @param dayOfMonth the day of month to compare actual day of month to
+   * @return this assertion object.
    */
   @Deprecated
   public SELF isWithinDayOfMonth(int dayOfMonth) {
@@ -1398,6 +1404,9 @@ public SELF hasDayOfWeek(int dayOfWeek) {
 
   /**
    * @deprecated use {@link #hasDayOfWeek(int)} instead.
+   * @param dayOfWeek the day of week to compare actual day of week to, see {@link Calendar#DAY_OF_WEEK} for valid
+   *          values
+   * @return this assertion object.
    */
   @Deprecated
   public SELF isWithinDayOfWeek(int dayOfWeek) {
@@ -1429,6 +1438,8 @@ public SELF hasHourOfDay(int hourOfDay) {
 
   /**
    * @deprecated use {@link #hasHourOfDay(int)} instead.
+   * @param hourOfDay the hour of day to compare actual hour of day to (24-hour clock)
+   * @return this assertion object.
    */
   @Deprecated
   public SELF isWithinHourOfDay(int hourOfDay) {
@@ -1460,6 +1471,8 @@ public SELF hasMinute(int minute) {
 
   /**
    * @deprecated use {@link #hasMinute(int)} instead.
+   * @param minute the minute to compare actual minute to
+   * @return this assertion object.
    */
   @Deprecated
   public SELF isWithinMinute(int minute) {
@@ -1491,6 +1504,8 @@ public SELF hasSecond(int second) {
 
   /**
    * @deprecated use {@link #hasSecond(int)} instead.
+   * @param second the second to compare actual second to
+   * @return this assertion object.
    */
   @Deprecated
   public SELF isWithinSecond(int second) {
@@ -1522,10 +1537,12 @@ public SELF hasMillisecond(int millisecond) {
 
   /**
    * @deprecated use {@link #hasMillisecond(int)} instead.
+   * @param millisecond the millisecond to compare actual millisecond to
+   * @return this assertion object.
    */
   @Deprecated
-  public SELF isWithinMillisecond(int second) {
-    dates.assertHasMillisecond(info, actual, second);
+  public SELF isWithinMillisecond(int millisecond) {
+    dates.assertHasMillisecond(info, actual, millisecond);
     return myself;
   }
 
@@ -2054,6 +2071,7 @@ public SELF isInSameSecondWindowAs(Date other) {
    * </ul>
    *
    * @param dateAsString the given Date represented as String.
+   * @return this assertion object.
    * @throws NullPointerException if dateAsString parameter is {@code null}.
    * @throws AssertionError if the actual {@code Date} is {@code null}.
    * @throws AssertionError if actual and given {@code Date} are not in the same second.
@@ -2121,6 +2139,8 @@ public SELF isInSameSecondAs(Date other) {
    * <li><code>2003-04-26T13:01:02</code></li>
    * <li><code>2003-04-26</code></li>
    * </ul>
+   * @param dateAsString the given Date represented as String.
+   * @return this assertion object.
    */
   public SELF isInSameSecondAs(String dateAsString) {
     return isInSameSecondAs(parse(dateAsString));