Revise javadoc for all public interfaces

.cursor/rules/doc-awaitable.mdc

@@ -0,0 +1,32 @@
+---
+description: doc javadoc for async awaitable functions of I/O objects
+alwaysApply: false
+---
+
+**Checklist for an outstanding async/awaitable function javadoc:**
+
+Revised checklist:
+
+---
+
+- Keep the ascii-art to a minimum, only add dividers if the class declaration is very long
+- Don't emit @tparam for deduced types or concepts
+- Don't use C-style /* */ comments inside C-style comments
+- Never list std::bad_alloc
+- Don't document detail:: or implementation symbols
+
+**Checklist for an outstanding awaitable function javadoc:**
+
+- **Brief** — One-sentence summary starting with a verb, e.g. "Read data from the stream asynchronously."
+- **Extended description** — Short paragraph explaining what the function does. State that it is an asynchronous operation that suspends the calling coroutine until completion. If composed, state which underlying operations it is implemented in terms of.
+- **Completion conditions** — Bulleted `@li` list of conditions under which the operation completes and the coroutine resumes (e.g. "The supplied buffers are full", "An error occurs", "The operation was canceled").
+- **Concurrency and overlap** — State which operations may be simultaneously in flight. E.g. for a read: "At most one write operation may be in flight concurrently with this read operation. No other read operations may be in flight until this operation completes." Clarify that simultaneous in-flight operations does *not* imply that the initiating calls themselves may be made concurrently; all calls to the stream must be made from the same implicit or explicit serialization context.
+- **`@param` for each parameter** — Including ownership/lifetime semantics. For buffers: state that the caller retains ownership and must guarantee validity until the operation completes. For string/view parameters: state whether the implementation copies the data or requires it to remain valid for the duration.
+- **`@return`** — Describe the returned aggregate and its elements. The first element is always `error_code`. Name and describe each subsequent element (e.g. "bytes_transferred", "endpoint"). Note that the result is customarily destructured by the caller.
+- **Error conditions** — Document the notable `error_code` values or conditions that may appear in the first element. E.g. `capy::cond::canceled` if the stop token was activated or the i/o object's `cancel()` was called, EOF conditions, protocol-specific errors, etc. State that error codes should be compared to error conditions, not specific values.
+- **`@throws`** — Typically only for precondition violations. State which preconditions trigger exceptions, or state that no exceptions are thrown during normal operation.
+- **Cancellation** — State that the operation supports cancellation via `stop_token` propagated through the IoAwaitable protocol, or via the i/o object's `cancel()` member. State that the resulting error compares equal to `capy::cond::canceled`.
+- **`@par Example`** — Two or three `@code` blocks showing different usage patterns: typical happy path with destructuring, error handling, cancellation, different overloads, etc.
+- **`@note` / `@par Remarks`** — Behavioral gotchas. E.g. "This operation may not read all of the requested bytes." Or equivalence to another overload.
+- **`@tparam`** — For non-variadic template parameters. State the concept requirement (e.g. "The type must satisfy the *AsyncStream* concept"). Don't document `Args...`.
+- **`@see`** — Always last. Cross-references to related functions, concepts, and relevant RFC sections.

.cursor/rules/doc-concept.mdc

@@ -0,0 +1,22 @@
+---
+description: doc javadoc for concept declaration
+alwaysApply: false
+---
+
+- Keep the ascii-art to a minimum, only add dividers if the class declaration is very long
+- Don't emit @tparam for deduced types or concepts
+- Don't use C-style /* */ comments inside C-style comments
+- Never list std::bad_alloc
+- Don't document detail:: or implementation symbols
+
+**Rules for concept javadocs:**
+
+- **Brief** — One sentence naming the concept and stating what a conforming type does. E.g. "Concept for types that consume buffer data using callee-owned buffers."
+- **Extended description** — A short paragraph summarizing the pattern the concept models, its purpose, and how it contrasts with related concepts.
+- **`@tparam`** — One entry per template parameter to the concept.
+- **`@par Syntactic Requirements`** — Bulleted `@li` list of every expression that must be valid. For each, state the member name, its arguments, and what it returns (including whether the return type must satisfy another concept like `IoAwaitable`). State the decomposed result tuple.
+- **`@par Semantic Requirements`** — Grouped by operation. For each operation, a bulleted `@li` list describing its behavior, preconditions, postconditions, success/error semantics, and any state transitions (e.g. "no further operations are permitted after EOF").
+- **`@par Buffer Lifetime`** (or equivalent resource lifetime section) — If the concept involves borrowed resources (buffers, handles, views), state exactly when they are valid and what invalidates them.
+- **`@par Conforming Signatures`** — A single `@code` block showing the canonical signatures using pseudo-syntax (e.g. `IoAwaitable auto`). This is the quick-reference that implementers copy from.
+- **`@par Example`** — A `@code` block showing a generic algorithm templated on the concept, demonstrating typical usage with destructuring, error handling, and interaction with related concepts.
+- **`@see`** — Always last. Cross-references to related concepts, concrete models, and foundational concepts the signatures depend on.

