llvm / llvm/llvm-project

[clang-doc] `constexpr` fields are not handled well

Open
#168,127 0 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

Record fields are serialized via `QualType` because `RecordDecl::fields()` returns `FieldDecl`s, which aren't `VarDecl`s. Thus we have less information about them than other variables to document. One problem is that we don't capture their full spelling. For instance, in the basic project, we have:

https://github.com/llvm/llvm-project/blob/8b596224258dae1fc671d70e4f2072e162cd4f59/clang-tools-extra/test/clang-doc/Inputs/basic-project/include/Calculator.h#L61

`static_val` is `constexpr`, but we get its type spelling via `TypePrinter` which doesn't capture the `constexpr`. It only allows us to output `const` because that is actually part of the type. See:

https://github.com/llvm/llvm-project/blob/8b596224258dae1fc671d70e4f2072e162cd4f59/clang-tools-extra/test/clang-doc/basic-project.test#L332

I think it'd be pretty useful to have the actual source spelling since `constexpr` has more implications than just `const`. We also don't currently support documenting the initialization expression. These are both limited by the fact that we use type information to get the spelling, so we need to get to the `VarDecl` somehow.

Contributor guide

Open the contributing guide

Research direction

Start with clang-tools-extra/test/clang-doc/Inputs/basic-project/include/Calculator.h and clang-tools-extra/test/clang-doc/basic-project.test, then trace how clang-doc serializes record fields through QualType. Update the coverage so the constexpr spelling and initialization expression are represented, and run basic-project.test to verify the documented output.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.