net: document crate.

embassy-net/src/udp.rs

@@ -1,3 +1,5 @@
+//! UDP sockets.
+
 use core::cell::RefCell;
 use core::future::poll_fn;
 use core::mem;
@@ -11,6 +13,7 @@ use smoltcp::wire::{IpEndpoint, IpListenEndpoint};
 
 use crate::{SocketStack, Stack};
 
+/// Error returned by [`UdpSocket::bind`].
 #[derive(PartialEq, Eq, Clone, Copy, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum BindError {
@@ -20,6 +23,7 @@ pub enum BindError {
     NoRoute,
 }
 
+/// Error returned by [`UdpSocket::recv_from`] and [`UdpSocket::send_to`].
 #[derive(PartialEq, Eq, Clone, Copy, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
@@ -27,12 +31,14 @@ pub enum Error {
     NoRoute,
 }
 
+/// An UDP socket.
 pub struct UdpSocket<'a> {
     stack: &'a RefCell<SocketStack>,
     handle: SocketHandle,
 }
 
 impl<'a> UdpSocket<'a> {
+    /// Create a new UDP socket using the provided stack and buffers.
     pub fn new<D: Driver>(
         stack: &'a Stack<D>,
         rx_meta: &'a mut [PacketMetadata],
@@ -57,6 +63,7 @@ impl<'a> UdpSocket<'a> {
         }
     }
 
+    /// Bind the socket to a local endpoint.
     pub fn bind<T>(&mut self, endpoint: T) -> Result<(), BindError>
     where
         T: Into<IpListenEndpoint>,
@@ -89,6 +96,11 @@ impl<'a> UdpSocket<'a> {
         res
     }
 
+    /// Receive a datagram.
+    ///
+    /// This method will wait until a datagram is received.
+    ///
+    /// Returns the number of bytes received and the remote endpoint.
     pub async fn recv_from(&self, buf: &mut [u8]) -> Result<(usize, IpEndpoint), Error> {
         poll_fn(move |cx| {
             self.with_mut(|s, _| match s.recv_slice(buf) {
@@ -103,6 +115,7 @@ impl<'a> UdpSocket<'a> {
         .await
     }
 
+    /// Send a datagram to the specified remote endpoint.
     pub async fn send_to<T>(&self, buf: &[u8], remote_endpoint: T) -> Result<(), Error>
     where
         T: Into<IpEndpoint>,
@@ -122,22 +135,28 @@ impl<'a> UdpSocket<'a> {
         .await
     }
 
+    /// Returns the local endpoint of the socket.
     pub fn endpoint(&self) -> IpListenEndpoint {
         self.with(|s, _| s.endpoint())
     }
 
+    /// Returns whether the socket is open.
+
     pub fn is_open(&self) -> bool {
         self.with(|s, _| s.is_open())
     }
 
+    /// Close the socket.
     pub fn close(&mut self) {
         self.with_mut(|s, _| s.close())
     }
 
+    /// Returns whether the socket is ready to send data, i.e. it has enough buffer space to hold a packet.
     pub fn may_send(&self) -> bool {
         self.with(|s, _| s.can_send())
     }
 
+    /// Returns whether the socket is ready to receive data, i.e. it has received a packet that's now in the buffer.
     pub fn may_recv(&self) -> bool {
         self.with(|s, _| s.can_recv())
     }