llvm / llvm/llvm-project

[clang-doc] Mustache looks up missing tags in parent contexts

Open
#174,359 6 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

If a tag, like `{{#Description}}`, is not found within the current context, then Mustache will go up the stack to find it. This is actually expected behavior according [to the Mustache spec](https://mustache.github.io/mustache.5.html) (See the "Tag Types/Variables") but that means that contexts that don't have partials (namely variables and friends currently) will end up searching parent contexts for the property if it doesn't exist. It seems like partials only search their current given context.

In practice, that means that friends and variables currently cant serialize comments because `{{#Description}}` will render the parent's comments. In theory, this seems to negate most of the logic that was set up to compensate for Mustache's "logic-less" design. It would be unfortunate to have to serialize a `HasVariableDescription` inside a variable JSON object (redundancy), but a full partial just for variables doesn't seem warranted yet.

Contributor guide

Open the contributing guide

Research direction

Start by tracing clang-doc's Mustache context lookup for variables and friends, and compare it with how partials use their current context. Done means missing tags in those contexts no longer render matching properties from parent contexts, while the documented Mustache behavior remains understood for other context types.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Bug
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.