docs: correct and complete library documentation#337
Merged
Conversation
|
An automated preview of the documentation is available at https://337.capy.prtest3.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-06-25 19:28:11 UTC |
|
GCOVR code coverage report https://337.capy.prtest3.cppalliance.org/gcovr/index.html Build time: 2026-06-24 19:04:22 UTC |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop-2 #337 +/- ##
============================================
Coverage ? 98.39%
============================================
Files ? 83
Lines ? 4233
Branches ? 0
============================================
Hits ? 4165
Misses ? 68
Partials ? 0
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
mvandeberg
force-pushed
the
docs/pass2
branch
2 times, most recently
from
3e87d0f to
9d233ed
Compare
4 tasks
Bring the documentation in line with the implementation across public-header docstrings and the Antora manual. Headers: - read_until: the match position is returned on success, not on error. - dynamic_buffer: flat/circular/vector/string are all adapters over external storage; the value-type category is for user-defined owning buffers. - Add missing docstrings to public symbols: task/quitter promise types, the delay awaitable, fuse::result, make_buffer overloads, the recycling memory resource, and frame_alloc_mixin's operator new. - Remove buffer_param references to a nonexistent max_size member. - Note that the recycling memory resource ignores the requested alignment. - Fix this_coro/run_async examples and document the environment precondition. - Correct the executor concept example, io_runnable handle() constness, the executor_ref example, pull_from parameter descriptions, and timeout/when_all and when_any @throws clauses. - Name strand's template parameter Ex and correct its dispatch condition. - Correct the overstated no-throw guarantee on the test mock streams. Manual: - IoAwaitable: the custom-awaitable example resumes the caller by wrapping its handle in a continuation and posting that to the executor; dispatch/post take a continuation&, not a raw coroutine_handle. - Construct buffers from arrays/containers with make_buffer, not mutable_buffer (which has no array/range constructor), in the read/stream examples; a string_view is not itself a ConstBufferSequence and must be wrapped with make_buffer. - Document the real fixed 16-entry buffer window for system I/O. - Correct the mock source/sink prose and member tables. - async_event is a manual-reset event, not one-shot. - Fix the custom-dynamic-buffer read loop to check end-of-stream before commit. - Remove a misplaced whole-catalog summary section. - Correct the type-erasure vtable taxonomy and the run_async wrapper snippet. - Replace the cancellation page's timeout example with the real timeout() combinator; bind executor_ref to a named executor. - Document when_all/when_any all-fail semantics (when_any reports an unspecified failure); replace the FrameAllocator concept with the real allocator requirements and document frame_alloc_mixin. - Document read into a DynamicBuffer, the ReadSource read overload, read_until, and write_now; the composed write takes its buffer sequence by value. - Smaller buffer/stream/source corrections (byte-size note, empty/partial read). Buffer and stream specification: - Explain that const_buffer/mutable_buffer are non-owning handles: the caller owns the underlying bytes and their lifetime; the library manages only the handles and handle-sequences it produces. - Strengthen the rationale for void* over std::byte/span, and state that treating a single buffer as a one-element sequence is a deliberate convenience applied consistently across the buffer API. - Note on the ReadStream/WriteStream concepts that the single buffer archetype in the requires-clause is only a representative: the real contract is that the operation accepts any MutableBufferSequence / ConstBufferSequence, which a C++ concept cannot fully express. Addresses cppalliance#273, cppalliance#287, and cppalliance#296.
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.
Bring the documentation in line with the implementation across public-header docstrings and the Antora manual.
Headers:
Manual:
Closes #296
Closes #273