docs: byte counting goes to buffer algos page by akrzemi1 · Pull Request #447 · cppalliance/capy

akrzemi1 · 2026-10-07T21:27:44Z

Did some reshuffling in Buffers docs, so that buffer counting is in buffer algrithms.
Removed buffe_length from the docs as we are getting consensus to remove it altogether.

Did some reshuffling in Buffers docs, so that buffer counting is in buffer algrithms. Removed buffe_length from the docs as we are getting consensus to remove it altogether.

cppalliance-bot · 2026-10-07T21:35:25Z

An automated preview of the documentation is available at https://447.capy.prtest3.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-10-10 20:04:22 UTC

cppalliance-bot · 2026-10-07T21:47:16Z

GCOVR code coverage report https://447.capy.prtest3.cppalliance.org/gcovr/index.html
LCOV code coverage report https://447.capy.prtest3.cppalliance.org/genhtml/index.html
Coverage Diff Report https://447.capy.prtest3.cppalliance.org/diff-report/index.html

Build time: 2026-10-10 20:19:21 UTC

codecov · 2026-10-07T21:57:10Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.09%. Comparing base (f764adc) to head (d04c51a).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #447   +/-   ##
========================================
  Coverage    98.09%   98.09%           
========================================
  Files          130      130           
  Lines         6289     6289           
========================================
  Hits          6169     6169           
  Misses         120      120

