When code changes affect how people understand or use behavior—especially grammar directives/annotations or feature support—add documentation that explains intent and keeps docs aligned with current functionality.

Apply this in two ways: 1) For non-obvious inline constructs (e.g., grammar annotations), add an immediate “what/why” comment so readers don’t need to infer meaning from implementation. 2) For user-facing feature support changes (e.g., removing directive support in favor of YAML frontmatter), ensure the relevant developer/user documentation is updated (or explicitly tracked via a follow-up PR) so there’s no mismatch between code and guidance.

Example (grammar annotation):

terminal SANKEY_LINK_VALUE returns number: /"(0|[1-9][0-9]*)(\.[0-9]+)?"|.../;
/**
 * @greedy
 * This token should be matched late so it doesn’t preempt other token rules.
 */
@greedy