llvm / llvm/llvm-project

[clang-doc] Reconstructing a source declaration in Mustache templates is complex

Open
#172,545 4 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

This is what it looks like to recreate the source spelling of a declaration in Mustache templates for a function that might be a specialization:

```html

{{ReturnType.Name}} {{Name}}{{#Template}}{{#Specialization}}<{{#Parameters}}{{Param}}{{^End}}, {{/End}}{{/Parameters}}>{{/Specialization}}{{/Template}} ({{#Params}}{{^End}}{{Type}} {{Name}}, {{/End}}{{#End}}{{Type}} {{Name}}{{/End}}{{/Params}})

```

It's not the most readable and pretty long. If the format of the HTML document were changed (which is currently happening somewhat frequently), then this might also have to change. From my own tinkering, it's also difficult to break these up into easier-to-read chunks with newlines since the declarations are always in `

` tags, meaning indentations are rendered literally.

An alternative to this would be to do the spelling reconstruction beforehand and just emit the entire spelling in the template. We could use something like [`extractapi::DeclarationFragmentsBuilder`](https://clang.llvm.org/doxygen/classclang_1_1extractapi_1_1DeclarationFragmentsBuilder.html) which already handles a lot of this kind of work.

This could also be a bit of a non-issue.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the clang-doc Mustache template that reconstructs declarations and the extractapi::DeclarationFragmentsBuilder entry point. Determine whether declaration spelling can be prepared before rendering, including function specializations. Done means the template is simpler while still emitting the correct complete declaration spelling.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
compilers, documentation
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.