llvm / llvm/llvm-project

[clang-doc] Fix lack of code coverage for missing MD Mustache functionality

Open
#201,945 3 comments 0 reactions 0 assignees View on GitHub
clang-doc
Dominant language
LLVM
Stars
40.5k
Forks
18.7k
PR merge metrics
PR metrics pending

Description

We want to deprecate and remove the original Markdown backend in favor of the Mustache-powered MD backend. We can't currently do that without possibly experiencing regression in Markdown output partially due to the legacy MD lit tests not covering all functionality. The Mustache MD backend is tested on all existing MD lit tests, but that doesn't seem to be enough. We don't necessarily have to patch the functionality in now. Just having some `CHECK-NOT` lines to document missing functionality would be really great and get us on our way to moving to the new generator.

For example, the legacy MD generator can serialize scoped enums:

https://github.com/llvm/llvm-project/blob/276cc2fac75a476824ea25b5349dfbac0d5b5545/clang-tools-extra/clang-doc/MDGenerator.cpp#L231-L239

Mustache MD cannot do the same and the fact that we don't have tests to at least document this is bad:

https://github.com/llvm/llvm-project/blob/276cc2fac75a476824ea25b5349dfbac0d5b5545/clang-tools-extra/clang-doc/assets/md/namespace-template.mustache#L43-L55

It also goes to show how spotty the tests for legacy MD tests are. I identified some with the help of an LLM:

- [ ] [Child records are emitted](https://github.com/llvm/llvm-project/blob/276cc2fac75a476824ea25b5349dfbac0d5b5545/clang-tools-extra/clang-doc/MDGenerator.cpp#L388)
- [ ] [All functions can be rendered including protected/private (so no access control?)](https://github.com/llvm/llvm-project/blob/276cc2fac75a476824ea25b5349dfbac0d5b5545/clang-tools-extra/clang-doc/MDGenerator.cpp#L394)
- [ ] [Virtual parents](https://github.com/llvm/llvm-project/blob/276cc2fac75a476824ea25b5349dfbac0d5b5545/clang-tools-extra/clang-doc/MDGenerator.cpp#L365)
- [ ] Comments, a lot of them. The legacy MD unit tests test this a lot.
- [ ] Repository URLs which are passed optionally.

The unit test suite also has some more functionality that might be missing. Unfortunately, we can't easily access those via Mustache.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.