From d97f9c7014bcc14d3b094d964ba2e9452b4314f3 Mon Sep 17 00:00:00 2001
From: Steve Gerbino <steve@gerbino.co>
Date: Fri, 2 Oct 2026 20:48:22 +0200
Subject: [PATCH] docs: add the reference example for io_context::service

Recent MrDocs develop-release builds list inherited members, so
io_context now carries capy's execution_context::service docstring,
whose example marker expects a snippet file in this repository. Without
it the reference-snippets extension fails the whole docs build.
---
 .../reference/io_context__service.record.cpp  | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 test/doc/reference/io_context__service.record.cpp

diff --git a/test/doc/reference/io_context__service.record.cpp b/test/doc/reference/io_context__service.record.cpp
new file mode 100644
index 000000000..74f6fcd9c
--- /dev/null
+++ b/test/doc/reference/io_context__service.record.cpp
@@ -0,0 +1,53 @@
+//
+// Copyright (c) 2026 Steve Gerbino
+//
+// 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/corosio
+//
+
+// Reference example injected into the documentation for
+// io_context::service by doc/addons/extensions/reference-snippets.lua.
+// The symbol is inherited from capy::execution_context (declared in
+// boost/capy/ex/execution_context.hpp); MrDocs lists it under io_context,
+// so the inherited docstring's example marker resolves against this file.
+// The tagged region is what the reference renders; scaffolding stays
+// outside the tags.
+
+#include "../doc_warnings.hpp"
+
+#include <boost/corosio/io_context.hpp>
+
+#include <tuple>
+
+namespace corosio = boost::corosio;
+namespace capy    = boost::capy;
+
+namespace {
+
+namespace ex_1 {
+// tag::example[]
+struct my_service : capy::execution_context::service
+{
+    explicit my_service(capy::execution_context&) {}
+
+protected:
+    void shutdown() override
+    {
+        // Cancel pending operations, release resources
+    }
+};
+
+void register_service()
+{
+    corosio::io_context ioc;
+
+    // Created on first use, owned by the context for its lifetime
+    auto& svc = ioc.use_service<my_service>();
+    std::ignore = svc;
+}
+// end::example[]
+} // namespace ex_1
+
+} // namespace