Re-enable AllPublicDeclarationsHaveDocumentation and finish public API doc comments

[leogdion]

Background

While un-skipping the CI lint job (see #152), we fixed all SwiftLint violations and most missing documentation. To land a green CI now, the swift-format rule AllPublicDeclarationsHaveDocumentation was temporarily disabled in .swift-format (set to false).

Originally there were 411 public/package declarations missing /// doc comments. Most were written during this pass (BushelFactory, MacOSCore, FoundationWax, TestUtilities, Library/LibraryWax, VirtualBuddy/Hub/HubIPSW, Foundation/Args/GuestProfile, Utilities/UT/Logging, etc.), but roughly 150 remained unfinished across these modules when we stopped:

• Sources/BushelMachineWax (~44)
• Sources/BushelMachine (~30)
• Sources/BushelFactory (partial)
• Sources/BushelUtilities (~18, incl. UInt128.swift operators)
• Sources/BushelArgs, BushelGuestProfile, BushelFoundation (small remainders)

Note: several doc-comment agents completed their modules fully; the exact remainder should be re-measured after re-enabling the rule.

Task for the next alpha (v3.0.0-alpha.5)

1. Set "AllPublicDeclarationsHaveDocumentation": true in .swift-format.
2. Run LINT_MODE=STRICT ./Scripts/lint.sh to get the current list of undocumented public declarations.
3. Add meaningful /// doc comments to each (real summaries, not placeholders; include - Parameters/Returns/Throws for functions).
4. Watch for two gotchas seen during this pass:
   • A // swiftlint:disable:next force_unwrapping directive must sit directly above the !-bearing line, not between the doc comment and the declaration (otherwise orphaned_doc_comment fires). Splitting the value onto its own line works.
   • Added doc comments can push files over the file_length (225) limit or lines over line_length (108) — wrap long doc lines and split oversized files (but beware private/fileprivate initializers that only compile within the same file, e.g. LibraryError).

Context

• Doc rule disabled in commit on branch v3.0.0-alpha.4.
• All other lint categories (file_name, force_unwrapping, explicit_acl, ordering, file_length, formatting) are fully fixed and green under LINT_MODE=STRICT.

🤖 Generated with Claude Code