.cursor/rules/doc-errors.mdc

@@ -0,0 +1,37 @@
+---
+description: doc javadoc error error_code error_condition enum
+alwaysApply: false
+---
+
+- Keep the ascii-art to a minimum, only add dividers if the class declaration is very long
+- Don't emit @tparam for deduced types or concepts
+- Don't use C-style /* */ comments inside C-style comments
+- Never list std::bad_alloc
+- Don't document detail:: or implementation symbols
+
+**Rules for error_code enum javadocs:**
+
+- **Brief** — One sentence stating the error category, e.g. "Error codes for WebSocket stream operations."
+- **Extended description** — State which operations produce these codes and which error category they belong to.
+- **Portability warning** — State explicitly that callers must never compare received `error_code` values against this enum directly. Received error codes should always be compared against error conditions, which are portable across implementations. These enum values are implementation details subject to change.
+- **Per-enumerator** — Each value gets a short description of the failure it represents.
+- **`@see`** — The corresponding error condition enum, the error category, and the functions that produce these codes.
+
+---
+
+**Rules for error_condition enum javadocs:**
+
+- **Brief** — One sentence stating the condition category, e.g. "Portable error conditions for WebSocket operations."
+- **Extended description** — State that these are the conditions callers should compare against when handling errors. State which `error_code` enums map to these conditions.
+- **Per-enumerator** — Each value gets a description of the abstract failure class it represents, and under what circumstances a received `error_code` will compare equal to it. E.g. "An `error_code` compares equal to `canceled` when the stop token was activated or the i/o object's `cancel()` was called."
+- **`@par Example`** — A `@code` block showing idiomatic comparison:
+   ```cpp
+   auto [ec, n] = co_await stream.async_read(bufs);
+   if(ec == cond::canceled)
+       // handle cancellation
+   else if(ec == cond::end_of_stream)
+       // handle EOF
+   else if(ec)
+       // handle other errors
+   ```
+- **`@see`** — The corresponding error_code enum(s), the error category, and relevant operations.

.cursor/rules/doc-general.mdc

@@ -0,0 +1,32 @@
+---
+description: doc javadoc for general types and functions
+alwaysApply: false
+---
+
+- Keep the ascii-art to a minimum, only add dividers if the class declaration is very long
+- Don't emit @tparam for deduced types or concepts
+- Don't use C-style /* */ comments inside C-style comments
+- Never list std::bad_alloc
+- Don't document detail:: or implementation symbols
+
+**Rules for general type javadocs:**
+
+- **Brief** — One sentence stating what the type is and its primary purpose.
+- **Extended description** — What it does, when to use it, how it relates to other types in the library. Mention ownership semantics, copyability/movability, and thread safety if relevant.
+- **`@tparam`** — For each non-variadic template parameter, state its role and any concept requirements.
+- **`@par Example`** — One or more `@code` blocks showing construction and typical usage.
+- **`@note`** — Gotchas, lifetime constraints, or non-obvious behavior.
+- **`@see`** — Always last. Related types, concepts, and functions.
+
+---
+
+**Rules for general function javadocs:**
+
+- **Brief** — One sentence starting with a verb describing what the function does. If it returns a value, start with "Return".
+- **Extended description** — Preconditions, what the function does, and any side effects. State complexity if non-obvious.
+- **`@param`** — For each parameter. Include ownership, lifetime, and validity requirements.
+- **`@return`** — What is returned and under what conditions the return value varies.
+- **`@throws`** — Each exception type and the condition that triggers it. If noexcept, say so.
+- **`@par Example`** — One or more `@code` blocks. More examples when the function has multiple usage patterns or overloads.
+- **`@note`** — Gotchas, performance considerations, or surprising behavior.
+- **`@see`** — Always last. Related functions, types, and concepts.

include/boost/capy.hpp

@@ -10,51 +10,90 @@
 #ifndef BOOST_CAPY_HPP
 #define BOOST_CAPY_HPP
 
