Javadoc improvements

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

@@ -665,10 +665,10 @@ public SELF contains(CharSequence... values) {
    * Verifies that the actual {@code CharSequence} contains any of the given values.
    * <p>
    * Example:
-   * <pre><code class='java'> // assertions will pass
+   * <pre><code class='java'> // assertion succeeds
    * assertThat(&quot;Gandalf the grey&quot;).containsAnyOf(&quot;grey&quot;, &quot;black&quot;);
    *
-   * // assertions will fail
+   * // assertion fails
    * assertThat(&quot;Gandalf the grey&quot;).containsAnyOf(&quot;white&quot;, &quot;black&quot;);</code></pre>
    *
    * @param values the values to look for.

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

@@ -1117,20 +1117,14 @@ public SELF hasNoParentRaw() {
    * </p>
    *
    * Examples:
-   * <pre><code class="java"> // Given the following empty paths
-   * /root/sub-dir-1/foo.ext
-   * /root/sub-dir-1/bar.ext
+   * <pre><code class="java">
+   * Path foxPath = Files.write(Paths.get("/fox.txt"), "The Quick Brown Fox.".getBytes());
+   * 
+   * // this assertion succeeds
+   * assertThat(foxPath).hasSize(20);
    *
-   * Path emptyPath = Paths.get("/root/sub-dir-1/foo.ext")
-   * Path nonEmptyPath = Files.write(Paths.get("/root/sub-dir-1/bar.ext"),
-   *                                 "The Quick Brown Fox.".getBytes());
-   * // the following assertions pass
-   * assertThat(emptyPath).hasSize(0);
-   * assertThat(nonEmptyPath).hasSize(20);
-   *
-   * // the following assertions fail
-   * assertThat(emptyPath).hasSize(5);
-   * assertThat(nonEmptyPath).hasSize(0);</code></pre>
+   * // this assertion fails
+   * assertThat(foxPath).hasSize(3);</code></pre>
    *
    * @param expectedSize the expected {@code Path} file size in bytes
    * @return {@code this} assertion object
@@ -1912,27 +1906,26 @@ private String readPath(Charset charset) {
 
   /**
    * Verifies that the actual {@code Path} has given extension.
-   *
    * <p>
    * Example:
    * <pre><code class='java'> Path path = Paths.get(&quot;file.java&quot;);
    *
-   * // assertion will pass
+   * // assertion succeeds:
    * assertThat(path).hasExtension(&quot;java&quot;);
    *
-   * // assertion will fail
+   * // assertion fails:
    * assertThat(path).hasExtension(&quot;png&quot;);</code></pre>
    *
-   * @param expected the expected extension, without the {@code '.'}.
+   * @param expectedExtension the expected extension, without the {@code '.'}.
    * @return {@code this} assertion object.
    * @throws NullPointerException if the expected extension is {@code null}.
    * @throws AssertionError if the actual {@code Path} is {@code null}.
    * @throws AssertionError if the actual {@code Path} is not a regular file.
    * @throws AssertionError if the actual {@code Path} does not have the expected extension.
    * @since 3.21.0
    */
-  public SELF hasExtension(String expected) {
-    paths.assertHasExtension(info, actual, expected);
+  public SELF hasExtension(String expectedExtension) {
+    paths.assertHasExtension(info, actual, expectedExtension);
     return myself;
   }