From 05fe1c6cefbf291118b11ea37d203ddee2434ac7 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Sun, 30 Oct 2022 18:50:49 +0000 Subject: [PATCH 1/3] Ckleanup language and update URLs @michael-o --- src/site/apt/examples/fix-javadocs.apt.vm | 43 +++++++++++------------ 1 file changed, 20 insertions(+), 23 deletions(-) diff --git a/src/site/apt/examples/fix-javadocs.apt.vm b/src/site/apt/examples/fix-javadocs.apt.vm index a0accdf50..4a788554c 100644 --- a/src/site/apt/examples/fix-javadocs.apt.vm +++ b/src/site/apt/examples/fix-javadocs.apt.vm @@ -28,39 +28,39 @@ Fixing Javadoc Comments - When developers write code, they could forget to create (or update) the Javadoc comments. The and + When developers write code, they often forget to create (or update) the Javadoc comments. The and goals are interactive goals (i.e. used generally in command line) to fix the actual Javadoc comments in your classes. You need to call to fix main Java source files (i.e. inside src/main/java directory) or to fix test Java source files (i.e. inside src/test/java directory). - <>: Since the changes are done <> in the source code, we recommend <> the use of - a SCM, so you could always do a revert if a problem occurs. You could always add <<<-DoutputDirectory=/path/to/dir>>> - to specify a target directory where classes will be generated. + <>: Since the changes are done <> in the source code by default, we <> recommend using + a SCM, so you cab revert if a problem occurs. You can also add <<<-DoutputDirectory=/path/to/dir>>> + to change the directory where classes will be generated and avoid overwriting the existing source code. * Features Summary - The user could skip the class/field/method Javadoc fixing using specific parameters, i.e. + The user can skip the class/field/method Javadoc fixing using specific parameters, i.e. {{{../fix-mojo.html#fixClassComment}\}}. - Also, the user could specify a {{{../fix-mojo.html#level}\}}, i.e. public, to fix only class/field/method with + Also, the user can specify a {{{../fix-mojo.html#level}\}}, i.e. public, to fix only class/field/method with the given level. - These goals could fix dynamically all Javadoc tags (by default, see {{{../fix-mojo.html#fixTags}\}}) or - selective tags like author, version... - Also, the user could specify default value for some tags, i.e. {{{../fix-mojo.html#defaultAuthor}\}}. + These goals can fix all Javadoc tags (by default, see {{{../fix-mojo.html#fixTags}\}}) or + selective tags like author, version, etc. + You specify default value for some tags, for example, {{{../fix-mojo.html#defaultAuthor}\}}. - The goal could use Clirr ({{{http://clirr.sourceforge.net}}} via the - {{{http://mojo.codehaus.org/clirr-maven-plugin/}clirr-maven-plugin}}, a tool that checks Java libraries for - binary and source compatibility with older releases. So, the <@since> tags will be dynamically added for the current + The goal can use Clirr ({{{http://clirr.sourceforge.net}}} via the + {{{http://mojo.codehaus.org/clirr-maven-plugin/}clirr-maven-plugin}} to add + <@since> tags will be dynamically added for the current project version. You need to add the parameter (see below). - Finally, the user could process specific Java files using the + Finally, the user can process specific Java files using the {{{../fix-mojo.html#includes}includes}}/{{{../fix-mojo.html#excludes}excludes}} parameters. ** Current limitations - The and goals use intensively {{{http://qdox.codehaus.org/}Qdox}} to extract class/interface/method - Javadoc from source files. Unfortunately, Qdox has {{{https://issues.apache.org/jira/browse/QDOX}some known issues}}. + The and goals use {{{https://github.com/paul-hammant/qdox}} to extract class/interface/method + Javadoc from source files. * Example Call @@ -86,16 +86,14 @@ y ... +-----+ - You could review the changes and commit. + You can then review the changes and commit. * Using Clirr Integration - <>: a previous artifact should be deployed firstly. - ** Comparing against a specific version - By default, the goals compare the current code against the latest released version, which is lower than the current - version. If you want to use another version, you need to specify it similar to the Maven Clirr Plugin: + By default, the goals compare the current code against the latest released version which is lower than the current + version. If you want to use another version, you need to specify it like so: +-----+ mvn javadoc:fix -DcomparisonVersion=1.0 @@ -107,9 +105,8 @@ mvn javadoc:fix -DcomparisonVersion=1.0 ** Using another Clirr version - By default, the and goals use the {{{http://mojo.codehaus.org/clirr-maven-plugin/}clirr-maven-plugin}}, - version <<<2.2.2>>>. To use another version, you need to add a dependency in the Javadoc plugin, similar to the - following: + By default, the and goals use the {{{https://www.mojohaus.org/clirr-maven-plugin}clirr-maven-plugin}}, + version <<<2.2.2>>>. To use another version, you need to add a dependency in the Javadoc plugin as shown here: +-----+ From e90578fedb7332bd7512f18fa4187d854389605e Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Sat, 5 Nov 2022 20:32:32 +0000 Subject: [PATCH 2/3] fix typo --- src/site/apt/examples/fix-javadocs.apt.vm | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/site/apt/examples/fix-javadocs.apt.vm b/src/site/apt/examples/fix-javadocs.apt.vm index 4a788554c..813e10cd6 100644 --- a/src/site/apt/examples/fix-javadocs.apt.vm +++ b/src/site/apt/examples/fix-javadocs.apt.vm @@ -35,7 +35,7 @@ Fixing Javadoc Comments to fix test Java source files (i.e. inside src/test/java directory). <>: Since the changes are done <> in the source code by default, we <> recommend using - a SCM, so you cab revert if a problem occurs. You can also add <<<-DoutputDirectory=/path/to/dir>>> + a SCM, so you can revert if a problem occurs. You can also add <<<-DoutputDirectory=/path/to/dir>>> to change the directory where classes will be generated and avoid overwriting the existing source code. * Features Summary From e3c1a3942bccb787386cea85ebbb8af6ff9071de Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Mon, 14 Nov 2022 07:30:24 -0500 Subject: [PATCH 3/3] Fix link --- src/site/apt/examples/fix-javadocs.apt.vm | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/site/apt/examples/fix-javadocs.apt.vm b/src/site/apt/examples/fix-javadocs.apt.vm index 813e10cd6..be45ef074 100644 --- a/src/site/apt/examples/fix-javadocs.apt.vm +++ b/src/site/apt/examples/fix-javadocs.apt.vm @@ -59,7 +59,7 @@ Fixing Javadoc Comments ** Current limitations - The and goals use {{{https://github.com/paul-hammant/qdox}} to extract class/interface/method + The and goals use {{{https://github.com/paul-hammant/qdox}qdox}} to extract class/interface/method Javadoc from source files. * Example Call