[clang-doc] Handle additional comment types in MustacheHTMLGenerator

[ilovepi]

The new mustache generator is missing support for several comment types. Comparing the MDGenerator cases to what's in Mustache shows that we don't currently handle most cases. Even running the mustache backend over the tests/clang-doc/enum.cpp test triggers an assertion from unhandled an HTMLStartTagComment. Its infeasible that we'd be able to run it over a large codebase like clang until we handle those comment types.

Looking at that implementation, Its also likely that we'd benefit from translating the CommentInfo.Kind field into a strongly typed enum. That would make handling the different comment "kinds" with checked switch statements, rather than the pattern of if/else.

The work here is fairly trivial, though getting it right with the requisite testing in place may take a few iterations.

[llvmbot]

Hi!

This issue may be a good introductory issue for people new to working on LLVM. If you would like to work on this issue, your first steps are:

1. Check that no other contributor is working on this issue. If someone is assigned to the issue or claimed to be working on it, ping the person. After one week without a response, the assignee may be changed.
2. Leave a comment indicating that you are working on the issue, or just create a pull request after following the steps below. Mention this issue in the description of the pull request.
3. Fix the issue locally.
4. Run the test suite locally. Remember that the subdirectories under test/ create fine-grained testing targets, so you can e.g. use make check-clang-ast to only run Clang's AST tests.
5. Create a Git commit.
6. Run git clang-format HEAD~1 to format your changes.
7. Open a pull request to the upstream repository on GitHub. Detailed instructions can be found in GitHub's documentation. Mention this issue in the description of the pull request.

If you have any further questions about this issue, don't hesitate to ask via a comment in the thread below.

[llvmbot]

@llvm/issue-subscribers-good-first-issue

Author: Paul Kirth (ilovepi)

The new mustache generator is missing support for several comment types. Comparing the MDGenerator cases to what's in Mustache shows that we don't currently handle most cases. Even running the mustache backend over the tests/clang-doc/enum.cpp test triggers an assertion from unhandled an HTMLStartTagComment. Its infeasible that we'd be able to run it over a large codebase like clang until we handle those comment types.

Looking at that implementation, Its also likely that we'd benefit from translating the CommentInfo.Kind field into a strongly typed enum. That would make handling the different comment "kinds" with checked switch statements, rather than the pattern of if/else.

The work here is fairly trivial, though getting it right with the requisite testing in place may take a few iterations.

[laurenmchin]

Hello, I'd like to work on this. Could someone please assign this to me?

[ilovepi]

@laurenmchin you're free to work on this. In my experience assigning tasks in github is counter-productive, since contributors often don't follow through. If you make a PR, it will be linked here and you can add maintainers as reviewers. that's a stronger signal IMO that you're working on this.

[snarang181]

@ilovepi, I had a PR #142273 linked to another issue I created which refactors the CommentInfo.Kind structure. Should i just link it to this PR? I had created another issue because the refactoring diff had become quite large.

[ilovepi]

This is just an issue. You’re free to link any number of PRs that work towards closing this issue. I closed the other issue because it was just a duplicate of this. If there were a something significant onto track on its own as part of this, it would be as a sub task. The thing you’re doing though is the core work this issue tracks.

[snarang181]

This is just an issue. You’re free to link any number of PRs that work towards closing this issue. I closed the other issue because it was just a duplicate of this. If there were a something significant onto track on its own as part of this, it would be as a sub task. The thing you’re doing though is the core work this issue tracks.

That makes sense, apologies. Opening sub-tasks makes more sense than opening new issues, I will keep it in mind for the future where it is relevant. Thank you for explaining.

[laurenmchin]

@ilovepi Thanks for the clarification! I'll open a PR as soon as I have something ready.

@snarang181

I’ve been working on implementing support for the remaining comment types in MustacheHTMLGenerator as outlined above.

Given that you've already submitted a PR refactoring CommentInfo.Kind to use a strongly typed enum, I’ll focus on handling the remaining unaddressed comment types and ensuring comprehensive test coverage for these cases. Once your PR is merged, I’d be happy to incorporate your enum into my work.

Please let me know if there’s any overlap I missed or if further coordination is needed.

[snarang181]

@ilovepi Thanks for the clarification! I'll open a PR as soon as I have something ready.

@snarang181

I’ve been working on implementing support for the remaining comment types in MustacheHTMLGenerator as outlined above.

Given that you've already submitted a PR refactoring CommentInfo.Kind to use a strongly typed enum, I’ll focus on handling the remaining unaddressed comment types and ensuring comprehensive test coverage for these cases. Once your PR is merged, I’d be happy to incorporate your enum into my work.

Please let me know if there’s any overlap I missed or if further coordination is needed.

Hello @laurenmchin, I apologize for the confusion. Since I had initially opened another issue for the refactoring of the data type, the title might be misleading. The PR linked to this issue also handles the missing comment types in the case of the mustache format.