Issue #19827: Remove chapter numbers from Doc Comments Coverage Page by gianmarcoschifone · Pull Request #19828 · checkstyle/checkstyle

gianmarcoschifone · 2026-05-16T22:40:34Z

Issue #19827

Removed section numbers from displayed rule names in doc_comments_style.xml.
Excluded doc_comments from testAllStyleRules, since that validation depends on numbered rule names and anchors.
Added testDocCommentsStyleRules to validate doc-comments style coverage without relying on numbering.
Kept important checks for doc-comments modules, config links, sample links, duplicate modules, and sample folder existence.

gianmarcoschifone · 2026-05-16T22:41:33Z

GitHub, generate website

github-actions · 2026-05-16T22:56:01Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/485efb5_20260516225447/index.html

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/485efb5_20260516225447/doc_comments_style.html#Coverage_table

romani

I like it

Zopsss

one small change required:

Zopsss · 2026-05-19T03:10:50Z

+    }
+
+    private static void removeCommonUndocumentedModules(Set<String> styleChecks) {
+        // these modules aren't documented, but are added to the config


make this a javadoc comment

Zopsss

few more changes:

Zopsss · 2026-05-19T03:18:12Z

-                    1.1.1.1 Separate Specification Documents
+                    Java Platform API Specification is defined
+                      by the documentation comments in the source code


this isn't required. It is just a bullet point.

Similarly following are also not required:

Java Platform API Specification is a contract between callers and implementations

Java API Specification assertions need to be implementation-independent

Java API Specification should contain assertions sufficient to enable Software Quality Assurance

It was me , I asked to make all bold items to be links.

Zopsss · 2026-05-19T03:32:10Z

-                    2.1 Format of a Doc Comment
+                    Format of a Doc Comment


Make all following sub-sections of "Introuction" & "Writing doc comments" bold + italic:

Making a some simple table of content will be awesome

@gianmarcoschifone I think you misunderstood what I meant here. You made the sub-section bold + italic in the cached page but I meant to do it in the Coverage Table.

Zopsss · 2026-05-19T03:33:20Z

-                    2.1.1 Notes
+                    Notes


remove this, it is just notes

Zopsss · 2026-05-19T03:33:55Z

-                    2.1.2 getImage
+                    getImage


Remove this, it is an example not a rule/section:

Here is what the previous example would look like after running the Javadoc tool

Zopsss · 2026-05-19T03:38:51Z

-                    2.5.4.1 @author
+                    @author


remove @author, @version, @param, @return, and all the other tags.

If we're not able to follow some tag then we will explicitly mention it in the coverage table with blue/red tick.

I asked to make them as link. As it looks like paragraph, and have wording on what is good .
Fact that we can not make any such words a rule, is our decision

As in Google style we slice and dice all text, and do not hesitate to mark section as "no rules".
It will be very clear for all that we read it attentively, and still think there is no rules.

They were just tags, we don't have different checks for tags, mostly all of these tags will be using same check.

It'll make the table longer.

The google style guide on the other hand is very well documented and have numberings too. So skipping some rules/sections doesn't make sense, we should include all of them. But that is not the case with this documentation.

Anyways, let's keep this for now. If we're able to follow rules for all tags then I think we should remove it, otherwise we can keep it to inform user that a particular tag rule is not able to be followed by us.

They were just tags, we don't have different checks for tags, mostly all of these tags will be using same check.

We do not know for sure, and you might noticed recent trend in Google style coverage that we create Google special Checks for very special requests. If general Check is not able to cover special request, we do special Check.

It'll make the table longer.

I am completely ok to rethink on this at the end of summer.
done: https://github.com/orgs/checkstyle/projects/19?pane=issue&itemId=190014508

romani · 2026-05-19T04:11:48Z

@Zopsss , how can we make guide page to look good in mobile browser?

gianmarcoschifone · 2026-05-19T08:37:05Z

GitHub, generate website

github-actions · 2026-05-19T08:46:17Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/0eb9c0b_20260519084502/index.html

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/0eb9c0b_20260519084502/doc_comments_style.html#Coverage_table

gianmarcoschifone · 2026-05-19T08:49:00Z

Changed TOC style and added javadoc to the private method

romani · 2026-05-19T12:56:44Z

@Zopsss

reasoning why we have links to all blocks of text in style guide:
Based on experience from Google style coverage, each sentence in guide may contains hint to rule that is wil lbe up to our interpretation to cover it or not. Wording sometime is more like recomentation not a rule.
If there is big block of text, a lot of sentences, it becomes hard to track that we read all , and there is definitely no rules in set of sentences.
Likely in Google style all is already in links and small chapters. It is not a case for Doc style, it is LESS structured.
So we need to slice and dice it to be always confident that we read all and non of them have rules. Users can come to us and ask why certain sentence is not a rule in Checkstyle, sliced and dices doc will help us to keep context on decision in separate issues, so it will easier to find our decision on each sentence.

Zopsss · 2026-05-19T15:16:58Z

Okay, let's keep the bullet points. And I've already replied regarding the tags documentation part.

Zopsss · 2026-05-19T15:19:51Z

how can we make guide page to look good in mobile browser?

Sorry I'm not able to understand, are you asking to improve the UI and Table design? this will include improving CSS, might also require JS too. Or just formatting of it? This will include only improving wording and HTML of the table.

romani · 2026-05-19T15:43:47Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/0eb9c0b_20260519084502/styleguides/doc-comments-style/doc-comments-styleguide.html

Text is not wrapped in good way on mobile phone. Font is too little, it required to zoom in and scroll horizontala few times to finish reading.

It would help me alot if it looks like

When phone browser is used.

But this can be done is separate issue, not a blocker here

romani · 2026-05-19T15:44:42Z

@Zopsss , I a little not sure on review status from you. Are you ok to merge or some items should be done?

Zopsss · 2026-05-20T05:42:50Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/0eb9c0b_20260519084502/styleguides/doc-comments-style/doc-comments-styleguide.html

Text is not wrapped in good way on mobile phone. Font is too little, it required to zoom in and scroll horizontala few times to finish reading.

This can be fixed via CSS. We can tackle this in different issue. @gianmarcoschifone please open an issue regarding this.

Zopsss · 2026-05-20T05:48:12Z

I a little not sure on review status from you. Are you ok to merge or some items should be done?

Last change is required: #19828 (comment)

romani · 2026-05-20T12:05:05Z

@gianmarcoschifone , please do this last point.
We are very close to merge.

…rage Page

gianmarcoschifone · 2026-05-20T16:32:44Z

GitHub, generate website

github-actions · 2026-05-20T16:44:46Z

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8c24aed_20260520164406/index.html

https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/8c24aed_20260520164406/doc_comments_style.html#Coverage_table

gianmarcoschifone · 2026-05-20T16:45:54Z

@Zopsss @romani done

Zopsss

LGTM. It's a very good start for our project!! @gianmarcoschifone

romani approved these changes May 17, 2026

View reviewed changes

romani assigned Zopsss May 17, 2026

gianmarcoschifone mentioned this pull request May 18, 2026

Coverage of Documentation Comments Style Guide #19807

Open

Zopsss suggested changes May 19, 2026

View reviewed changes

gianmarcoschifone force-pushed the chapternum branch from 485efb5 to 0eb9c0b Compare May 19, 2026 08:28

This comment was marked as off-topic.

Sign in to view

Zopsss suggested changes May 20, 2026

View reviewed changes

Issue checkstyle#19827: Remove chapter numbers from Doc Comments Cove…

8c24aed

…rage Page

gianmarcoschifone force-pushed the chapternum branch from 0eb9c0b to 8c24aed Compare May 20, 2026 16:28

Zopsss approved these changes May 21, 2026

View reviewed changes

romani merged commit 3056d95 into checkstyle:master May 21, 2026
128 checks passed

romani mentioned this pull request May 21, 2026

Cached page of Documentation style guide should be open in mobile browser in easy to read rendering #19905

Closed

gianmarcoschifone deleted the chapternum branch May 21, 2026 08:06

This was referenced May 29, 2026

Issue #19926: Add Documenting Default Constructors coverage #19992

Open

Issue #19827: Complete removal of chapter numbers in Doc Comments #19996

Merged

Uh oh!

Conversation

gianmarcoschifone commented May 16, 2026

Uh oh!

gianmarcoschifone commented May 16, 2026

Uh oh!

github-actions Bot commented May 16, 2026

Uh oh!

romani left a comment

Choose a reason for hiding this comment

Uh oh!

Zopsss left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Zopsss left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

romani May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

romani commented May 19, 2026

Uh oh!

gianmarcoschifone commented May 19, 2026

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

gianmarcoschifone commented May 19, 2026

Uh oh!

romani commented May 19, 2026

Uh oh!

Zopsss commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Zopsss commented May 19, 2026

Uh oh!

romani commented May 19, 2026

Uh oh!

romani commented May 19, 2026

Uh oh!

Zopsss commented May 20, 2026

Uh oh!

This comment was marked as off-topic.

Uh oh!

Zopsss commented May 20, 2026

Uh oh!

romani commented May 20, 2026

Uh oh!

gianmarcoschifone commented May 20, 2026

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

gianmarcoschifone commented May 20, 2026

Uh oh!

romani May 19, 2026 •

edited

Loading

Zopsss commented May 19, 2026 •

edited

Loading