docs(sacp): un-ignore doc examples and make them compile

Convert 33 doc examples from ```ignore to compilable ``` blocks
using sacp-test support types. Remaining 14 ignore blocks are:
- Deadlock demonstration examples in ordering.rs (intentional)
- Complex schema types in cookbook.rs (RequestPermission, etc.)
- Derive macro examples in jsonrpc.rs (require proc-macro)
- External crate examples (sacp-conductor)

All 71 doc tests now pass.

Author: nikomatsakis

src/sacp/src/concepts/callbacks.rs

@@ -7,17 +7,22 @@
 //!
 //! Use `on_receive_request` to handle incoming requests that expect a response:
 //!
-//! ```ignore
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::{ValidateRequest, ValidateResponse};
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
 //! ClientToAgent::builder()
-//!     .on_receive_request(async |req: PermissionRequest, request_cx, cx| {
-//!         // Decide whether to grant the permission
-//!         let granted = prompt_user(&req).await;
+//!     .on_receive_request(async |req: ValidateRequest, request_cx, cx| {
+//!         // Process the request
+//!         let is_valid = req.data.len() > 0;
 //!
 //!         // Send the response
-//!         request_cx.respond(PermissionResponse { granted })
-//!     }, on_receive_request!())
-//!     .run_until(transport, async |cx| { ... })
+//!         request_cx.respond(ValidateResponse { is_valid, error: None })
+//!     }, sacp::on_receive_request!())
+//!     .run_until(transport, async |cx| { Ok(()) })
 //!     .await?;
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! Your callback receives three arguments:
@@ -30,23 +35,53 @@
 //! Use `on_receive_notification` for fire-and-forget messages that don't need
 //! a response:
 //!
-//! ```ignore
-//! builder.on_receive_notification(async |notif: ProgressNotification, cx| {
-//!     println!("Progress: {}%", notif.percent);
-//!     Ok(())
-//! }, on_receive_notification!());
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::StatusUpdate;
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! ClientToAgent::builder()
+//!     .on_receive_notification(async |notif: StatusUpdate, cx| {
+//!         println!("Status: {}", notif.message);
+//!         Ok(())
+//!     }, sacp::on_receive_notification!())
+//! #   .run_until(transport, async |_| Ok(())).await?;
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! # The Request Context
 //!
 //! The [`JrRequestCx`] lets you send a response to the request:
 //!
-//! ```ignore
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::{MyRequest, MyResponse};
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! # ClientToAgent::builder()
+//! #   .on_receive_request(async |req: MyRequest, request_cx, cx| {
 //! // Send a successful response
-//! request_cx.respond(MyResponse { ... })?;
+//! request_cx.respond(MyResponse { status: "ok".into() })?;
+//! # Ok(())
+//! #   }, sacp::on_receive_request!())
+//! #   .run_until(transport, async |_| Ok(())).await?;
+//! # Ok(())
+//! # }
+//! ```
 //!
-//! // Or send an error
-//! request_cx.respond_with_error(Error::invalid_params("missing field"))?;
+//! Or send an error:
+//!
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::{MyRequest, MyResponse};
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! # ClientToAgent::builder()
+//! #   .on_receive_request(async |req: MyRequest, request_cx, cx| {
+//! request_cx.respond_with_error(sacp::Error::invalid_params())?;
+//! # Ok(())
+//! #   }, sacp::on_receive_request!())
+//! #   .run_until(transport, async |_| Ok(())).await?;
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! You must send exactly one response per request. If your callback returns
@@ -57,17 +92,22 @@
 //! You can register multiple handlers. They're tried in order until one
 //! handles the message:
 //!
-//! ```ignore
-//! builder
-//!     .on_receive_request(async |req: PermissionRequest, request_cx, cx| {
-//!         // Handle permission requests
-//!         request_cx.respond(PermissionResponse { granted: true })
-//!     }, on_receive_request!())
-//!     .on_receive_request(async |req: ToolCallRequest, request_cx, cx| {
-//!         // Handle tool calls
-//!         request_cx.respond(ToolCallResponse { result: "done".into() })
-//!     }, on_receive_request!())
-//!     // ...
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::{ValidateRequest, ValidateResponse, ExecuteRequest, ExecuteResponse};
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! ClientToAgent::builder()
+//!     .on_receive_request(async |req: ValidateRequest, request_cx, cx| {
+//!         // Handle validation requests
+//!         request_cx.respond(ValidateResponse { is_valid: true, error: None })
+//!     }, sacp::on_receive_request!())
+//!     .on_receive_request(async |req: ExecuteRequest, request_cx, cx| {
+//!         // Handle execution requests
+//!         request_cx.respond(ExecuteResponse { result: "done".into() })
+//!     }, sacp::on_receive_request!())
+//! #   .run_until(transport, async |_| Ok(())).await?;
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! # Ordering Guarantees

src/sacp/src/concepts/connections.rs

@@ -20,36 +20,47 @@
 //! Every link type has a `builder()` method that returns a connection builder.
 //! The builder lets you configure handlers, then connect to a transport:
 //!
-//! ```ignore
-//! use sacp::ClientToAgent;
-//!
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
 //! ClientToAgent::builder()
 //!     .name("my-client")
-//!     .connect_to(transport)
-//!     .run_until(async |cx| {
+//!     .run_until(transport, async |cx| {
 //!         // Use `cx` to send requests and handle responses
 //!         Ok(())
 //!     })
 //!     .await?;
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! # The Connection Context
 //!
 //! Inside `run_until`, you receive a [`JrConnectionCx`] (connection context) that
 //! lets you interact with the remote peer:
 //!
