diff --git a/docs/style.md b/docs/style.md index 970aa96..15f905d 100644 --- a/docs/style.md +++ b/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 diff --git a/source/ast/ast.hon b/source/ast/ast.hon index 1d84c7a..12a30c3 100644 --- a/source/ast/ast.hon +++ b/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{ diff --git a/source/ast/renderer/renderer.hon b/source/ast/renderer/renderer.hon index 2efd8ea..f15346d 100644 --- a/source/ast/renderer/renderer.hon +++ b/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") diff --git a/source/diagnostics/diagnostics.hon b/source/diagnostics/diagnostics.hon index 08e11b5..ac26d1d 100644 --- a/source/diagnostics/diagnostics.hon +++ b/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) } } diff --git a/source/lexer/scan.hon b/source/lexer/scan.hon index a43dfc7..bc5d704 100644 --- a/source/lexer/scan.hon +++ b/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( diff --git a/source/parser/parse.hon b/source/parser/parse.hon index 390df87..be6b542 100644 --- a/source/parser/parse.hon +++ b/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. -#! allocator supplies returned node storage and temporary lists released before return. +#! 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. #! the caller owns the Tree and must release it with ast.deinit. parse proc( allocator mem.Allocator, diff --git a/source/sema/resolve.hon b/source/sema/resolve.hon index 2623183..e353f4a 100644 --- a/source/sema/resolve.hon +++ b/source/sema/resolve.hon @@ -53,8 +53,8 @@ State :: struct { allocator mem.Allocator } -#! borrows tree and diagnostic_store during resolution, without retaining their storage. -#! allocator supplies caller-owned bindings and temporary scopes released before return. +#! borrows `tree` and `diagnostic_store` during resolution, without retaining their storage. +#! `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, diff --git a/source/strpool/strpool.hon b/source/strpool/strpool.hon index f1957d9..a691f22 100644 --- a/source/strpool/strpool.hon +++ b/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), diff --git a/std/arraylist/arraylist.hon b/std/arraylist/arraylist.hon index 1765b05..f048ca8 100644 --- a/std/arraylist/arraylist.hon +++ b/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), diff --git a/std/hashmap/hashmap.hon b/std/hashmap/hashmap.hon index 99bef84..e0b34bc 100644 --- a/std/hashmap/hashmap.hon +++ b/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, diff --git a/std/mem/mem.hon b/std/mem/mem.hon index 33d4c23..dee5c1d 100644 --- a/std/mem/mem.hon +++ b/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 }