+/** @file
+    @brief Master header including all public capy components.
+
+    Including this header provides access to the complete capy library:
+    coroutine tasks, executors, I/O operations, buffers, and concepts.
+*/
+
+// Core types
+#include <boost/capy/cond.hpp>
+#include <boost/capy/coro.hpp>
+#include <boost/capy/error.hpp>
+#include <boost/capy/io_result.hpp>
+#include <boost/capy/io_task.hpp>
+#include <boost/capy/task.hpp>
+
+// Algorithms
+#include <boost/capy/read.hpp>
+#include <boost/capy/read_until.hpp>
+#include <boost/capy/when_all.hpp>
+#include <boost/capy/write.hpp>
+
+// Buffers
 #include <boost/capy/buffers.hpp>
+#include <boost/capy/buffers/buffer_copy.hpp>
 #include <boost/capy/buffers/buffer_pair.hpp>
 #include <boost/capy/buffers/buffer_param.hpp>
 #include <boost/capy/buffers/circular_dynamic_buffer.hpp>
 #include <boost/capy/buffers/consuming_buffers.hpp>
-#include <boost/capy/buffers/buffer_copy.hpp>
 #include <boost/capy/buffers/flat_dynamic_buffer.hpp>
 #include <boost/capy/buffers/front.hpp>
 #include <boost/capy/buffers/make_buffer.hpp>
 #include <boost/capy/buffers/slice.hpp>
+#include <boost/capy/buffers/some_buffers.hpp>
+#include <boost/capy/buffers/span.hpp>
 #include <boost/capy/buffers/string_dynamic_buffer.hpp>
 #include <boost/capy/buffers/vector_dynamic_buffer.hpp>
+
+// Concepts
+#include <boost/capy/concept/buffer_archetype.hpp>
+#include <boost/capy/concept/buffer_sink.hpp>
+#include <boost/capy/concept/buffer_source.hpp>
 #include <boost/capy/concept/const_buffer_sequence.hpp>
 #include <boost/capy/concept/decomposes_to.hpp>
 #include <boost/capy/concept/dynamic_buffer.hpp>
+#include <boost/capy/concept/execution_context.hpp>
 #include <boost/capy/concept/executor.hpp>
 #include <boost/capy/concept/io_awaitable.hpp>
 #include <boost/capy/concept/io_awaitable_task.hpp>
 #include <boost/capy/concept/io_launchable_task.hpp>
+#include <boost/capy/concept/match_condition.hpp>
 #include <boost/capy/concept/mutable_buffer_sequence.hpp>
 #include <boost/capy/concept/read_source.hpp>
 #include <boost/capy/concept/read_stream.hpp>
+#include <boost/capy/concept/stream.hpp>
 #include <boost/capy/concept/write_sink.hpp>
 #include <boost/capy/concept/write_stream.hpp>
-#include <boost/capy/cond.hpp>
-#include <boost/capy/coro.hpp>
-#include <boost/capy/error.hpp>
+
+// Execution
 #include <boost/capy/ex/any_executor.hpp>
 #include <boost/capy/ex/async_event.hpp>
 #include <boost/capy/ex/coro_lock.hpp>
 #include <boost/capy/ex/execution_context.hpp>
 #include <boost/capy/ex/executor_ref.hpp>
 #include <boost/capy/ex/executor_work_guard.hpp>
 #include <boost/capy/ex/frame_allocator.hpp>
+#include <boost/capy/ex/immediate.hpp>
+#include <boost/capy/ex/io_awaitable_support.hpp>
 #include <boost/capy/ex/recycling_memory_resource.hpp>
-#include <boost/capy/ex/run_async.hpp>
 #include <boost/capy/ex/run.hpp>
+#include <boost/capy/ex/run_async.hpp>
 #include <boost/capy/ex/strand.hpp>
 #include <boost/capy/ex/system_context.hpp>
-#include <boost/capy/ex/thread_pool.hpp>
 #include <boost/capy/ex/this_coro.hpp>
-#include <boost/capy/io_result.hpp>
-#include <boost/capy/read.hpp>
-#include <boost/capy/task.hpp>
-#include <boost/capy/when_all.hpp>
-#include <boost/capy/write.hpp>
+#include <boost/capy/ex/thread_pool.hpp>
+
+// Type-erased I/O
+#include <boost/capy/io/any_buffer_sink.hpp>
+#include <boost/capy/io/any_buffer_source.hpp>
+#include <boost/capy/io/any_read_source.hpp>
+#include <boost/capy/io/any_read_stream.hpp>
+#include <boost/capy/io/any_stream.hpp>
+#include <boost/capy/io/any_write_sink.hpp>
+#include <boost/capy/io/any_write_stream.hpp>
+#include <boost/capy/io/pull_from.hpp>
+#include <boost/capy/io/push_to.hpp>
 
 #endif