-//! ```ignore
-//! .run_until(async |cx| {
-//!     // Send a request and wait for the response
-//!     let response = cx.send_request(InitializeRequest { ... })
-//!         .block_task()
-//!         .await?;
-//!
-//!     // Send a notification (fire-and-forget)
-//!     cx.send_notification(SomeNotification { ... })?;
-//!
-//!     Ok(())
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp::schema::InitializeRequest;
+//! # use sacp_test::StatusUpdate;
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! # ClientToAgent::builder().run_until(transport, async |cx| {
+//! // Send a request and wait for the response
+//! let response = cx.send_request(InitializeRequest {
+//!     protocol_version: Default::default(),
+//!     client_capabilities: Default::default(),
+//!     client_info: None,
+//!     meta: None,
 //! })
+//!     .block_task()
+//!     .await?;
+//!
+//! // Send a notification (fire-and-forget)
+//! cx.send_notification(StatusUpdate { message: "hello".into() })?;
+//! # Ok(())
+//! # }).await?;
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! # Sending Requests
@@ -61,19 +72,31 @@
 //!
 //! Use `block_task()` when you need the response before continuing:
 //!
-//! ```ignore
-//! let response = cx.send_request(MyRequest { ... })
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::MyRequest;
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! # ClientToAgent::builder().run_until(transport, async |cx| {
+//! let response = cx.send_request(MyRequest {})
 //!     .block_task()
 //!     .await?;
 //! // Use response here
+//! # Ok(())
+//! # }).await?;
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! ## Option 2: Schedule a callback
 //!
 //! Use `on_receiving_result()` when you want to handle the response asynchronously:
 //!
-//! ```ignore
-//! cx.send_request(MyRequest { ... })
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::MyRequest;
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! # ClientToAgent::builder().run_until(transport, async |cx| {
+//! cx.send_request(MyRequest {})
 //!     .on_receiving_result(async |result| {
 //!         match result {
 //!             Ok(response) => { /* handle success */ }
@@ -82,6 +105,10 @@
 //!         Ok(())
 //!     })?;
 //! // Continues immediately, callback runs when response arrives
+//! # Ok(())
+//! # }).await?;
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! See [Ordering](super::ordering) for important details about how these differ.

src/sacp/src/concepts/error_handling.rs

@@ -21,26 +21,40 @@
 //! To send an error response to a request (without closing the connection),
 //! use the request context's `respond` method:
 //!
-//! ```ignore
-//! connection.on_receive_request(async |request, request_cx, _cx| {
-//!     if !is_valid(&request) {
-//!         // Send error to peer, keep connection alive
-//!         request_cx.respond(Err(sacp::Error::invalid_params()))?;
-//!         return Ok(());
-//!     }
-//!
-//!     // Process valid request...
-//!     request_cx.respond(Ok(response))?;
-//!     Ok(())
-//! });
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # use sacp_test::{ValidateRequest, ValidateResponse};
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! ClientToAgent::builder()
+//!     .on_receive_request(async |request: ValidateRequest, request_cx, _cx| {
+//!         if request.data.is_empty() {
+//!             // Send error to peer, keep connection alive
+//!             request_cx.respond_with_error(sacp::Error::invalid_params())?;
+//!             return Ok(());
+//!         }
+//!
+//!         // Process valid request...
+//!         request_cx.respond(ValidateResponse { is_valid: true, error: None })?;
+//!         Ok(())
+//!     }, sacp::on_receive_request!())
+//! #   .run_until(transport, async |_| Ok(())).await?;
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! For sending error notifications (one-way error messages), use
 //! [`send_error_notification`][crate::JrConnectionCx::send_error_notification]:
 //!
-//! ```ignore
+//! ```
+//! # use sacp::{ClientToAgent, AgentToClient, Component};
+//! # async fn example(transport: impl Component<AgentToClient>) -> Result<(), sacp::Error> {
+//! # ClientToAgent::builder().run_until(transport, async |cx| {
 //! cx.send_error_notification(sacp::Error::internal_error()
 //!     .with_data("Something went wrong"))?;
+//! # Ok(())
+//! # }).await?;
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! # The `into_internal_error` Helper
@@ -50,16 +64,21 @@
 //! [`Error::into_internal_error`][crate::Error::into_internal_error] method
 //! provides a convenient way to do this:
 //!
-//! ```ignore
+//! ```
 //! use sacp::Error;
 //!
+//! # fn example() -> Result<(), sacp::Error> {
+//! # let data = "hello";
+//! # let path = "/tmp/test.txt";
 //! // Convert any error type to sacp::Error
 //! let value = serde_json::to_value(&data)
 //!     .map_err(Error::into_internal_error)?;
 //!
 //! // Or with a file operation
 //! let contents = std::fs::read_to_string(path)
-//!     .map_err(Error::into_internal_error)?;
+//!     .map_err(Error::into_internal_error);
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! This wraps the original error's message in an internal error, which is
@@ -79,12 +98,12 @@
 //!
 //! You can add context with `.with_data()`:
 //!
-//! ```ignore
-//! sacp::Error::invalid_params()
+//! ```
+//! let error = sacp::Error::invalid_params()
 //!     .with_data(serde_json::json!({
 //!         "field": "timeout",
 //!         "reason": "must be positive"
-//!     }))
+//!     }));
 //! ```
 //!
 //! # Summary