Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Missing consistent order of Javadoc tags #3469

Open
scordio opened this issue May 10, 2024 · 5 comments · May be fixed by bjss/assertj#2 or #3627
Open

Missing consistent order of Javadoc tags #3469

scordio opened this issue May 10, 2024 · 5 comments · May be fixed by bjss/assertj#2 or #3627
Assignees
Labels
status: ideal for contribution An issue that a contributor can help us with theme: documentation An issue related to documentation

Comments

@scordio
Copy link
Member

scordio commented May 10, 2024

According to Oracle, the Javadoc order of tags should be the following:

  • @author
  • @version
  • @param
  • @return
  • @exception / @throws
  • @see
  • @since
  • @serial
  • @deprecated

Other than fixing the existing order, we should have an automated way to enforce it, maybe via Spotless or the maven-javadoc-plugin.

@PhilipIngham
Copy link

Hey! I've started working on this issue on this PR here, and have mentioned something on the PR and will mention it here just to see where people stand.

In the Oracle Javadoc, it mentions a convention around multiple @throws tags to be in alphabetical order - order of multiple tags. Is this wanting to be implemented? Perhaps it should be a separate issue if it's wanting to go ahead, but figured I'd get some thoughts on it from more knowledgeable folk than myself before deciding what to do with it.

@scordio
Copy link
Member Author

scordio commented Jul 30, 2024

@PhilipIngham thanks for jumping on it!

In the Oracle Javadoc, it mentions a convention around multiple @throws tags to be in alphabetical order - order of multiple tags. Is this wanting to be implemented?

Sounds sensible to me.

Do you already know how to enforce these rules in an automated way?

@PhilipIngham
Copy link

Do you already know how to enforce these rules in an automated way?

Not really, no. At the moment I'm just going through everything manually using regex to fix the stuff that's out of place in the tags, but I'll definitely need some help and/or time to figure out how to get the automation down.

@scordio
Copy link
Member Author

scordio commented Jul 30, 2024

I was checking what Checkstyle offers and spotted the following:

@PhilipIngham
Copy link

Checked this out and looks really useful, I will try and implement it :) Thanks for the assistance

@PhilipIngham PhilipIngham linked a pull request Sep 29, 2024 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
status: ideal for contribution An issue that a contributor can help us with theme: documentation An issue related to documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants