[MRELEASE-1036] Fix JavaDoc for JDK 8

[cchacin]

Related JIRA Ticket

https://issues.apache.org/jira/browse/MRELEASE-1036

What?

• Fix Javadocs

Why?

• To be compatible with the JDK 8 doclint

Testing:

✅mvn javadoc:javadoc

[michael-o]

This PR was mediocre/incomplete. It introduced trailing spaces and ^M in several files. @cchacin Can you please create a followup PR?

[cchacin]

@michael-o I can notice trailing spaces in Strategy.java but those were there before, I didn't notice it since the diff is not showing that I introduced those, and the goal was to make the mvn javadoc command to pass in java 8.

I can submit another PR to fix the trailing spaces that were already present in that file, but I cannot see the ^M that you mentioned, can you help me to understand what else needs to be fixed to submit one single PR with all the required changes?

We can also use a .editorconfig and/or .gitattributes files to help to minimize these situations.

[michael-o]

@cchacin
A sample:

diff --git a/maven-release-api/src/main/java/org/apache/maven/shared/release/policy/naming/NamingPolicy.java b/maven-release-api/src/main/java/org/apache/maven/shared/release/policy/naming/NamingPolicy.java
index 3435c243..2257df39 100644
--- a/maven-release-api/src/main/java/org/apache/maven/shared/release/policy/naming/NamingPolicy.java
+++ b/maven-release-api/src/main/java/org/apache/maven/shared/release/policy/naming/NamingPolicy.java
@@ -29,7 +29,11 @@ import org.apache.maven.shared.release.policy.PolicyException;
 public interface NamingPolicy
 {
     /**
-     * Calculation of the name used for branching or tagging.
+     * @return the calculation of the name used for branching or tagging.^M
+     * ^M
+     * @param request the {@code NamingPolicyRequest}^M
+     * ^M
+     * @throws PolicyException if exception in the policy^M
      */
     NamingPolicyResult getName( NamingPolicyRequest request )
         throws PolicyException;
diff --git a/maven-release-api/src/main/java/org/apache/maven/shared/release/policy/version/VersionPolicy.java b/maven-release-api/src/main/java/org/apache/maven/shared/release/policy/version/VersionPolicy.java
index a902bdfb..55bffae7 100644
--- a/maven-release-api/src/main/java/org/apache/maven/shared/release/policy/version/VersionPolicy.java
+++ b/maven-release-api/src/main/java/org/apache/maven/shared/release/policy/version/VersionPolicy.java
@@ -30,13 +30,23 @@ import org.apache.maven.shared.release.versions.VersionParseException;
 public interface VersionPolicy
 {
     /**
-     * Calculation of the release version from development state.
+     * @return the calculation of the release version from development state.^M
+     * ^M
+     * @param request the {@code VersionPolicyRequest}^M
+     *                ^M
+     * @throws PolicyException if exception in the policy^M
+     * @throws VersionParseException if exception parsing the version^M
      */
     VersionPolicyResult getReleaseVersion( VersionPolicyRequest request )
         throws PolicyException, VersionParseException;

     /**
-     * Calculation of the next development version from release state.
+     * @return the calculation of the next development version from release state.^M
+     *^M
+     * @param request the {@code VersionPolicyRequest}^M
+     *^M
+     * @throws PolicyException if exception in the policy^M
+     * @throws VersionParseException if exception parsing the version^M
      */
     VersionPolicyResult getDevelopmentVersion( VersionPolicyRequest request )
         throws PolicyException, VersionParseException;

The Git Bash shows all trailing whitespace include carriage returns. You don't see them on GH. Please create one PR for this.

[cchacin]

Created 2 PRs including one that can help to prevent this problem in the future:

1. fix: re-normalize ALL line endings fix: re-normalize all line endings #34
   As you can see there were a lot of files presenting the same issue, the following PR can prevent that:
2. fix: add .gitattributes to auto configure line endings fix: add .gitattributes to auto configure line endings #35