From 6c4e4b374a48a5d3d46a7b7e9fded128232ccfbe Mon Sep 17 00:00:00 2001
From: Ivan Molodetskikh <yalterz@gmail.com>
Date: Wed, 4 Sep 2024 12:21:23 +0300
Subject: [PATCH] ipc: Write some more docs

---
 niri-ipc/src/lib.rs   | 20 ++++++++++++++++++++
 niri-ipc/src/state.rs |  6 ++++++
 2 files changed, 26 insertions(+)

diff --git a/niri-ipc/src/lib.rs b/niri-ipc/src/lib.rs
index 3ef744003..bf394a50b 100644
--- a/niri-ipc/src/lib.rs
+++ b/niri-ipc/src/lib.rs
@@ -1,4 +1,24 @@
 //! Types for communicating with niri via IPC.
+//!
+//! After connecting to the niri socket, you can send a single [`Request`] and receive a single
+//! [`Reply`], which is a `Result` wrapping a [`Response`]. If you requested an event stream, you
+//! can keep reading [`Event`]s from the socket after the response.
+//!
+//! You can use the [`socket::Socket`] helper if you're fine with blocking communication. However,
+//! it is a fairly simple helper, so if you need async, or if you're using a different language,
+//! you are encouraged to communicate with the socket manually.
+//!
+//! 1. Read the socket filesystem path from [`socket::SOCKET_PATH_ENV`] (`$NIRI_SOCKET`).
+//! 2. Connect to the socket and write a JSON-formatted [`Request`] on a single line. You can follow
+//!    up with a line break and a flush, or just flush and shutdown the write end of the socket.
+//! 3. Niri will respond with a single line JSON-formatted [`Reply`].
+//! 4. If you requested an event stream, niri will keep responding with JSON-formatted [`Event`]s,
+//!    on a single line each.
+//!
+//! ## Backwards compatibility
+//!
+//! This crate follows the niri version. It is **not** API-stable in terms of the Rust semver. In
+//! particular, expect new struct fields and enum variants to be added in patch version bumps.
 #![warn(missing_docs)]
 
 use std::collections::HashMap;
diff --git a/niri-ipc/src/state.rs b/niri-ipc/src/state.rs
index 8d2d1744e..2ab58fc3f 100644
--- a/niri-ipc/src/state.rs
+++ b/niri-ipc/src/state.rs
@@ -1,4 +1,10 @@
 //! Helpers for keeping track of the event stream state.
+//!
+//! 1. Create an [`EventStreamState`] using `Default::default()`, or any individual state part if
+//!    you only care about part of the state.
+//! 2. Connect to the niri socket and request an event stream.
+//! 3. Pass every [`Event`] to [`EventStreamStatePart::apply`] on your state.
+//! 4. Read the fields of the state as needed.
 
 use std::collections::hash_map::Entry;
 use std::collections::HashMap;