ARTEMIS-5314 overhaul JavaDoc formatting & content #5512
+11,156
−21,584
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Someone elses turn to chew on the massive code/javadoc twiddling, I wont be reviewing it :) Though on the commit message, the https://bugs.openjdk.org/browse/JDK-8256804 CSR Jira seems like it does a far better job of explaining Presumably a draft because of the compilation failure on 21+ |
jbertram
force-pushed
the
ARTEMIS-5314
branch
2 times, most recently
from
8a074cf to
1e8c9da
Compare
jbertram
force-pushed
the
ARTEMIS-5314
branch
from
1e8c9da to
3c0db62
Compare
tabish121
reviewed
Feb 20, 2025
| @@ -16,8 +16,6 @@ | |||
| */ | |||
| package org.apache.activemq.artemis.api.core; | |||
|
|
|||
| /** | |||
| */ | |||
| // XXX | |||
There was a problem hiding this comment.
Missed some extra "comment" that could also get deleted.
jbertram
force-pushed
the
ARTEMIS-5314
branch
2 times, most recently
from
6c5e762 to
1e09236
Compare
|
The full test-suite is green on this. |
tabish121
reviewed
Feb 20, 2025
| @@ -51,7 +51,9 @@ | |||
| import static org.junit.jupiter.api.Assertions.assertNotNull; | |||
| import static org.junit.jupiter.api.Assumptions.assumeTrue; | |||
|
|
|||
| /* at the time this test was written JournalFileImpl was leaking through JournalFileImpl::negative creating a linked list (or leaked-list, pun intended) */ | |||
| /* At the time this test was written JournalFileImpl was leaking through JournalFileImpl::negative creating a linked | |||
There was a problem hiding this comment.
Could perhaps add a newline after the opening '/*' to bring this into compliance with all the other formatting changes.
| @@ -53,7 +53,9 @@ | |||
| import org.slf4j.Logger; | |||
| import org.slf4j.LoggerFactory; | |||
|
|
|||
| /* at the time this test was written JournalFileImpl was leaking through JournalFileImpl::negative creating a linked list (or leaked-list, pun intended) */ | |||
| /* At the time this test was written JournalFileImpl was leaking through JournalFileImpl::negative creating a linked | |||
There was a problem hiding this comment.
Should perhaps add a newline after the opening '/*' to be consistent with other changes.
| OBJECT, STRING, NUMBER, | ||
| TRUE, FALSE, | ||
| NULL | ||
| ARRAY, OBJECT, STRING, NUMBER, TRUE, FALSE, NULL |
There was a problem hiding this comment.
This doesn't appear to be javadoc related
jbertram
force-pushed
the
ARTEMIS-5314
branch
4 times, most recently
from
d9172ec to
cb2deff
Compare
This commit overhauls JavaDoc formatting & content across the entire code-base placing a heavy emphasis on the don't-repeat-yourself principle (i.e. DRY). The main goals here are readability, conciseness, and safeguarding future commits from the same kinds of mistakes that have plagued the code-base for many years now. It includes the following changes: - Remove empty @param, @throws, & @return tags. - Remove useless/boilerplate comments. - Re-wrap to 120 characters. Many comments already used this limit while others were less than and still other were more than this limit. Using 120 was a happy medium. - Enforce multi-line syntax, e.g.: /** * Lorem ipsum */ - Change /** to /* where appropriate (e.g. license headers, intra-method comments, etc.) - Change /* to /** where appropriate (e.g. method descriptions, comments using tags like @code, etc.) - Remove trailing or extraneous '*' characters. - Remove JavaDocs from implementations when the JavaDocs of the interface will suffice. - Use {@code Lorem ipsum} syntax where appropriate. - Use <p> for empty lines. Remove <br>, <br/>, & <br /> - Use the {@return ...} sytanx introduced in Java 16. Details are at https://bugs.openjdk.org/browse/JDK-8256804. - Align @param descriptions. - Align @throws descriptions. - Add empty line between description and start of tags (e.g. @param). - Fix the prolific "whether or not" to the more correct just "whether". - Enforce many of these standards via checkstyle. - Remove references to defunct issue trackers or forums. - Convert single line comments using /* syntax to use //.
jbertram
force-pushed
the
ARTEMIS-5314
branch
from
cb2deff to
fb04fe5
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I apologize in advance for this PR. I started down this road, and it just kept growing. I didn't realize how many JavaDocs we actually had throughout the code-base.
Couple of things to note: