You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Richard Sand <rs...@idfconnect.com> on 2019/01/16 19:13:05 UTC
suggestion regarding MJAVADOC-564 - javadoc:fix enforcing order of tags
Hi all - I'd like to provide a fix for MJAVADOC-564, where the
javadoc:fix goal will sometimes output the javadoc tags in incorrect
order. The problem occurs because of the way the fix goal initially
reads in the tags and then iterates over them to make the prescribed
corrections. There is an internal wrapper class inside the
AbstractFixJavadocMojo called JavaEntityTags that maintains various
state of the processing, including maintaining the original values of
all tags, the mappings of @param and @throws to values, etc. There is a
lot of logic in the mojo to keep track of original and updated values,
determining whether an update is necessary, etc., and I think that it
can be simplified by keeping an ordered, multi-valued map of all tags,
both the original and added/updated. My suggestion is to add a trivial
inner class called JavaEntityValue to hold both the original and updated
value, i.e.:
class JavaEntityValue {
String originalValue;
String updatedValue;
}
and then keep a multi-valued, ordered map in JavaEntityTags, e.g.
LinkedHashMap allTags <String,LinkedList<JavaEntityValue>>;
This will allow all of the existing logic inside the mojo to manipulate
the "allTags" map instead of directly writing to the output buffer, so
we can output all of the results at the very end of the mojo, output the
tags in the prescribed order, while still preserving the existing order
of all instances of a particular tag or any unknown tags.
I'd like to use common-collections4 (which will not override or conflict
with the existing collections dependency, which is 3.2.1) for the
"allTags" map to create this combined linked/multivalued map with its
decorators.
Any thoughts about this? If its ok I'll build it and issue a PR on the
current 3.1.0-SNAPSHOT master
Best regards,
Richard
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: suggestion regarding MJAVADOC-564 - javadoc:fix enforcing order of tags
Posted by Richard Sand <rs...@idfconnect.com>.
Comparator will help order the tags but we still want to preserve the order of found tags we aren’t fixing, such as if we aren’t fixing “see” tags and want to honor the original order of the existing see tags.
I’ll give it a shot
Sent from my iPhone
> On Jan 16, 2019, at 3:40 PM, Robert Scholte <rf...@apache.org> wrote:
>
> It would be great if the fix-goal code could be simplified.
> In fact I thought about moving code to a different package+classes, which should make it easier read, maintain and to unittest. But that's a huge task.
> It is still a bit too abstract for me to see the complete picture.
>
> The first thing I had in mind when reading this was the need for a comparator to reorder the tags.
> Not sure if that would replace the need for common-collections4
>
> I would suggest to give it a try.
>
> thanks,
> Robert
>
>> On Wed, 16 Jan 2019 20:13:05 +0100, Richard Sand <rs...@idfconnect.com> wrote:
>>
>> Hi all - I'd like to provide a fix for MJAVADOC-564, where the javadoc:fix goal will sometimes output the javadoc tags in incorrect order. The problem occurs because of the way the fix goal initially reads in the tags and then iterates over them to make the prescribed corrections. There is an internal wrapper class inside the AbstractFixJavadocMojo called JavaEntityTags that maintains various state of the processing, including maintaining the original values of all tags, the mappings of @param and @throws to values, etc. There is a lot of logic in the mojo to keep track of original and updated values, determining whether an update is necessary, etc., and I think that it can be simplified by keeping an ordered, multi-valued map of all tags, both the original and added/updated. My suggestion is to add a trivial inner class called JavaEntityValue to hold both the original and updated value, i.e.:
>>
>> class JavaEntityValue {
>> String originalValue;
>> String updatedValue;
>> }
>>
>> and then keep a multi-valued, ordered map in JavaEntityTags, e.g.
>>
>> LinkedHashMap allTags <String,LinkedList<JavaEntityValue>>;
>>
>> This will allow all of the existing logic inside the mojo to manipulate the "allTags" map instead of directly writing to the output buffer, so we can output all of the results at the very end of the mojo, output the tags in the prescribed order, while still preserving the existing order of all instances of a particular tag or any unknown tags.
>>
>> I'd like to use common-collections4 (which will not override or conflict with the existing collections dependency, which is 3.2.1) for the "allTags" map to create this combined linked/multivalued map with its decorators.
>>
>> Any thoughts about this? If its ok I'll build it and issue a PR on the current 3.1.0-SNAPSHOT master
>>
>> Best regards,
>>
>> Richard
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: suggestion regarding MJAVADOC-564 - javadoc:fix enforcing order
of tags
Posted by Robert Scholte <rf...@apache.org>.
It would be great if the fix-goal code could be simplified.
In fact I thought about moving code to a different package+classes, which
should make it easier read, maintain and to unittest. But that's a huge
task.
It is still a bit too abstract for me to see the complete picture.
The first thing I had in mind when reading this was the need for a
comparator to reorder the tags.
Not sure if that would replace the need for common-collections4
I would suggest to give it a try.
thanks,
Robert
On Wed, 16 Jan 2019 20:13:05 +0100, Richard Sand <rs...@idfconnect.com>
wrote:
> Hi all - I'd like to provide a fix for MJAVADOC-564, where the
> javadoc:fix goal will sometimes output the javadoc tags in incorrect
> order. The problem occurs because of the way the fix goal initially
> reads in the tags and then iterates over them to make the prescribed
> corrections. There is an internal wrapper class inside the
> AbstractFixJavadocMojo called JavaEntityTags that maintains various
> state of the processing, including maintaining the original values of
> all tags, the mappings of @param and @throws to values, etc. There is a
> lot of logic in the mojo to keep track of original and updated values,
> determining whether an update is necessary, etc., and I think that it
> can be simplified by keeping an ordered, multi-valued map of all tags,
> both the original and added/updated. My suggestion is to add a trivial
> inner class called JavaEntityValue to hold both the original and updated
> value, i.e.:
>
> class JavaEntityValue {
> String originalValue;
> String updatedValue;
> }
>
> and then keep a multi-valued, ordered map in JavaEntityTags, e.g.
>
> LinkedHashMap allTags <String,LinkedList<JavaEntityValue>>;
>
> This will allow all of the existing logic inside the mojo to manipulate
> the "allTags" map instead of directly writing to the output buffer, so
> we can output all of the results at the very end of the mojo, output the
> tags in the prescribed order, while still preserving the existing order
> of all instances of a particular tag or any unknown tags.
>
> I'd like to use common-collections4 (which will not override or conflict
> with the existing collections dependency, which is 3.2.1) for the
> "allTags" map to create this combined linked/multivalued map with its
> decorators.
>
> Any thoughts about this? If its ok I'll build it and issue a PR on the
> current 3.1.0-SNAPSHOT master
>
> Best regards,
>
> Richard
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org