@@ -172,9 +172,12 @@ struct TFutureBase {
 template<> struct TFuture<void>;
 
 /**
- * @brief Future type for coroutines returning a value of type T.
+ * @brief Owned coroutine handle that carries a result of type T.
  *
- * Provides mechanisms to await and retrieve the result of a coroutine.
+ * RAII: destroys the coroutine frame in `~TFuture`. Move-only.
+ * `co_await future` suspends the caller until the coroutine finishes, then
+ * returns `T` or rethrows a stored exception. `future.done()` polls
+ * completion without suspending.
  *
  * @tparam T The type of the result.
  */
@@ -236,7 +239,11 @@ struct TPromise<void>: public TPromiseBase<void> {
 };
 
 /**
- * @brief Future specialization for coroutines that return void.
+ * @brief Owned coroutine handle for coroutines that return void.
+ *
+ * Same ownership and exception-propagation semantics as `TFuture<T>`.
+ * `co_await future` suspends the caller until done, then rethrows any
+ * stored exception. Provides `Accept(func)` to chain a continuation.
  */
 template<>
 struct TFuture<void> : public TFutureBase<void> {
@@ -297,11 +304,14 @@ template<typename T>
 TFinalAwaiter<T> TPromiseBase<T>::final_suspend() noexcept { return {}; }
 
 /**
- * @brief Awaits the completion of all futures and collects their results.
+ * @brief Awaits every future in order and collects their results.
+ *
+ * Futures are `co_await`-ed sequentially (not concurrently). The caller
+ * suspends until each future finishes before moving to the next.
  *
  * @tparam T The type of each coroutine's result.
- * @param futures A vector of TFuture<T> objects.
- * @return TFuture<std::vector<T>> containing the results from all coroutines.
+ * @param futures A vector of TFuture<T> objects (moved in).
+ * @return TFuture<std::vector<T>> containing results in input order.
  */
 template<typename T>
 TFuture<std::vector<T>> All(std::vector<TFuture<T>>&& futures) {
@@ -314,10 +324,10 @@ TFuture<std::vector<T>> All(std::vector<TFuture<T>>&& futures) {
 }
 
 /**
- * @brief Awaits the completion of all void-returning coroutines.
+ * @brief Awaits every void future in order until all have completed.
  *
- * @param futures A vector of TFuture<void> objects.
- * @return TFuture<void> representing the completion of all coroutines.
+ * @param futures A vector of TFuture<void> objects (moved in).
+ * @return TFuture<void> that completes after all futures finish.
  */
 inline TFuture<void> All(std::vector<TFuture<void>>&& futures) {
     auto waiting = std::move(futures);
@@ -328,14 +338,16 @@ inline TFuture<void> All(std::vector<TFuture<void>>&& futures) {
 }
 
 /**
- * @brief Awaits the completion of any one of the given futures and returns its result.
+ * @brief Returns the result of whichever future completes first.
  *
- * If one of the futures has already finished, its result is returned immediately.
- * Otherwise, the current coroutine is suspended until one of the futures completes.
+ * If one future is already done, its result is returned without suspension.
+ * Otherwise, all futures register this coroutine as their continuation; when
+ * the first one resumes it, the remaining futures are abandoned (their frames
+ * are destroyed when the vector goes out of scope).
  *
- * @tparam T The type of the coroutine's result.
- * @param futures A vector of TFuture<T> objects.
- * @return TFuture<T> with the result from the first completed coroutine.
+ * @tparam T The type of each coroutine's result.
+ * @param futures A vector of TFuture<T> objects (moved in).
+ * @return TFuture<T> with the result from the first completed future.
  */
 template<typename T>
 TFuture<T> Any(std::vector<TFuture<T>>&& futures) {
@@ -355,10 +367,10 @@ TFuture<T> Any(std::vector<TFuture<T>>&& futures) {
 }
 
 /**
- * @brief Awaits the completion of any one of the void-returning coroutines.
+ * @brief Completes when the first void future finishes; others are abandoned.
  *
- * @param futures A vector of TFuture<void> objects.
- * @return TFuture<void> representing the completion of one of the coroutines.
+ * @param futures A vector of TFuture<void> objects (moved in).
+ * @return TFuture<void> that completes as soon as one future finishes.
  */
 inline TFuture<void> Any(std::vector<TFuture<void>>&& futures) {
     std::vector<TFuture<void>> all = std::move(futures);
 
@@ -1,34 +1,30 @@
 namespace NNet {
 
 /**
- * @class TLoop
- * @brief A generic event loop wrapper that uses TSelect as its poller.
+ * @brief Event loop that drives a poller backend.
  *
- * The event loop continuously calls @ref Step() until explicitly stopped via
- * @ref Stop().
+ * Each call to `Step()` runs one polling round: it calls `Poller_.Poll()` to
+ * collect ready I/O events and timers, then `Poller_.WakeupReadyHandles()` to
+ * resume the waiting coroutines.
  *
- * ### Example Usage
- * @code{.cpp}
- * #include <iostream>
+ * `Loop()` repeats `Step()` until `Stop()` is called. For manual control (e.g.
+ * driving the loop until a specific `TFuture` completes), use `Step()` directly:
  *
- * int main() {
- *     // Instantiate the event loop with TSelect
- *     TLoop<TSelect> loop;
- *
- *     // Run a single iteration of polling and wakeup
+ * @code
+ * TLoop<TDefaultPoller> loop;
+ * TFuture<void> task = my_coroutine(loop.Poller());
+ * while (!task.done())
  *     loop.Step();
+ * @endcode
  *
- *     // Stop the loop
- *     loop.Stop();
- *
- *     // Alternatively, to run continuously:
- *     // loop.Loop(); // Will keep calling Step() until Stop() is called
- *
- *     return 0;
- * }
+ * For server-style programs with detached `TVoidTask` coroutines:
+ * @code
+ * TLoop<TDefaultPoller> loop;
+ * server(loop.Poller(), TAddress{"::", 8888});  // returns TVoidTask
+ * loop.Loop();                                   // runs until Stop() is called
  * @endcode
  *
- * @tparam TPoller A type that provides polling and wakeup mechanisms (TSelect here).
+ * @tparam TPoller Polling backend: TEPoll, TKqueue, TIOCp, TUring, TPoll, TSelect, etc.
  */
 template<typename TPoller>
 class TLoop {
@@ -48,7 +44,8 @@ class TLoop {
         Running_ = false;
     }
     /**
-     * @brief Performs a single iteration of polling and waking up ready handles.
+     * @brief Runs one event-loop iteration: polls for I/O/timer events then
+     *        resumes all coroutines whose events fired.
      */
     void Step() {
         Poller_.Poll();
 
@@ -24,30 +24,16 @@
 namespace NNet {
 
 /**
- * @class TPollerBase
- * @brief Base class for pollers managing asynchronous I/O events and timers.
+ * @brief Backend-independent base for I/O pollers.
  *
- * TPollerBase provides the common interface and functionality for pollers that drive asynchronous
- * operations. It allows scheduling timers, registering I/O events (read, write, remote hang-up) on file
- * descriptors, and waking up waiting coroutines. It also offers convenience methods such as @ref Sleep()
- * (and its overload accepting a std::chrono::duration) and @ref Yield().
+ * Manages three concerns shared by all poller backends:
+ * - **Timers** — `AddTimer` / `RemoveTimer` / `ProcessTimers`
+ * - **I/O event registration** — `AddRead`, `AddWrite`, `AddRemoteHup`, `RemoveEvent`
+ * - **Coroutine scheduling** — `Sleep`, `Yield`, `Wakeup`, `WakeupReadyHandles`
  *
- * The class maintains internal collections for pending changes (events), ready events, and timers.
- * It also keeps track of the maximum file descriptor, which is used in system-level polling calls.
- *
- * Key methods include:
- *  - @ref AddTimer() to schedule a timer.
- *  - @ref RemoveTimer() to cancel a timer.
- *  - @ref AddRead(), @ref AddWrite(), @ref AddRemoteHup() to register I/O events.
- *  - @ref RemoveEvent() to deregister events.
- *  - @ref Sleep() and @ref Yield() to suspend execution until a specified time or until the next
- *    polling round.
- *  - @ref Wakeup() and @ref WakeupReadyHandles() to resume waiting coroutines when events occur.
- *
- * The class also provides helper methods for computing timeout values (via @ref GetTimeout()).
- *
- * The detailed comment inside @ref Wakeup() describes how a waiting coroutine is resumed and how new
- * event registrations are matched.
+ * Concrete backends (TEPoll, TKqueue, …) inherit from this class and implement
+ * `Poll()` to fill `ReadyEvents_` using the OS-specific mechanism, then call
+ * `WakeupReadyHandles()` (provided here) to resume waiting coroutines.
  */
 class TPollerBase {
 public:
@@ -91,20 +77,26 @@ class TPollerBase {
     }
 
     /**
-     * @brief Registers a read event on a file descriptor.
+     * @brief Registers a read interest on a file descriptor.
      *
-     * @param fd The file descriptor.
-     * @param h  The coroutine handle to resume when data is available.
+     * `h` will be resumed by `WakeupReadyHandles()` on the next loop iteration
+     * after the fd becomes readable.
+     *
+     * @param fd File descriptor to watch.
+     * @param h  Coroutine to resume when data is available.
      */
     void AddRead(int fd, THandle h) {
         MaxFd_ = std::max(MaxFd_, fd);
         Changes_.emplace_back(TEvent{fd, TEvent::READ, h});
     }
     /**
-     * @brief Registers a write event on a file descriptor.
+     * @brief Registers a write interest on a file descriptor.
      *
-     * @param fd The file descriptor.
-     * @param h  The coroutine handle to resume when ready for writing.
+     * `h` will be resumed by `WakeupReadyHandles()` on the next loop iteration
+     * after the fd becomes writable.
+     *
+     * @param fd File descriptor to watch.
+     * @param h  Coroutine to resume when ready for writing.
      */
     void AddWrite(int fd, THandle h) {
         MaxFd_ = std::max(MaxFd_, fd);
@@ -133,12 +125,12 @@ class TPollerBase {
         Changes_.emplace_back(TEvent{fd, TEvent::READ|TEvent::WRITE|TEvent::RHUP, {}});
     }
     /**
-     * @brief Removes events associated with a given coroutine handle.
+     * @brief No-op placeholder for future cleanup by handle.
      *
-     * This overload will be called by destructors of unfinished futures.
-     * Unimplemented.
+     * Intended to be called by destructors of unfinished futures so that
+     * pending waits can be unregistered. Currently unimplemented.
      *
-     * @param h The coroutine handle.
+     * @param h The coroutine handle (unused).
      */
     void RemoveEvent(THandle /*h*/) {
         // TODO: Add new vector for this type of removing
@@ -204,11 +196,13 @@ class TPollerBase {
         return Sleep(TClock::now() + duration);
     }
     /**
-     * @brief Yields execution to the next event loop iteration.
+     * @brief Suspends the coroutine until the next event-loop iteration.
      *
-     * Equivalent to calling Sleep() with a default zero time.
+     * Equivalent to `Sleep(TTime{})`, which fires immediately on the next
+     * `ProcessTimers()` call. Use when you want to give other coroutines a
+     * chance to run before continuing.
      *
-     * @return An awaitable object for yielding execution.
+     * @return An awaitable that resumes on the next loop tick.
      */
     auto Yield() {
         return Sleep(TTime{});
 
@@ -5,6 +5,23 @@ namespace NNet {
 
 struct TVoidPromise;
 
+/**
+ * @brief Fire-and-forget coroutine handle.
+ *
+ * Cannot be `co_await`-ed. Self-destructs on completion (`final_suspend →
+ * suspend_never`). Unhandled exceptions are silently swallowed.
+ *
+ * Use for detached tasks that outlive their caller — e.g. per-connection
+ * handlers spawned inside an accept loop.
+ *
+ * @code
+ * TVoidTask handle_client(TSocket sock) {
+ *     char buf[4096]; ssize_t n;
+ *     while ((n = co_await sock.ReadSome(buf, sizeof(buf))) > 0)
+ *         co_await sock.WriteSome(buf, n);
+ * }
+ * @endcode
+ */
 struct TVoidTask : std::coroutine_handle<TVoidPromise>
 {
     using promise_type = TVoidPromise;
@@ -21,6 +38,12 @@ struct TVoidPromise
 
 struct TVoidSuspendedPromise;
 
+/**
+ * @brief Like TVoidTask but suspends at final_suspend instead of self-destructing.
+ *
+ * Used internally where the caller needs to manually destroy the coroutine
+ * after it completes. Not for general use — prefer TVoidTask or TFuture<void>.
+ */
 struct TVoidSuspendedTask : std::coroutine_handle<TVoidSuspendedPromise>
 {
     using promise_type = TVoidSuspendedPromise;
@@ -36,25 +59,11 @@ struct TVoidSuspendedPromise
 };
 
 /**
- * @class Self
- * @brief A minimal example of a coroutine "awaitable" object.
- *
- * This structure stores a coroutine handle and demonstrates how a coroutine
- * can be suspended and resumed.
- *
- * ### Example Usage
- * @code{.cpp}
- * // A simple coroutine that uses 'Self' as an awaitable:
- * std::coroutine_handle<> exampleCoroutine() {
- *     // co_await our custom awaitable
- *     auto handle = co_await Self{};
- *     // 'handle' is a std::coroutine_handle to this coroutine.
- *     // You can perform actions like handle.destroy(), handle.resume(), etc.
- *     ...
- * }
- * @endcode
+ * @brief Awaitable that resumes immediately and yields this coroutine's own handle.
  *
- * @note Internally, it captures the coroutine handle in its await_suspend step.
+ * `co_await Self{}` never actually suspends (`await_suspend` returns `false`),
+ * but it captures the current coroutine handle via `await_suspend`. Used by
+ * `Any()` to register the same coroutine as the continuation of multiple futures.
  *
  * @cond INTERNAL
  */