docs: backtick parameter references in API comments

docs/style.md

@@ -58,6 +58,7 @@ while (
 
 - prefer lowercase prose in documentation, including headings and sentence starts. preserve the case of code identifiers, proper names, and acronyms.
 - write comments for invariants, ownership, or reasons that the code alone does not explain. use `#!` for API documentation.
+- enclose explicit references to parameter identifiers in backticks, for example: “an empty `destination` is a no-op.” leave general conceptual terms unquoted, even when they match a parameter name, for example: “memory must be freed with the same allocator that was used to allocate it.”
 - when editing a function, review its existing comments and API documentation against the resulting implementation. update comments that remain useful; remove those that are obsolete or merely restate self-explanatory code. retain contracts and rationale that callers or maintainers cannot infer from the implementation.
 
 ## library operations

source/ast/ast.hon

@@ -156,7 +156,7 @@ InvalidView :: struct {
     diagnostic DiagnosticId
 }
 
-#! retains allocator for node storage and borrows source; release with deinit_builder.
+#! retains `allocator` for node storage and borrows `source`; release with deinit_builder.
 init_builder proc(allocator mem.Allocator, source []u8) Builder {
     return Builder{
         storage = Storage{

source/ast/renderer/renderer.hon

@@ -7,7 +7,7 @@ Renderer :: struct {
     bytes arraylist.ArrayList(u8)
 }
 
-#! retains allocator for rendered output; the caller owns the returned Renderer.
+#! retains `allocator` for rendered output; the caller owns the returned Renderer.
 init proc(allocator mem.Allocator) Renderer {
     return Renderer{ bytes = arraylist.init(allocator) }
 }
@@ -17,7 +17,7 @@ deinit proc(renderer @mut Renderer) void {
     arraylist.deinit(&renderer.bytes)
 }
 
-#! borrows tree during rendering; output stays renderer-owned until render or deinit.
+#! borrows `tree` during rendering; output stays renderer-owned until render or deinit.
 render proc(renderer @mut Renderer, tree @ast.Tree) void ! mem.AllocError {
     arraylist.clear(&renderer.bytes)
     try append_text(renderer, "package\n")

source/diagnostics/diagnostics.hon

@@ -28,7 +28,7 @@ Store :: struct { list arraylist.ArrayList(Diagnostic) }
 
 CapacityError :: enum { diagnostic_limit_reached }
 
-#! retains allocator for added diagnostics; the caller owns the returned Store.
+#! retains `allocator` for added diagnostics; the caller owns the returned Store.
 init proc(allocator mem.Allocator) Store {
     return Store{ list = arraylist.init(allocator) }
 }

source/lexer/scan.hon

@@ -34,7 +34,7 @@ State :: struct {
     tokens arraylist.ArrayList(Token)
 }
 
-#! retains allocator for scanned tokens; the caller owns the returned State.
+#! retains `allocator` for scanned tokens; the caller owns the returned State.
 init proc(allocator mem.Allocator) State {
     return State{ tokens = arraylist.init(allocator) }
 }
@@ -44,7 +44,7 @@ deinit proc(state @mut State) void {
     arraylist.deinit(&state.tokens)
 }
 
-#! borrows program and diagnostic_store during scanning; tokens remain state-owned.
+#! borrows `program` and `diagnostic_store` during scanning; tokens remain state-owned.
 #! token allocation uses the retained allocator; identifiers use strpool.strings's allocator.
 #! initialize strpool.strings before scanning and keep it alive while using identifier IDs.
 scan proc(

source/parser/parse.hon

@@ -29,8 +29,8 @@ State :: struct {
     next_token usize
 }
 
-#! borrows tokens and source while parsing; the returned Tree borrows source until ast.deinit.
+#! borrows `tokens` and `source` while parsing; the returned Tree borrows `source` until ast.deinit.
-#! allocator supplies returned node storage and temporary lists released before return.
+#! `allocator` supplies returned node storage and temporary lists released before return.
 #! the caller owns the Tree and must release it with ast.deinit.
 parse proc(
     allocator mem.Allocator,

source/sema/resolve.hon

@@ -53,8 +53,8 @@ State :: struct {
     allocator mem.Allocator
 }
 
-#! borrows tree and diagnostic_store during resolution, without retaining their storage.
+#! borrows `tree` and `diagnostic_store` during resolution, without retaining their storage.
-#! allocator supplies caller-owned bindings and temporary scopes released before return.
+#! `allocator` supplies caller-owned bindings and temporary scopes released before return.
 #! release the returned Resolution with deinit, which uses the retained allocator.
 resolve proc(
     allocator mem.Allocator,

source/strpool/strpool.hon

@@ -18,7 +18,7 @@ StringPool :: struct {
     allocator mem.Allocator
 }
 
-#! retains allocator for interned copies and indexes; the caller owns the pool.
+#! retains `allocator` for interned copies and indexes; the caller owns the pool.
 init proc(allocator mem.Allocator) StringPool {
     return StringPool{
         ids = hashmap.init(allocator),

std/arraylist/arraylist.hon

@@ -10,7 +10,7 @@ ArrayList proc($T type) type {
     }
 }
 
-#! retain allocator for later growth and cleanup; this call does not allocate.
+#! retain `allocator` for later growth and cleanup; this call does not allocate.
 init proc($T type, allocator mem.Allocator) ArrayList(T) {
     return ArrayList(T) {
         items = mem.empty(T),

std/hashmap/hashmap.hon

@@ -29,7 +29,7 @@ StringHashMap proc($V type) type {
     return HashMap([]u8, V, str_hash, str_eql)
 }
 
-#! retain allocator for later growth and cleanup; this call does not allocate.
+#! retain `allocator` for later growth and cleanup; this call does not allocate.
 init proc(
     $K, $V type,
     $hash_key proc(key K) usize,

std/mem/mem.hon

@@ -26,7 +26,7 @@ raw_alloc proc(
 }
 
 #! resize caller-owned storage with its original allocator and alignment.
-#! on allocation failure with nonzero new_size, original storage remains caller-owned; release the result with raw_free.
+#! on allocation failure with nonzero `new_size`, original storage remains caller-owned; release the result with raw_free.
 raw_realloc proc(
     allocator Allocator,
     memory ?*mut u8,
@@ -54,7 +54,7 @@ eql proc($T type, left, right []T) bool {
 }
 
 #! assign `value` to each slice element, preserving its typed value rather than repeating a byte.
-#! an empty destination is a no-op.
+#! an empty `destination` is a no-op.
 set proc($T type, destination []mut T, value T) void {
     for (0..destination.len) |i| destination[i] = value
 }