From d33677e090615c3c0fb602393a0ce1188932fbac Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Sat, 8 Jul 2023 08:24:30 -0400 Subject: [PATCH 1/3] [MJAVADOC-757] fix Javadoc warnings --- .../javadoc/AbstractFixJavadocMojo.java | 4 ++-- .../plugins/javadoc/AbstractJavadocMojo.java | 19 ++++++++----------- .../maven/plugins/javadoc/JavadocUtil.java | 7 ++++--- .../plugins/javadoc/ResourcesBundleMojo.java | 2 +- .../plugins/javadoc/TestFixJavadocMojo.java | 3 +-- 5 files changed, 16 insertions(+), 19 deletions(-) diff --git a/src/main/java/org/apache/maven/plugins/javadoc/AbstractFixJavadocMojo.java b/src/main/java/org/apache/maven/plugins/javadoc/AbstractFixJavadocMojo.java index 75a88fbe..cf5ab033 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/AbstractFixJavadocMojo.java +++ b/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 Where Tags - * Can Be Used. + * + * @see Where Tags Can Be Used * @author Vincent Siveton * @since 2.6 */ diff --git a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java index 8374125c..84e27228 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java +++ b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java @@ -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 getProjectBuildOutputDirs(MavenProject p) { if (StringUtils.isEmpty(p.getBuild().getOutputDirectory())) { @@ -1693,10 +1693,8 @@ protected List getProjectBuildOutputDirs(MavenProject p) { } /** - * Either returns the attached artifact file or outputDirectory - * - * @param project - * @return + * @param mavenProject 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 getAggregatedProjects() { if (this.reactorProjects == null) { @@ -6046,8 +6043,8 @@ private List getAggregatedProjects() { } /** - * - * @return true if the module need to be skipped from aggregate generation + * @param mavenProject the project that might be skipped + * @return true 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 true if the pom configuration skip javadoc generation for the project + * @param mavenProject the project that might be skipped + * @return true if the pom configuration skips javadoc generation for the project */ protected boolean isSkippedJavadoc(MavenProject mavenProject) { String property = mavenProject.getProperties().getProperty("maven.javadoc.skip"); diff --git a/src/main/java/org/apache/maven/plugins/javadoc/JavadocUtil.java b/src/main/java/org/apache/maven/plugins/javadoc/JavadocUtil.java index 91942bb3..c58a8ed0 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/JavadocUtil.java +++ b/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 getFilesFromSource( File sourceDirectory, diff --git a/src/main/java/org/apache/maven/plugins/javadoc/ResourcesBundleMojo.java b/src/main/java/org/apache/maven/plugins/javadoc/ResourcesBundleMojo.java index d93926e5..60d7e08e 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/ResourcesBundleMojo.java +++ b/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) diff --git a/src/main/java/org/apache/maven/plugins/javadoc/TestFixJavadocMojo.java b/src/main/java/org/apache/maven/plugins/javadoc/TestFixJavadocMojo.java index 877c5f2d..e44f193c 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/TestFixJavadocMojo.java +++ b/src/main/java/org/apache/maven/plugins/javadoc/TestFixJavadocMojo.java @@ -33,8 +33,7 @@ /** * Fix Javadoc documentation and tags for the Test Java code for the project. - * @see Where Tags Can - * Be Used. + * @see Where Tags Can Be Used. * @author Vincent Siveton * @since 2.6 */ From e30946b0f2fd77eaa265b1b4d608893d1797b96e Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Sat, 8 Jul 2023 08:57:41 -0400 Subject: [PATCH 2/3] more fixes --- .../maven/plugins/javadoc/AbstractJavadocMojo.java | 12 ++++++------ .../maven/plugins/javadoc/TestFixJavadocMojo.java | 3 ++- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java index 84e27228..55bac924 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java +++ b/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. - *
+ * Creates links to existing javadoc-generated documentation of external referenced classes.

+ * * Notes: *

    *
  1. only used if {@code isOffline} is set to false.
    2. @@ -1039,12 +1039,12 @@ public abstract class AbstractJavadocMojo extends AbstractMojo { * <links> * * will be used because https://docs.oracle.com/en/java/javase/17/docs/api/element-list exists. - *
  2. if {@link #detectLinks} is defined, the links between the project dependencies are + *
  3. If {@link #detectLinks} is defined, the links between the project dependencies are * automatically added.
    4. - *
  4. if {@link #detectJavaApiLink} is defined, a Java API link, based on the Java version of the + *
  5. If {@link #detectJavaApiLink} is defined, a Java API link, based on the Java version of the * project's sources, will be added automatically.
    6. *
- * @see Doclet option link. + * @see Doclet option link */ @Parameter(property = "links") protected ArrayList links; @@ -1693,7 +1693,7 @@ protected List getProjectBuildOutputDirs(MavenProject p) { } /** - * @param mavenProject the project in which to find a classes file + * @param project the project in which to find a classes file * @return null, the attached artifact file, or outputDirectory. */ protected File getClassesFile(MavenProject project) { diff --git a/src/main/java/org/apache/maven/plugins/javadoc/TestFixJavadocMojo.java b/src/main/java/org/apache/maven/plugins/javadoc/TestFixJavadocMojo.java index e44f193c..4ff18ec3 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/TestFixJavadocMojo.java +++ b/src/main/java/org/apache/maven/plugins/javadoc/TestFixJavadocMojo.java @@ -33,7 +33,8 @@ /** * Fix Javadoc documentation and tags for the Test Java code for the project. - * @see Where Tags Can Be Used. + * + * @see Where Tags Can Be Used * @author Vincent Siveton * @since 2.6 */ From 570ffb42875834dc7e931a17cee43a8e896bfa81 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Sat, 8 Jul 2023 08:59:22 -0400 Subject: [PATCH 3/3] spotles --- .../org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java index 55bac924..2fdb2f0c 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java +++ b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java @@ -1027,7 +1027,7 @@ public abstract class AbstractJavadocMojo extends AbstractMojo { /** * Creates links to existing javadoc-generated documentation of external referenced classes.

- * + * * Notes: *

    *
  1. only used if {@code isOffline} is set to false.