Consistent Javadocs Tags Order

[PhilipIngham]

Check List:

• Fixes Missing consistent order of Javadoc tags assertj/assertj#3469
• Unit tests : NA
• Javadoc with a code example (on API only) : YES
• PR meets the contributing guidelines

Following the contributing guidelines will make it easier for us to review and accept your PR.

[PhilipIngham]

Started working on this issue, definitely going to take a while to change everything, and then implement a way for it to be kept up with automatically. Here is a checklist that I will edit and update with the changes that need to be made and completion status:

Reordering all tags to be in the correct order, following the Javadoc order of tags:
@author - Complete!
@version - Already done.
@param - Complete!
@return - Complete!
@exception (covers @throws) - Complete!
@see - Complete!
@since - Complete!
@serial - Complete!
@deprecated - Complete!

Reorder multiple @throws tags to be in alphabetical order as per the Javadoc order of multiple tags (open to discussion)

Create a method to enforce this ordering of tags automatically

[PhilipIngham]

With the above commit, someone can now check for issues in ordering of tags with mvn checkstyle:check.
Currently still working on automation though I think I am close to getting it working

[scordio]

@PhilipIngham by luck, I noticed you opened the PR on a fork and not on assertj/assertj 😉

[PhilipIngham]

Yeah this is so people can review internally before making a pull request against the actual repository

[PhilipIngham]

I've ran into a spot of trouble with this. Essentially, the last commit I did should allow so that whenever a maven build is ran, it should do the checkstyle check I have created using my ruleset, however I can't get it to run. I've tried using different phases in the plugin in the pom.xml file (such as verify and compile) but nothing changes. I feel like I'm missing something pretty obvious with it, would someone be able to have a look?

[scordio]

If no one finds a solution earlier, I try playing with it over the weekend.

[PhilipIngham]

That would be great, thanks :)

[scordio]

Raised #3 against this branch.

[PhilipIngham]

Just an FYI I am still working on this 😅 Just been away for a week so not done much during that time. Current focus is getting the throws tags to be ordered alphabetically, then I'll be looking to merge it in :)

[scordio]

Take your time and thank you very much for your effort!

[PhilipIngham]

Hey, just thought I'd give an update on this and how it is going.

As of now I'm at the point where I'm trying to sort the throw tags to be alphabetically ordered. This is proving to be a very difficult task, as there is nothing available in the checkstyle plugin to help with this, so I've been trying to write some stuff myself but it's seeming to be probably a lot more hassle than it's worth.

With myself, I'll be moving onto different things so the likelihood of me working on this for too much longer aren't that high. I'll still be able to do bits here and there, but it won't have my full attention.

What I suggest is either:

• This be merged in by itself as the ordering of all javadoc tags is successful
• Or this be put on hold for someone else to pick up

Happy with whichever option is chose.

[scordio]

Would you have time to raise the PR against the main repo, even as a draft?

I'm happy to take over the topic and finalize it, but most likely not in the short term. I'll get there eventually 🙂 and keep you as the author.

[PhilipIngham]

Created one here: assertj#3627