Google Summer of Code 2026 Final Report

Project: Coverage of Documentation Comments Style Guide

Student: Gianmarco Schifone

Organization: Checkstyle

Mentors: Roman Ivanov, Mauryan Kansara, Mohamed Mahfouz, Anmol202005

Project Goals

This project focuses on improving Javadoc support in Checkstyle and implementing coverage for Oracle’s Documentation Comments Style Guide. The guide is written as prose, so the main goal was to turn its rules into something Checkstyle users can actually run and understand.

The main user-facing result is the Documentation Comments coverage page, which brings together the ready-to-use configuration, examples, tests, and rule-by-rule coverage status. It shows which rules are supported, which rules are only partially covered, and which rules are not suitable for Checkstyle because they depend too much on human judgment or project-specific conventions.

Another important goal was to improve the implementation behind Javadoc checks. Several rules need proper understanding of Javadoc tags, references, text, and their relation to Java code. Because of this, the project also included work on Checkstyle’s ANTLR-based Javadoc parser and AST construction, migration of existing checks to Javadoc AST-based analysis, and creation of new checks where Checkstyle did not have enough support.

What I Did During GSoC

The work was completed in several main areas.

1. Documentation Comments profile

I started by adding the base infrastructure for the Documentation Comments style guide. This included the configuration file, the generated coverage table, the cached copy of Oracle’s guide used by the website, and the first set of integration tests and examples.

I also added validation for the new page and configuration, so broken links, missing samples, duplicated modules, and invalid coverage entries are caught by tests.

2. Rule-by-rule coverage

After the infrastructure was ready, I reviewed Oracle’s guide section by section. For each rule, I checked if it was already covered by an existing Checkstyle check, if the check needed new configuration, or if new support had to be added. For rules that could not be enforced reliably, I documented the limitation.

3. Parser and AST work

A large part of the project was connected to Checkstyle’s ANTLR-based Javadoc parser and the visitor layer that builds Checkstyle’s Javadoc AST from the parse tree. I fixed grammar and parser problems found while running checks on real projects and while comparing behavior with the JDK javadoc tool. The parser fixes included cases around references, URI fragments, generic outer and inner class links, quoted inline values, method references, link labels with braces, block tags after multiple leading asterisks, and column positions for leading asterisks.

I also migrated several important Javadoc checks to use the parsed Javadoc AST. This changed how the checks read comments: instead of depending on older text or tag handling, they can work with the structured Javadoc tree. These migrations required updates to the checks, shared utility code, tests and examples.

4. New checks and check updates

I added new checks and extended existing ones where the guide required behavior that was not available before. This included support for default constructor documentation, author tag validation, a new regular-expression based Javadoc check for text rules, and more complete handling of several Javadoc tag requirements.

I also removed an obsolete Javadoc style check after its responsibilities were covered by newer checks and configuration. I updated documentation and regression configs for that migration so users and maintainers could see what changed and why.

5. CI and regression validation

I added CI validation that runs the JDK javadoc tool and doclint on Javadoc test inputs and examples. This helped separate real Checkstyle behavior from invalid Javadoc syntax.

I worked in the test-configs repository as well. For Javadoc checks, I created a dedicated project list with its own exclusions. The goal was to skip files in external projects that already contain invalid Javadoc, so regression reports can focus on Checkstyle behavior instead of failures caused by broken input in real codebases.

6. Review and follow-up work

Most large PRs were validated with diff reports. I investigated reported differences, checked whether they were expected, and updated tests, suppressions, or implementation details when needed. Some review discussions also turned into follow-up issues.

Current Status and Future Work

All GSoC-related PRs from the linked period are merged. The project has 73 merged PRs in the main Checkstyle repository and 8 merged PRs in the test-configs repository.

The Documentation Comments configuration is ready to use, and the coverage page is available as part of Checkstyle’s documentation. Parser fixes, AST-based migrations, new check support, CI validation, and regression-test support are also merged.

There are still areas where the work can continue:

Add new checks for guide rules that can be enforced reliably.
Improve parser coverage when new real-world Javadoc cases are found.
Keep the Documentation Comments configuration and coverage page updated as Checkstyle changes.

Code Contributions

I contributed 81 merged PRs during the GSoC period: 73 in checkstyle/checkstyle and 8 in checkstyle/test-configs. The complete list is available here: merged GSoC PRs.

Main groups of contributions:

Coverage infrastructure and guide mapping: #19801, #19828, #19942, #20960, and many follow-up PRs that mapped individual sections of the guide.
Migration to AST-based Javadoc checks: #19963, #20300, #20752, #20892.
Javadoc parser fixes: #20294, #20308, #20341, #20394, #20445, #20503, #20839, #20934.
New checks and check updates: #21189, #21217, #21070, #21106.
Javadoc validation and CI work: #20635, #20663, #20704.
Regression-test configuration work: #236, #239, #245, #246, #255.
Migration and maintenance work: #20582, #21131, #250.

What I Learned During GSoC

Technical Skills:

Parser and AST work: I learned how ANTLR lexer and parser grammars handle a domain-specific syntax, how a parse tree is converted into an AST, and how small grammar changes can affect higher-level analysis.
Static analysis rules: I gained more experience writing and updating rule implementations, deciding when a rule needs new logic, and when configuration or documentation is enough.
Regression analysis: I learned how to read large diff reports, identify false positives and false negatives, and compare tool behavior with a reference implementation.
Testing and CI: I worked with integration tests, generated documentation tests, mutation testing, coverage checks, syntax validation, and CI jobs that protect both code and documentation.

Non-Technical Skills:

Project planning: I learned how to split a large project into small issues and PRs that can be reviewed and merged independently.
Communication: I improved how I write PR descriptions, explain behavior changes, and answer review comments with concrete examples.
Open-source collaboration: I learned how maintainers think about compatibility, releases, migration paths, and long-term maintenance in a mature project. I also reviewed PRs from other contributors, which helped me look at changes from a maintainer’s perspective.

Overall, GSoC helped me become more confident working on a large codebase.

Acknowledgements

I want to thank my mentors Roman Ivanov, Mauryan Kansara, Mohamed Mahfouz, and Anmol202005 for their guidance, reviews, and support throughout the project. Their feedback helped me understand the codebase better and improve the quality of each PR.

I also want to thank the Checkstyle community. The previous GSoC work on the Javadoc parser was an important base for this project, and my work continues in the same direction by improving how Checkstyle handles Javadoc in practice.