Docs: update specification of capy::read

doc/modules/ROOT/nav.adoc

@@ -71,4 +71,7 @@
 ** xref:9.design/9m.WhyNotCobalt.adoc[Why Not Cobalt?]
 ** xref:9.design/9n.WhyNotCobaltConcepts.adoc[Why Not Cobalt Concepts?]
 ** xref:9.design/9o.WhyNotTMC.adoc[Why Not TooManyCooks?]
+* xref:A.specification-methods/A.intro.adoc[Methods of API Description]
+** xref:A.specification-methods/Ab.cancellation.adoc[Cancellation]
+** xref:A.specification-methods/Ac.contingencies.adoc[Contingencies]
 * xref:reference:boost/capy.adoc[Reference]

doc/modules/ROOT/pages/A.specification-methods/A.intro.adoc

@@ -0,0 +1,16 @@
+//
+// Copyright (c) 2026 Andrzej Krzemieński (akrzemi1@gmail.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/capy
+//
+
+= Methods of API Description
+
+
+
+This section describes the conventions used to specify the API of this library in the following 
+xref:reference:boost/capy.adoc[Reference] section.
+

doc/modules/ROOT/pages/A.specification-methods/Ab.cancellation.adoc

@@ -0,0 +1,20 @@
+//
+// Copyright (c) 2026 Andrzej Krzemieński (akrzemi1@gmail.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/capy
+//
+
+= Cancellation
+
+A function is said to _support IoAwaitable cancellation_ when its return type 
+models concept `IoAwaitable` and this return object `a` controls a coroutine which
+can be prematurely stopped using the `std::stop_token` propagated through the 
+`IoAwaitable` protocol. Additionally, if the result type of expression `co_await a`
+in the context of a Capy-coroutine is a specialization of `io_result` 
+then the cancelling of an operation is 
+considered a contingency represented by condition `cond::canceled`.
+
+

doc/modules/ROOT/pages/A.specification-methods/Ac.contingencies.adoc

@@ -0,0 +1,44 @@
+//
+// Copyright (c) 2026 Andrzej Krzemieński (akrzemi1@gmail.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/capy
+//
+
+= Contingencies
+
+A _contingency_ is any situation occurring during an operation
+on a stream, caused by the stream's state, that prevents this operation
+from reading or writing the requested number of bytes.
+
+These situations do not violate the postconditions of the corresponding operations, 
+as their postconditions never say that the requested number of bytes will indeed be
+processed.
+
+Each stream operation that may encounter a contingency await-returns
+a type which is a specialization of `capy::io_result`. These objects can be _destructured_
+using a structured binding. The first binding of such destructuring is of type
+`std::error_code`. This binding, call it `ec`, is used to signal if and which
+contingency occured:
+
+ * If `ec == std::error_code{}`, no contingency occurred.
+ * Otherwise a contingency occurred. In order to determine which contingency occurred,
+   compare `ec` to error conditions, in particular to `capy::cond`.
+
+NOTE: Reaching the end of stream is also a contingency
+      (which can be interpreted as preventing an infinite read
+      from proceeding).
+
+NOTE: The stream operations can still throw exceptions to indicate conditions
+      unrelated to stream state that prevent these operations from satisfying
+      their postconditions, such as failures to grow a buffer, or 
+      failure to allocate a coroutine frame.
+
+NOTE: Operations on streams often await-return `capy::io_result<std::size_t>`
+      destructuring to `[ec, n]`, where `n` represents the number of processed bytes.
+      Upon a reported contingency, a non-zero `n` indicates the state of the partial
+      or sometimes even a full read. When an inner operation reports a contingency,
+      the outer operation usually processes its partial results before reporting
+      the contingency itself.

doc/mrdocs.yml

@@ -26,4 +26,7 @@ multipage: true
 # use-system-libc: true
 # use-system-stdlib: true
 
+# Automation
+auto-function-metadata: false
+
 cmake: '-DCMAKE_CXX_STANDARD=20 -DBOOST_CAPY_MRDOCS_BUILD=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=OFF'