docs: adopt a documentation style guide and bring the docs into compl… - #364
Merged
Merged
Conversation
|
An automated preview of the documentation is available at https://364.corosio.prtest3.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-09-25 21:24:25 UTC |
|
GCOVR code coverage report https://364.corosio.prtest3.cppalliance.org/gcovr/index.html Build time: 2026-09-25 21:46:41 UTC |
mvandeberg
force-pushed
the
pr/doc-updates
branch
4 times, most recently
from
September 25, 2026 20:26
2466812 to
c0adfcb
Compare
…iance Corosio's documentation had no stated standard and no way to check one. This adds both, and applies them. **The standard.** `doc/STYLE_GUIDE.md` defines five axes -- Structure, Accuracy, Wording, Completeness, Presentation -- over the Diátaxis modes, a single-source-of-truth rule for code and signatures, a controlled vocabulary, and the enforcement tiers that say which rules block a merge. **The machinery.** `doc/lint/` holds nine checks: structural AsciiDoc and nav rules, sentence length over both corpora, docstring extraction so prose rules reach the headers, tagged-include resolution, MrDocs reference warnings, a self-test that mutates the linters and asserts they notice, and a gate that compares a run against `baseline.json`. `doc/.vale/` adds the Corosio styles and vocabulary. The Documentation workflow runs all of it, with the structural and sentence-length rules blocking and the reference surface reporting. **The compliance work.** Every page declares its Diátaxis mode; listing blocks are tagged and sourced from compiled snippets rather than pasted; prose links the reference through `cpp:` macros instead of restating signatures; tense, fluff, and terminology follow the guide. The reference side documents every parameter, return value, and backend trait the generator asked for, and MrDocs now builds the public headers with warnings enabled and reports none. **One API change.** The awaitables returned by the I/O initiators were plain structs whose captured arguments, out-parameters, constructor, and CRTP dispatch hook were all public, committing the library to a surface it never intended to offer. Only `await_ready`, `await_suspend`, and `await_resume` are the interface, and the compiler is what calls those; everything else is private now. Member-initialisation order is unchanged. **Repairs the audit turned up.** `message_flags::dont_route` does not exist and five docstrings cited it; `native_tcp`/`native_udp` claimed `family()` was a compile-time constant when only `type()` and `protocol()` are; `local_stream.hpp` referenced a symbol that exists nowhere, which MrDocs renders as nothing rather than a broken link; `io_context.hpp` pointed at a `post()` overload that no longer exists; `shutdown_type` omitted `udp_socket` from the types that use it; `4a.tcp-networking.adoc` re-taught TCP internals the networking tutorial owns and now cross-links them. **Cancellation and message-flag claims.** The cancellation wording `289c5d2c` introduced generalises too far. `decode_io_result` lets a decided result outrank the cancellation flag only when `bytes > 0`, so "an operation whose result is already decided reports that result" holds for byte-transferring operations and fails for zero-byte ones. Narrowed on `tcp_acceptor::cancel`, its `implementation::cancel`, and `resolver::cancel`, whose operations -- accept, wait, resolve -- never transfer a byte, so a racing cancel always reports `operation_canceled`. Left as it was on `tcp_socket`, `local_stream_socket`, `local_datagram_socket`, `udp_socket` and `stream_file`, which do transfer bytes. `close()` in `random_access_file.hpp` and `stream_file.hpp` still carried the pre-`289c5d2c` unconditional claim although it tears down through the same path `cancel()` uses; both now defer to `cancel`'s contract. `udp_socket::implementation`'s four operations described `flags` as "Platform message flags (e.g. `MSG_DONTWAIT`)". At that layer the parameter still carries the portable `message_flags` bit pattern -- the public overloads forward `static_cast<int>(flags)` unchanged and `to_native_msg_flags` translates inside the backend -- and `MSG_DONTWAIT` is not in that mapping at all, which maps only peek, out_of_band and do_not_route. Also: `@return` added to four non-void functions that documented only `@throws` (`random_access_file::size`, `stream_file::implementation::size` and `::release`, `native_resolver::operator=`); `@tparam Ex` added to the executor constructors of `local_stream_socket` and `local_datagram_socket`, matching `tcp_socket`; and `basic_mocket::write_some`'s `@return` now states the partial-write contract `7bc2fa76` introduced. `doc/prompts/` carries the audit and repair tooling that found these, and `doc/design/style-guide-compliance.md` records the adoption plan.
mvandeberg
force-pushed
the
pr/doc-updates
branch
from
September 25, 2026 21:21
c0adfcb to
7cb5334
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
…iance
Corosio's documentation had no stated standard and no way to check one. This adds both, and applies them.
The standard.
doc/STYLE_GUIDE.mddefines five axes -- Structure, Accuracy, Wording, Completeness, Presentation -- over the Diátaxis modes, a single-source-of-truth rule for code and signatures, a controlled vocabulary, and the enforcement tiers that say which rules block a merge.The machinery.
doc/lint/holds nine checks: structural AsciiDoc and nav rules, sentence length over both corpora, docstring extraction so prose rules reach the headers, tagged-include resolution, MrDocs reference warnings, a self-test that mutates the linters and asserts they notice, and a gate that compares a run againstbaseline.json.doc/.vale/adds the Corosio styles and vocabulary. The Documentation workflow runs all of it, with the structural and sentence-length rules blocking and the reference surface reporting.The compliance work. Every page declares its Diátaxis mode; listing blocks are tagged and sourced from compiled snippets rather than pasted; prose links the reference through
cpp:macros instead of restating signatures; tense, fluff, and terminology follow the guide. The reference side documents every parameter, return value, and backend trait the generator asked for, and MrDocs now builds the public headers with warnings enabled and reports none.One API change. The awaitables returned by the I/O initiators were plain structs whose captured arguments, out-parameters, constructor, and CRTP dispatch hook were all public, committing the library to a surface it never intended to offer. Only
await_ready,await_suspend, andawait_resumeare the interface, and the compiler is what calls those; everything else is private now. Member-initialisation order is unchanged.Repairs the audit turned up.
message_flags::dont_routedoes not exist and five docstrings cited it;native_tcp/native_udpclaimedfamily()was a compile-time constant when onlytype()andprotocol()are;local_stream.hppreferenced a symbol that exists nowhere, which MrDocs renders as nothing rather than a broken link;io_context.hpppointed at apost()overload that no longer exists;shutdown_typeomittedudp_socketfrom the types that use it;4a.tcp-networking.adocre-taught TCP internals the networking tutorial owns and now cross-links them.doc/prompts/carries the audit and repair tooling that found these, anddoc/design/style-guide-compliance.mdrecords the adoption plan.