Flag	Coverage Δ
linux	`98.08% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f764adc...d04c51a. Read the comment docs.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

mvandeberg

I can't accept the PR as is because it removes documentation of buffer_length without removing buffer_length. Those should both happen at the same time.

In the meantime, I am leaving my review of the doc changes itself so it can be ready to go when we remove buffer_length.

Stale link back to 5b. 4.coroutines/4g.composition.adoc:147-148 still says read_all lives on Composite Buffers and links there. Now that it's on Buffer Algorithms, the link should be xref:5.buffers/5d.buffer-algo.adoc#_consuming_buffers[Buffer Algorithms]. The NOTE on 5d links to 4g, so the two pages should point at each other.
buffer_length is still used elsewhere. The commit drops buffer_length from the buffer pages because it's slated for removal. 8.examples/8c.buffer-composition.adoc:54 still tells readers to use buffer_length(), and example/buffer-composition/buffer_composition.cpp calls it 3 times (lines 58, 93, 113). Should those change here, or in the PR that removes the function? Either way, the IMPORTANT box this PR deletes was the only place that explained the difference from buffer_size.
Orphaned snippet tags. test/doc/snippets/5d_buffer_algo.cpp still has tag::buffer_empty_example (line 308) and tag::buffer_length_example (line 325), but no page includes them now. The include-tag check only catches includes of missing tags, not tags nobody includes, so nothing will flag this. See the inline comment on 5d line 24 for buffer_empty. buffer_length_example / testBufferLength can go now or with the function's removal.
5b rationale now points forward. 5b.composite-buffers.adoc:155 ("The slice views from cpp:buffer_slice[] and cpp:consuming_buffers::data[]...") explains the bidirectional requirement using two types the reader now meets only on the later 5d page. An xref to Buffer Algorithms, or moving that reason to 5d, would fix the ordering.

mvandeberg · 2026-10-09T20:32:34Z


-cpp:buffer_length[] returns the *number of buffers* in the sequence:
+
+cpp:buffer_empty[] reports whether a sequence carries no data, 


This section lost its example. The buffer_empty_example include was dropped, but the tagged, tested fragment is still in the snippet file. Could you include it again after this paragraph?

[source,cpp] ---- include::example$snippets/5d_buffer_algo.cpp[tag=buffer_empty_example,indent=0] ----

Would it be ok, if I consequently remove the example from the cpp file.
This example contributes nothing to the user's understanding of the library, and at the same time makes the docs longer.

mvandeberg · 2026-10-09T20:34:46Z

+This would translate into later using a zero-size buffer. 
+
+
+== buffer_slice


The other headings on this page describe tasks ("Counting Bytes", "Copying", "Partial Transfer Loops"), but these two are bare identifiers (also consuming_buffers on line 52). How about == Slicing and == Consuming Buffers? The second one keeps the generated ID _consuming_buffers, so <<_consuming_buffers>> on line 108 still resolves.

If this is ok with you, I would address it in a separate PR. A PR that rewrites the entire Buffer algorithms section.

mvandeberg · 2026-10-09T20:35:37Z

-include::example$snippets/5d_buffer_algo.cpp[tag=buffer_empty_example,indent=0]
+include::example$snippets/5d_buffer_algo.cpp[tag=consuming_buffers_include]
+
+include::example$snippets/5d_buffer_algo.cpp[tag=read_all,indent=0]


After the move, the page shows the same consuming_buffers loop twice: read_all here and read_full (tag=read_loop) under Partial Transfer Loops. They differ only in break vs co_return and in a concrete vs generic stream type. I'd keep one. For example, keep read_all here and let Partial Transfer Loops show just write_full with a pointer back, or drop read_all and point forward to read_loop. Note that the NOTE below refers to read_all by name.

Same request. Can we wait with this to another PR?
The presentation of buffer algorithms requires a huge rewrite, anyway. I do not think that this PR adds any confusion relaive to the initial state.
This PR focuses only on drwing the line between composite buffers themselves and buffer algorithms.

mvandeberg · 2026-10-09T20:37:38Z

 // Buffer algorithms
 // ---------------------------------------------------------------------

+using Stream = capy::test::stream;


The template parameter Stream in read_full and write_full further down the file hides this alias. So on the rendered page, Stream is a concrete test type in read_all and a ReadStream-constrained parameter in read_loop. If read_all stays, it could take
template<capy::ReadStream Stream, capy::MutableBufferSequence Buffers> like read_full, and the alias would only be needed by send_sliced. Renaming the alias (for example test_stream) would also work.

Just please note that this strange pattern is present in the docs even before my PR: https://github.com/cppalliance/capy/blob/develop/test/doc/snippets/5b_composite_buffers.cpp#L205

I am not adding this mess, it is preexistent. My PR only mkes it visible that there are things in the docs today. I cannot fix the entire docs with one PR. I already have the fixing of the other parts of Buffers on my plate. This was meant to be a simple PR that draws the line between Comosite buffers and algorithms.

mvandeberg · 2026-10-09T20:38:22Z

+        auto combined = std::array{buf1, buf2, buf3};

-        std::size_t total = capy::buffer_size(combined);  // 10
+        assert(capy::buffer_size(combined) == 10);


Nit: the other fragments on this page show results as comments
(// 11 in buffer_copy_example, for instance). The assert does nothing under NDEBUG, and the BOOST_TEST two lines down already checks the same thing. Either style works, but one style per page would be more consistent.

Again, would you agree to a separate PR?

akrzemi1 · 2026-10-10T13:05:14Z

@mvandeberg, thank you for the review. Could we assume the view that I am doing incremental changes to the Buffers docs, only a subsection or two at a time?
For instance, while I agree that consuming_buffers and buffer_slce require changes, I would rather defer them to a separate PR. They require a lot of changes and a separate thought/reflection process.

akrzemi1 · 2026-10-10T13:59:57Z

@mvandeberg, rearding your list:

Stale link back to 5b. Will fix.
buffer_length is still used elsewhere. I will put the documentation of the function back. Another PR will remove it consistently, and rename buffer_size to something like buffer_byte_count.
Orphaned snippet tags. Will remove them.
5b rationale now points forward. I'll put the rationale to the very end of Buffers section for now. In subsequent PR I will revise the rationale. Some parts are no loner necessary.

docs: byte counting goes to buffer algos page

b09dde9

Did some reshuffling in Buffers docs, so that buffer counting is in buffer algrithms. Removed buffe_length from the docs as we are getting consensus to remove it altogether.

akrzemi1 requested review from mvandeberg and sgerbino October 7, 2026 21:27

github-project-automation Bot added this to Beast2 Oct 7, 2026

mvandeberg reviewed Oct 9, 2026

View reviewed changes

akrzemi1 added 2 commits October 10, 2026 21:08

docs: minor fixes in Buffers section

8a7b759

docs: fix spelling and grammar in Buffers

d04c51a


		cpp:buffer_length[] returns the number of buffers in the sequence:

		cpp:buffer_empty[] reports whether a sequence carries no data,

		This would translate into later using a zero-size buffer.


		== buffer_slice

Conversation

akrzemi1 commented Oct 7, 2026

Uh oh!

cppalliance-bot commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cppalliance-bot commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mvandeberg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

akrzemi1 commented Oct 10, 2026

Uh oh!

akrzemi1 commented Oct 10, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cppalliance-bot commented Oct 7, 2026 •

edited

Loading

cppalliance-bot commented Oct 7, 2026 •

edited

Loading

codecov Bot commented Oct 7, 2026 •

edited

Loading