[akrzemi1]

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]

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-25 17:20:50 UTC

[cppalliance-bot]

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-25 17:43:38 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.47%. Comparing base (158c009) to head (02173f8).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #447   +/-   ##
========================================
  Coverage    98.47%   98.47%           
========================================
  Files          137      137           
  Lines         7293     7293           
========================================
  Hits          7182     7182           
  Misses         111      111           

Flag	Coverage Δ
linux	98.46% <ø> (ø)

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 158c009...02173f8. 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.

1. 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.
2. 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.
3. 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.
4. 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.

[akrzemi1]

@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]

@mvandeberg, rearding your list:

1. Stale link back to 5b. Will fix.
2. 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.
3. Orphaned snippet tags. Will remove them.
4. 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.

[mvandeberg]

@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.

Anything that has further reaching consequences, I have rescinded from my review. The remaining items should be relevant just to this PR. I realize that some of the remaining items are nitpicks, but I am doing this because we already have people using capy and reading the documentation. It is worth the extra work of cleaning up the small messes as we remodel the documentation.

[akrzemi1]

Ok, made some further refactorings.

[akrzemi1]

@mvandeberg, are you seeing these updates?