After reading the replies and thinking this through, I think there is a clear, low-impact fix that avoids naming debates entirely.
The core issue is not whether Ast values should be named ast or tree. The issue is that the first LSP hover entry point is not self-contained.
In the Ast.parse hover, the comment says that the result should be freed with tree.deinit(), but the hover never states what tree refers to. At that point, the reader has to infer from context that tree is the returned Ast value. That inference is easy if you already know the code, but it is still implicit.
Given the constraints mentioned in the replies:
treemay be a deliberate name choice to avoid visual confusion withAst- Zig does not require variable names to derive from type names
- std is unlikely to be renamed broadly
The most robust fix seems to be improving the hover-visible doc comment, not renaming identifiers.
For example, the comment could explicitly bind the name once, or avoid the local name entirely, e.g.:
- “Returns an
Ast. The returned value must be freed by callingdeiniton it.” - or “The returned
Ast(referred to astree) must be freed withtree.deinit().”
This keeps existing naming, respects readability concerns, and makes the LSP hover self-contained.
The same approach likely applies elsewhere in std: when a doc comment visible in LSP refers to a name that is not present in the signature (like tree, or single-letter generics), the default should be to explicitly state what that name refers to at the first point of contact, even if other solutions might be better in specific cases.
This is somewhat related to a previous thread I opened about single-letter generic parameters lacking explanation; in both cases, the common issue is that LSP-visible documentation refers to identifiers without binding their meaning at the first point of contact. [1]
[1]: https://ziggit.dev/t/zig-api-naming-single-letter-generics-with-no-explanation/13539