add examples to rustdocs on functions instead of README and add license and credits to readme

Author: MOmarMiraj

README.md

@@ -1,4 +1,4 @@
-# 1Password IPC Client 
+# 1Password IPC Client
 
 ## Overview
 
@@ -68,62 +68,6 @@ let response2 = send_with_pipe(&mut pipe, request2).unwrap();
 
 Note: Windows and Linux have a limitation in multi-threaded environments with message integrity. Users must ensure they send and receive one at a time.
 
-## Public API
-
-### `send_to`
-
-```rust
-pub fn send_to(endpoint_name: &str, message: Vec<u8>) -> Result<Vec<u8>, ErrorCode>
-```
-
-Sends a message to the IPC server at the given endpoint and returns the response. This is a synchronous, blocking call that creates a fresh connection per invocation.
-
-| Parameter | Type | Description |
-| :-------- | :--- | :---------- |
-| endpoint_name | `&str` | The endpoint to connect to. Interpreted as a Mach port name on macOS, an abstract Unix socket name on Linux, or a named pipe path on Windows. |
-| message | `Vec<u8>` | The raw request bytes to send |
-
-**Returns:** `Ok(Vec<u8>)` containing the response bytes, or `Err(ErrorCode)` on failure.
-
-### `send_with_client` (macOS only)
-
-```rust
-pub fn send_with_client(client: &mut Client, request: Vec<u8>) -> Result<Vec<u8>, ErrorCode>
-```
-
-Sends a message over an existing Mach port client. Allows reusing the same connection across multiple calls.
-
-### `send_with_stream` (Linux only)
-
-```rust
-pub fn send_with_stream(stream: &mut UnixStream, message: Vec<u8>) -> Result<Vec<u8>, ErrorCode>
-```
-
-Sends a message over an existing Unix stream. Allows reusing the same connection across multiple calls.
-
-### `send_with_pipe` (Windows only)
-
-```rust
-pub fn send_with_pipe(pipe: &mut File, message: Vec<u8>) -> Result<Vec<u8>, ErrorCode>
-```
-
-Sends a message over an existing named pipe. Allows reusing the same connection across multiple calls.
-
-## Error Handling
-
-All platforms share a single `ErrorCode` enum, re-exported from the crate root as `onepassword_ipc_client::ErrorCode`.
-
-| Value | Description |
-| :---- | :---------- |
-| `InvalidArguments` | Invalid arguments were provided (e.g. bad endpoint name). |
-| `FailedToConnect` | Failed to connect to the IPC endpoint. |
-| `FailedToSend` | Failed to send the message. |
-| `FailedToReceive` | Failed to receive a response from the server. |
-| `FailedToEncode` | Failed to encode the message into the wire format. |
-| `FailedToDecode` | Failed to decode the response from the wire format. |
-| `ServerClosedConnection` | The server closed the connection unexpectedly. |
-| `Internal` | An internal error occurred. |
-
 ## Wire Protocol
 
 ### Framing (Linux / Windows)
