maven-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Richard Sand (JIRA)" <j...@apache.org>
Subject [jira] [Updated] (MJAVADOC-452) Several fixes for comment corruption in fix goal
Date Sat, 09 Jul 2016 03:43:11 GMT

     [ https://issues.apache.org/jira/browse/MJAVADOC-452?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]

Richard Sand updated MJAVADOC-452:
----------------------------------
    Attachment: maven-javadoc-plugin-OnlySaveIfChanged.patch

this patch is for the improvement that a file is not saved if no changes are made

> Several fixes for comment corruption in fix goal
> ------------------------------------------------
>
>                 Key: MJAVADOC-452
>                 URL: https://issues.apache.org/jira/browse/MJAVADOC-452
>             Project: Maven Javadoc Plugin
>          Issue Type: Bug
>          Components: javadoc
>    Affects Versions: 2.10.3
>            Reporter: Richard Sand
>              Labels: patch
>         Attachments: maven-javadoc-plugin-MJAVADOC452.patch, maven-javadoc-plugin-OnlySaveIfChanged.patch
>
>
> I've attached a patch to this issue that fixes several problems in javadoc:fix, including
issue MJAVADOC-420,MJAVADOC-434, and MJAVADOC-451, and adds some improvements to the fix goal.
> 1) added a new config parameter "removeUnknownThrows", to tell the plugin to remove a
@throws tag if the exception class is not actually thrown. Previously it only warned. I set
the default value to "false" to preserve existing behavior
> 2) in "processFix", I added a check to see if the content had actually been changed before
writing to disk. This preserves file timestamps and provides a clear indication if any changes
were actually made
> 3) a problem in "updateJavadocTags" for method comments specifically, where, if a throws
tag was unknown, it would be written at the bottom of the comments e.g. after @return, @since
etc. I fixed updateJavadocTags so that method tags are always output in the prescribed order
> 4) I fixed issue MJAVADOC-420, where if two method parameters existed with overlapping
names (e.g. @param thing @param thing2), then the second parameter would be added twice
> 5) there was an issue if a comment erroneously contained the same parameter twice (.e.g
@param thing, @param thing), where both tags would be duplicated, and all instances would
have the description of the first. this was fixed in "updateJavadocTags" and "addMissingJavadocTags"
> 6) Includes the same fix as attached to MJAVADOC-451, which adds a "skip" parameter,
which is useful when used in conjunction with "force". Also this parameter prevents "clirr"
from causing javadoc:fix from being re-invoked when clirr is kicked off, which would cause
an infinite loop of fix-->clirr-->fix-->clirr. This scenario is prevented by internally
passing the "skip" parameter into the invocation of clirr
> I believe the patch will also resolve MJAVADOC-434, corrupted files (basically the end-comment
tag was left in the middle of the comment block causing syntax errors) because I also observed
this behavior and I don't now after the patch, but I didn't actually trace down the root cause
of 434 to be certain
> Lastly I updated some of the log messages to be more descriptive and indicative of the
actual activity (e.g. changed "fixing" to "analyzing").
> Now that the tags are output in the prescribed order, two of the JUnit test "expected"
java output files needed to be updated to put the @return tag below their @param tags
> The attached patch file updates AbstractFixJavadocMojo.jar, and two test resources. All
JUnit tests pass successfully. The patch was generated against the 2.10.3 tag in SVN.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

Mime
View raw message