[MJAVADOC-757] fix Javadoc warnings (#212)

* [MJAVADOC-757] fix Javadoc warnings

Author: elharo

src/main/java/org/apache/maven/plugins/javadoc/AbstractFixJavadocMojo.java

@@ -87,8 +87,8 @@
 
 /**
  * Abstract class to fix Javadoc documentation and tags in source files.
- * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/javadoc/doc-comment-spec.html#where-tags-can-be-used">Where Tags
- * Can Be Used</a>.
+ *
+ * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/javadoc/doc-comment-spec.html#where-tags-can-be-used">Where Tags Can Be Used</a>
  * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
  * @since 2.6
  */

src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java

@@ -1026,8 +1026,8 @@ public abstract class AbstractJavadocMojo extends AbstractMojo {
     private boolean keywords;
 
     /**
-     * Creates links to existing javadoc-generated documentation of external referenced classes.
-     * <br>
+     * Creates links to existing javadoc-generated documentation of external referenced classes.<p>
+     *
      * <b>Notes</b>:
      * <ol>
      * <li>only used if {@code isOffline} is set to <code>false</code>.</li>
@@ -1039,12 +1039,12 @@ public abstract class AbstractJavadocMojo extends AbstractMojo {
      * &lt;links&gt;
      * </pre>
      * will be used because <code>https://docs.oracle.com/en/java/javase/17/docs/api/element-list</code> exists.</li>
-     * <li>if {@link #detectLinks} is defined, the links between the project dependencies are
+     * <li>If {@link #detectLinks} is defined, the links between the project dependencies are
      * automatically added.</li>
-     * <li>if {@link #detectJavaApiLink} is defined, a Java API link, based on the Java version of the
+     * <li>If {@link #detectJavaApiLink} is defined, a Java API link, based on the Java version of the
      * project's sources, will be added automatically.</li>
      * </ol>
-     * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html#standard-doclet-options">Doclet option link</a>.
+     * @see <a href=https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html#standard-doclet-options>Doclet option link</a>
      */
     @Parameter(property = "links")
     protected ArrayList<String> links;
@@ -1682,7 +1682,7 @@ protected MavenProject getProject() {
     /**
      * @param p not null maven project
      * @return the list of directories where compiled classes are placed for the given project. These dirs are
-     *         added in the javadoc classpath.
+     *         added to the javadoc classpath.
      */
     protected List<File> getProjectBuildOutputDirs(MavenProject p) {
         if (StringUtils.isEmpty(p.getBuild().getOutputDirectory())) {
@@ -1693,10 +1693,8 @@ protected List<File> getProjectBuildOutputDirs(MavenProject p) {
     }
 
     /**
-     * Either returns the attached artifact file or outputDirectory
-     *
-     * @param project
-     * @return
+     * @param project the project in which to find a classes file
+     * @return null, the attached artifact file, or outputDirectory.
      */
     protected File getClassesFile(MavenProject project) {
         if (!isAggregator() && isTest()) {
@@ -6026,8 +6024,7 @@ protected void failOnError(String prefix, Exception e) throws MojoExecutionExcep
     }
 
     /**
-     *
-     * @return List of projects to be part of aggregated javadoc
+     * @return list of projects to be part of aggregated javadoc
      */
     private List<MavenProject> getAggregatedProjects() {
         if (this.reactorProjects == null) {
@@ -6046,8 +6043,8 @@ private List<MavenProject> getAggregatedProjects() {
     }
 
     /**
-     *
-     * @return <code>true</code> if the module need to be skipped from aggregate generation
+     * @param mavenProject the project that might be skipped
+     * @return <code>true</code> if the project needs to be skipped from aggregate generation
      */
     protected boolean isSkippedModule(MavenProject mavenProject) {
         if (this.skippedModules == null || this.skippedModules.isEmpty()) {
@@ -6058,8 +6055,8 @@ protected boolean isSkippedModule(MavenProject mavenProject) {
     }
 
     /**
-     *
-     * @return <code>true</code> if the pom configuration skip javadoc generation for the project
+     * @param mavenProject the project that might be skipped
+     * @return <code>true</code> if the pom configuration skips javadoc generation for the project
      */
     protected boolean isSkippedJavadoc(MavenProject mavenProject) {
         String property = mavenProject.getProperties().getProperty("maven.javadoc.skip");

src/main/java/org/apache/maven/plugins/javadoc/JavadocUtil.java

@@ -393,9 +393,10 @@ public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IO
      * Convenience method that gets the files to be included in the javadoc.
      *
      * @param sourceDirectory the directory where the source files are located
-     * @param excludePackages the packages to be excluded in the javadocs
-     * @param sourceFileIncludes files to include.
-     * @param sourceFileExcludes files to exclude.
+     * @param sourceFileIncludes files to include
+     * @param sourceFileExcludes files to exclude
+     * @param excludePackages packages to be excluded from the javadocs
+     * @return the files from which javadoc should be generated
      */
     protected static List<String> getFilesFromSource(
             File sourceDirectory,

src/main/java/org/apache/maven/plugins/javadoc/ResourcesBundleMojo.java

@@ -62,7 +62,7 @@ public class ResourcesBundleMojo extends AbstractJavadocMojo {
 
     /**
      * Base name of artifacts produced by this project. This will be combined with
-     * {@link ResourcesBundleMojo#getAttachmentClassifier()} to produce the name for this bundle
+     * {@link AbstractJavadocMojo#getAttachmentClassifier()} to produce the name for this bundle
      * jar.
      */
     @Parameter(defaultValue = "${project.build.finalName}", readonly = true)

src/main/java/org/apache/maven/plugins/javadoc/TestFixJavadocMojo.java

@@ -33,8 +33,8 @@
 
 /**
  * Fix Javadoc documentation and tags for the <code>Test Java code</code> for the project.
- * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/javadoc/doc-comment-spec.html#where-tags-can-be-used">Where Tags Can
- * Be Used</a>.
+ *
+ * @see <a href=https://docs.oracle.com/en/java/javase/17/docs/specs/javadoc/doc-comment-spec.html#where-tags-can-be-used>Where Tags Can Be Used</a>
  * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
  * @since 2.6
  */