[
https://issues.apache.org/jira/browse/MJAVADOC-452?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Richard Sand updated MJAVADOC-452:
----------------------------------
Description:
I've attached a patch to this issue that fixes several problems in javadoc:fix,
including issue MJAVADOC-420,434, and 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") and updated the
hardcoded clirr version to 2.7.
was:
I've attached a patch to this issue that fixes several problems in javadoc:fix,
including issue MJAVADOC-420,434, and 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"
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") and updated the
hardcoded clirr version to 2.7.
> 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: AbstractFixJavadocMojo.patch
>
>
> I've attached a patch to this issue that fixes several problems in
> javadoc:fix, including issue MJAVADOC-420,434, and 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") and
> updated the hardcoded clirr version to 2.7.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