@@ -173,3 +117,19 @@ The maximum chunk size is 500,000 bytes (1-byte header + up to 499,999 bytes of
 
 On macOS, if the server's response spans multiple chunks, the client sends a dummy (empty) chunk after each intermediate response chunk to request the next one. On Linux and Windows, all response chunks are sent by the server without further prompting.
 
+## Credits
+
+Made with ❤️ and ☕ by the [1Password](https://1password.com/) team.
+
+### License
+
+<sup>
+Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
+2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
+</sup>
+
+<sub>
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
+be dual licensed as above, without any additional terms or conditions.
+</sub>

src/lib.rs

@@ -36,6 +36,23 @@ pub enum ErrorCode {
 /// Sends a message to the IPC server at the given endpoint and returns the response.
 ///
 /// This is a synchronous, blocking call that creates a fresh connection per invocation.
+///
+/// The `endpoint_name` is interpreted as a Mach port name on macOS, an abstract Unix socket
+/// name on Linux, or a named pipe path on Windows.
+///
+/// Returns the response bytes on success, or an [`ErrorCode`] on failure.
+///
+/// # Examples
+///
+/// ```no_run
+/// use onepassword_ipc_client::{send_to, ErrorCode};
+///
+/// let request = b"my request payload".to_vec();
+/// match send_to("your_endpoint_name", request) {
+///     Ok(response) => println!("Got {} bytes back", response.len()),
+///     Err(err) => eprintln!("IPC failed: {:?}", err),
+/// }
+/// ```
 #[cfg(any(target_os = "linux", target_os = "windows", target_os = "macos"))]
 pub fn send_to(endpoint_name: &str, message: Vec<u8>) -> Result<Vec<u8>, ErrorCode> {
     platform::send_to(endpoint_name, message)

src/platform/linux.rs

@@ -18,8 +18,23 @@ pub fn send_to(endpoint_name: &str, message: Vec<u8>) -> Result<Vec<u8>, ErrorCo
 /// Sends a message over an existing stream and returns the response.
 ///
 /// This allows reusing the same connection across multiple calls.
+///
 /// NOTE: This requires to send and receive messages one at a time as in multi-threaded
 /// contexts, this will ruin the message integrity as chunks can potentially be out of sync.
+///
+/// # Examples
+///
+/// ```no_run
+/// use std::os::linux::net::SocketAddrExt;
+/// use std::os::unix::net::{SocketAddr, UnixStream};
+/// use onepassword_ipc_client::send_with_stream;
+///
+/// let addr = SocketAddr::from_abstract_name("your_endpoint_name").unwrap();
+/// let mut stream = UnixStream::connect_addr(&addr).unwrap();
+///
+/// let response1 = send_with_stream(&mut stream, b"request one".to_vec()).unwrap();
+/// let response2 = send_with_stream(&mut stream, b"request two".to_vec()).unwrap();
+/// ```
 pub fn send_with_stream(stream: &mut UnixStream, message: Vec<u8>) -> Result<Vec<u8>, ErrorCode> {
     send_and_receive(stream, message)
 }

src/platform/macos.rs

@@ -15,6 +15,20 @@ pub fn send_to(endpoint_name: &str, request: Vec<u8>) -> Result<Vec<u8>, ErrorCo
     send_with_client(&mut client, request)
 }
 
+/// Sends a message over an existing Mach port client and returns the response.
+///
+/// This allows reusing the same connection across multiple calls.
+///
+/// # Examples
+///
+/// ```no_run
+/// use onepassword_ipc_client::send_with_client;
+/// use mach_listener::Client;
+///
+/// let mut client = Client::connect("your_endpoint_name").unwrap();
+/// let response = send_with_client(&mut client, b"hello".to_vec()).unwrap();
+/// println!("Got {} bytes back", response.len());
+/// ```
 pub fn send_with_client(client: &mut Client, request: Vec<u8>) -> Result<Vec<u8>, ErrorCode> {
     let chunks = build_chunks(&request);
     let mut iter = chunks.into_iter().peekable();

src/platform/windows.rs

@@ -18,8 +18,25 @@ pub fn send_to(endpoint_name: &str, message: Vec<u8>) -> Result<Vec<u8>, ErrorCo
 /// Sends a message over an existing named pipe and returns the response.
 ///
 /// This allows reusing the same connection across multiple calls.
+///
 /// NOTE: This requires to send and receive messages one at a time as in multi-threaded
 /// contexts, this will ruin the message integrity as chunks can potentially be out of sync.
+///
+/// # Examples
+///
+/// ```no_run
+/// use std::fs::OpenOptions;
+/// use onepassword_ipc_client::send_with_pipe;
+///
+/// let mut pipe = OpenOptions::new()
+///     .read(true)
+///     .write(true)
+///     .open(r"\\.\pipe\your_endpoint_name")
+///     .unwrap();
+///
+/// let response1 = send_with_pipe(&mut pipe, b"request one".to_vec()).unwrap();
+/// let response2 = send_with_pipe(&mut pipe, b"request two".to_vec()).unwrap();
+/// ```
 pub fn send_with_pipe(pipe: &mut File, message: Vec<u8>) -> Result<Vec<u8>, ErrorCode> {
     send_and_receive(pipe, message)
 }