Add Rustdoc.

src/device/socket/mod.rs

@@ -1,4 +1,11 @@
-//! This module implements the virtio vsock device.
+//! Driver for VirtIO socket devices.
+//!
+//! To use the driver, you should first create a [`VirtIOSocket`] instance with your VirtIO
+//! transport, and then create a [`VsockConnectionManager`] wrapping it to keep track of
+//! connections. If you only want to have a single outgoing vsock connection at once, you can use
+//! [`SingleConnectionManager`] for a slightly simpler interface.
+//!
+//! See [`VsockConnectionManager`] for a usage example.
 
 mod error;
 #[cfg(feature = "alloc")]

src/device/socket/multiconnectionmanager.rs

@@ -12,9 +12,34 @@ use zerocopy::FromBytes;
 
 const PER_CONNECTION_BUFFER_CAPACITY: usize = 1024;
 
-/// A higher level interface for vsock devices.
+/// A higher level interface for VirtIO socket (vsock) devices.
 ///
-/// This keeps track of a single vsock connection.
+/// This keeps track of multiple vsock connections.
+///
+/// # Example
+///
+/// ```
+/// # use virtio_drivers::{Error, Hal};
+/// # use virtio_drivers::transport::Transport;
+/// use virtio_drivers::device::socket::{VirtIOSocket, VsockAddr, VsockConnectionManager};
+///
+/// # fn example<HalImpl: Hal, T: Transport>(transport: T) -> Result<(), Error> {
+/// let mut socket = VsockConnectionManager::new(VirtIOSocket::<HalImpl, _>::new(transport)?);
+///
+/// // Start a thread to call `socket.poll()` and handle events.
+///
+/// let remote_address = VsockAddr { cid: 2, port: 42 };
+/// let local_port = 1234;
+/// socket.connect(remote_address, local_port)?;
+///
+/// // Wait until `socket.poll()` returns an event indicating that the socket is connected.
+///
+/// socket.send(remote_address, local_port, "Hello world".as_bytes())?;
+///
+/// socket.shutdown(remote_address, local_port)?;
+/// # Ok(())
+/// # }
+/// ```
 pub struct VsockConnectionManager<H: Hal, T: Transport> {
     driver: VirtIOSocket<H, T>,
     connections: Vec<Connection>,

src/device/socket/singleconnectionmanager.rs

@@ -6,9 +6,10 @@ use crate::{transport::Transport, Hal, Result};
 use core::hint::spin_loop;
 use log::debug;
 
-/// A higher level interface for vsock devices.
+/// A higher level interface for VirtIO socket (vsock) devices.
 ///
-/// This keeps track of a single vsock connection.
+/// This can only keep track of a single vsock connection. If you want to support multiple
+/// simultaneous connections, try [`VsockConnectionManager`](super::VsockConnectionManager).
 pub struct SingleConnectionManager<H: Hal, T: Transport> {
     driver: VirtIOSocket<H, T>,
     connection_info: Option<ConnectionInfo>,

src/device/socket/vsock.rs

@@ -75,6 +75,8 @@ impl ConnectionInfo {
         self.fwd_cnt += length as u32;
     }
 
+    /// Returns the number of bytes of RX buffer space the peer has available to receive packet body
+    /// data from us.
     fn peer_free(&self) -> u32 {
         self.peer_buf_alloc - (self.tx_cnt - self.peer_fwd_cnt)
     }
@@ -203,7 +205,10 @@ pub enum VsockEventType {
     CreditUpdate,
 }
 
-/// Driver for a VirtIO socket device.
+/// Low-level driver for a VirtIO socket device.
+///
+/// You probably want to use [`VsockConnectionManager`](super::VsockConnectionManager) rather than
+/// using this directly.
 pub struct VirtIOSocket<H: Hal, T: Transport> {
     transport: T,
     /// Virtqueue to receive packets.