GSoC 2025 - New ANTLR Grammar For Javadoc Comments

24 views
Skip to first unread message

mohamed mahfouz

unread,
Jun 10, 2025, 9:32:54 PMJun 10
to checkstyle-devel
Wednesday, 10 June report

What I have done so far:

- Introduces the initial version of the ANTLR-based parser grammar for Javadoc comments. It defines rules for:  
  1.   Main description, block tags, and inline tags

  2. Inline tag support: "{@code}, {@link}, {@linkplain}", and generic inline tags

  3. Block tag support: "@return, @param", and generic block tags.

  4. HTML parsing inside Javadoc, including normal and void HTML elements.

- Used a lightweight test framework that visualizes Javadoc comments as parse trees. This ensures that grammar changes are regression-tested and easy to validate

- Merged this PR that continues all of the previous points.

What I will be doing this week:

- Handle non-tight HTML elements (e.g., HTML tags are not closed in Javadoc)
-  Some open questions remain around error recovery vs. strict parsing
-  Continue iterating on the tree shape




       

mohamed mahfouz

unread,
Jun 18, 2025, 5:52:31 AMJun 18
to checkstyle-devel
Wednesday, 18 June report

Merged PRs:
  1. https://github.com/checkstyle-GSoC25/javadoc-parser/pull/18

Now, after we merge this open PR, we should be more comfortable with the parser's ability to parse HTML content, including tight, void, or non-tight tags.


What I will be doing this week:
I opened a tracker issue to track the inline tag support. I will work on this issue to plan and implement the inline tags rules.

mohamed mahfouz

unread,
Jun 25, 2025, 8:52:08 PMJun 25
to checkstyle-devel
Wednesday, 25 June report

Merged PRs:
What I will be doing this week
  1. Complete the remaining inline tags (Finish this issue)
  2. Start planning for Javadoc block tags

mohamed mahfouz

unread,
Jul 2, 2025, 6:56:46 AMJul 2
to checkstyle-devel
Wednesday, 2 July report

Merged PRs:
Open PRs:

Once the open PR implementing snippet tag parsing is merged, we can close the issue for supporting inline tags. I have also opened a new issue to track block tags support, which I will be working on this week.

mohamed mahfouz

unread,
Jul 9, 2025, 3:56:16 PMJul 9
to checkstyle-devel

Wednesday, 9 July report

Merged PRs:
Once we merge the two open PRs, support for all block tags will be complete, and we can close the corresponding issue. We had agreed that our goal was to finish all block tag support before the midterm evaluation, and merging these PRs will achieve that. Afterward, we will have one week remaining before the deadline, which we will spend on refactoring and cleanup to ensure the project is in a solid state to begin the integration phase after the midterm evaluation.

mohamed mahfouz

unread,
Jul 19, 2025, 10:42:24 AMJul 19
to checkstyle-devel

Saturday, 19 July report
Merged PRs:

mohamed mahfouz

unread,
Jul 23, 2025, 9:26:38 PMJul 23
to checkstyle-devel

Wednesday, 23 July report

Merged PRs:
  Now that we have completed and refined the parser and lexer, we are moving into the integration phase. In this phase, we will focus on building the AST using visitors. This work will be done in a single open PR. Once that is merged, we will proceed with fixing the checks and making any additional adjustments needed for full integration.  

mohamed mahfouz

unread,
Aug 8, 2025, 11:27:04 AMAug 8
to checkstyle-devel
Wednesday, 6 Aug report

  In the last two weeks, we completed building the AST using visitors and have started the integration phase.  

Merged PRs: 
  1. https://github.com/checkstyle-GSoC25/checkstyle/pull/22 (Replaced the old Javadoc parser with the new one and AST construction using visitor pattern)
  2. https://github.com/checkstyle-GSoC25/checkstyle/pull/27
  3. https://github.com/checkstyle-GSoC25/checkstyle/pull/28
  4. https://github.com/checkstyle-GSoC25/checkstyle/pull/32
  5. https://github.com/checkstyle-GSoC25/checkstyle/pull/38
Open PRs:
  1. https://github.com/checkstyle-GSoC25/checkstyle/pull/29
  2. https://github.com/checkstyle-GSoC25/checkstyle/pull/40
  3. https://github.com/checkstyle-GSoC25/checkstyle/pull/39
  We now have the new parser integrated with the new AST in place. Migration of checks is underway. Three checks have already been migrated:
  • SingleLineJavadocCheck
  • JavadocBlockTagLocationCheck
  • MissingDeprecatedCheck

mohamed mahfouz

unread,
Aug 30, 2025, 9:46:58 AMAug 30
to checkstyle-devel

Saturday 30 Aug report

This month, we continue in the integration phase and update the rest of the checks

Merged PRs: 
  1.  https://github.com/checkstyle-GSoC25/checkstyle/pull/42
  2. https://github.com/checkstyle-GSoC25/checkstyle/pull/45
  3. https://github.com/checkstyle-GSoC25/checkstyle/pull/46
  4. https://github.com/checkstyle-GSoC25/checkstyle/pull/50
  5. https://github.com/checkstyle-GSoC25/checkstyle/pull/51
  6. https://github.com/checkstyle-GSoC25/checkstyle/pull/52
  7. https://github.com/checkstyle-GSoC25/checkstyle/pull/54
  8. https://github.com/checkstyle-GSoC25/checkstyle/pull/55
  9. https://github.com/checkstyle-GSoC25/checkstyle/pull/57
  10. https://github.com/checkstyle-GSoC25/checkstyle/pull/62
  11. https://github.com/checkstyle-GSoC25/checkstyle/pull/64
  12. https://github.com/checkstyle-GSoC25/checkstyle/pull/65
  13. https://github.com/checkstyle-GSoC25/checkstyle/pull/67
  14. https://github.com/checkstyle-GSoC25/checkstyle/pull/68
  15. https://github.com/checkstyle-GSoC25/checkstyle/pull/70
  16. https://github.com/checkstyle-GSoC25/checkstyle/pull/71
  17. https://github.com/checkstyle-GSoC25/checkstyle/pull/73
Opened an issue to track pitest issues (surviving mutations): https://github.com/checkstyle-GSoC25/checkstyle/issues/72

Open PRs:
  1. https://github.com/checkstyle-GSoC25/checkstyle/pull/78
Only two checks are left to finish the check migration process 
  • SummaryJavadoc
  • JavadocParagrpagh
NOTE: The Project timeline is extended by one month
Reply all
Reply to author
Forward
0 new messages