sean/zelnet
Watch
1
0
Fork
You've already forked zelnet
 0
Code Issues Pull requests Projects Releases 61 Packages Wiki Activity

docs: rewrite all documentation to ASD-STE100 #87

Merged
sean merged 2 commits from docs/asd-ste100-rewrite into trunk 2026-08-07 16:36:16 +00:00
Conversation 0 Commits 2 Files changed 42 +2348 -1820
sean commented 2026-08-07 14:13:53 +00:00
Owner
Copy link

Summary

  • Rewrite README.md, AGENTS.md, STYLE.md, CHANGELOG.md, and docs/HOSTSERVER.md in ASD-STE100 Simplified Technical English.
  • Rewrite every //////! Zig doc comment across all 37 source files that had one, in the same style. Inline // comments and code are untouched (verified by diff).
  • No technical fact, command, version, date, or protocol detail was changed - only sentence structure and word choice, per the AGENTS.md directive (commit cda08be) requiring ASD-STE100 for all documentation.

Verification

  • zig build test, zig build, zig build check, zig fmt --check all pass clean.
  • Cross-compiled windows/gui.zig (-Dgui -Dtarget=x86_64-windows) and built macos/gui.zig (-Dgui) natively - both compile clean.
  • Every file's diff was checked to confirm only //////! lines (or prose in the 5 markdown docs) changed - no code or // comments touched.
  • Markdown table row counts and code-fence counts in docs/HOSTSERVER.md are identical before/after (tables and code blocks were left untouched by design).

Found but out of scope

Three pre-existing doc-comment and declaration misattachment bugs surfaced during review (a doc block describes a different function than the one below it). These are preserved as-is since fixing them is a content change, not a style rewrite:

  • src/hostserver/database.zig: the block above fetchLob starts by describing writeRows's EOF contract.
  • src/host.zig: the block above fmtEpoch describes fileConnect's return contract.
  • macos/gui.zig: the block above aidEnter mostly describes zelnet_key's NSView key-handling.

Happy to file these as follow-up issues if wanted.

Test plan

  • zig build test
  • zig build
  • zig build check
  • zig fmt --check
  • Manual diff review of every changed file for scope and technical accuracy
## Summary - Rewrite README.md, AGENTS.md, STYLE.md, CHANGELOG.md, and docs/HOSTSERVER.md in ASD-STE100 Simplified Technical English. - Rewrite every `///`/`//!` Zig doc comment across all 37 source files that had one, in the same style. Inline `//` comments and code are untouched (verified by diff). - No technical fact, command, version, date, or protocol detail was changed - only sentence structure and word choice, per the AGENTS.md directive (commit cda08be) requiring ASD-STE100 for all documentation. ## Verification - `zig build test`, `zig build`, `zig build check`, `zig fmt --check` all pass clean. - Cross-compiled `windows/gui.zig` (`-Dgui -Dtarget=x86_64-windows`) and built `macos/gui.zig` (`-Dgui`) natively - both compile clean. - Every file's diff was checked to confirm only `///`/`//!` lines (or prose in the 5 markdown docs) changed - no code or `//` comments touched. - Markdown table row counts and code-fence counts in docs/HOSTSERVER.md are identical before/after (tables and code blocks were left untouched by design). ## Found but out of scope Three pre-existing doc-comment and declaration misattachment bugs surfaced during review (a doc block describes a different function than the one below it). These are preserved as-is since fixing them is a content change, not a style rewrite: - `src/hostserver/database.zig`: the block above `fetchLob` starts by describing `writeRows`'s EOF contract. - `src/host.zig`: the block above `fmtEpoch` describes `fileConnect`'s return contract. - `macos/gui.zig`: the block above `aidEnter` mostly describes `zelnet_key`'s NSView key-handling. Happy to file these as follow-up issues if wanted. ## Test plan - [x] `zig build test` - [x] `zig build` - [x] `zig build check` - [x] `zig fmt --check` - [x] Manual diff review of every changed file for scope and technical accuracy 
Rewrite README.md, AGENTS.md, STYLE.md, CHANGELOG.md, and
docs/HOSTSERVER.md in ASD-STE100 Simplified Technical English: short
single-idea sentences, active voice, simple vocabulary, and consistent
terminology. No technical facts, commands, versions, or dates changed —
only sentence structure and word choice.
docs: rewrite Zig doc comments to ASD-STE100
All checks were successful
pipeline/ci CI green @ 2b864e034724
Details
2b864e0347
 
Rewrite every /// and //! doc comment across all 37 source files with
public/private documentation, in ASD-STE100 Simplified Technical
English: short single-idea sentences, active voice, simple vocabulary,
"must"/"must not"/"can" for obligation/prohibition/capability.

Scope is doc comments only — inline // implementation comments and all
code are untouched (verified via diff). Every documented technical
fact, byte offset, protocol caveat, and contract is preserved; dense
sentences were split rather than shortened at the cost of meaning.

zig build test, zig build, zig build check, and zig fmt --check all
pass clean, including a Windows cross-compile smoke of windows/gui.zig.

Found and left in place (out of scope for a style-only rewrite) two
pre-existing doc/code misattachment bugs where a doc comment block
describes a different declaration than the one it sits above:
src/hostserver/database.zig (writeRows/fetchLob) and src/host.zig
(fileConnect/fmtEpoch).
sean merged commit 2b864e0347 into trunk 2026-08-07 16:36:16 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
sean/zelnet!87
No description provided.