maven-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Robert Scholte (JIRA)" <j...@apache.org>
Subject [jira] [Updated] (MJAVADOC-452) Several fixes for comment corruption in fix goal
Date Sat, 29 Dec 2018 13:13:00 GMT

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

Robert Scholte updated MJAVADOC-452:
------------------------------------
    Description: 
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) *[Done]* 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) *[Done]* 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) *[Can't reproduce]* 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) *[Done]* 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) *[Done]* 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) *[Superceded]* 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.

  was:
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) *[Done]* 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) *[Done]* 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) *[Done]* 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) *[Done]* 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) *[Superceded]* 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.


> 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: fix
>    Affects Versions: 2.10.3
>            Reporter: Richard Sand
>            Priority: Major
>              Labels: patch
>         Attachments: maven-javadoc-plugin-MJAVADOC452.patch, maven-javadoc-plugin-OnlySaveIfChanged.patch,
maven-javadoc-plugin-RemoveUnknownThrowsOption.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) *[Done]* 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) *[Done]* 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) *[Can't reproduce]* 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) *[Done]* 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) *[Done]* 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) *[Superceded]* 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
(v7.6.3#76005)

Mime
View raw message