From 240d022ac9a176f1a58853618bdc2fee08d0c002 Mon Sep 17 00:00:00 2001 From: Lorenzo Felletti <60483783+lorenzofelletti@users.noreply.github.com> Date: Mon, 27 May 2024 20:46:36 +0100 Subject: [PATCH] docs: improve documentation (#2) * docs: improve documentation * revert `cfg_attr` * docs: improvements to documentation * docs: minor improvements --- src/constants.rs | 2 ++ src/dns.rs | 2 +- src/netc.rs | 4 +++- src/socket/tcp.rs | 16 +++++++++------- src/socket/tls.rs | 8 +++++++- src/socket/udp.rs | 17 +++++++++-------- src/traits/dns.rs | 10 +++++++++- src/traits/mod.rs | 4 +++- 8 files changed, 43 insertions(+), 20 deletions(-) diff --git a/src/constants.rs b/src/constants.rs index b12b30a..0651c9c 100644 --- a/src/constants.rs +++ b/src/constants.rs @@ -1,4 +1,6 @@ +/// HTTP port #[allow(unused)] pub const HTTP_PORT: u16 = 80; +/// HTTPS port #[allow(unused)] pub const HTTPS_PORT: u16 = 443; diff --git a/src/dns.rs b/src/dns.rs index f3f664f..1373741 100644 --- a/src/dns.rs +++ b/src/dns.rs @@ -68,7 +68,7 @@ impl DnsResolver { let dns = *GOOGLE_DNS_HOST; let mut udp_socket = UdpSocket::new().map_err(|_| DnsError::FailedToCreate)?; udp_socket - .bind(None) + .bind(Some(dns)) .map_err(|_| DnsError::FailedToCreate)?; Ok(DnsResolver { udp_socket, dns }) diff --git a/src/netc.rs b/src/netc.rs index 9d56f64..8cf5310 100644 --- a/src/netc.rs +++ b/src/netc.rs @@ -1,7 +1,9 @@ #[allow(unused)] pub const AF_INET: u8 = 2; +/// Stream socket (TCP) #[allow(unused)] pub const SOCK_STREAM: i32 = 1; +/// Datagram socket (UDP) #[allow(unused)] pub const SOCK_DGRAM: i32 = 2; @@ -26,7 +28,7 @@ impl Clone for sockaddr_in { sin_len: self.sin_len, sin_family: self.sin_family, sin_port: self.sin_port, - sin_addr: psp::sys::in_addr(self.sin_addr.0), + sin_addr: in_addr(self.sin_addr.0), sin_zero: self.sin_zero, } } diff --git a/src/socket/tcp.rs b/src/socket/tcp.rs index 2cc77a7..2577c08 100644 --- a/src/socket/tcp.rs +++ b/src/socket/tcp.rs @@ -18,15 +18,11 @@ use super::ToSockaddr; /// A TCP socket /// -/// # Fields -/// - [`fd`](Self::fd): The socket file descriptor -/// - [`is_connected`](Self::is_connected): Whether the socket is connected -/// - [`buffer`](Self::buffer): The buffer to store data to send -/// /// # Safety /// This is a wrapper around a raw socket file descriptor. /// /// The socket is closed when the struct is dropped. +/// Closing via drop is best-effort. /// /// # Notes /// The structure implements [`EasySocket`]. This allows you to interact with @@ -46,14 +42,17 @@ use super::ToSockaddr; /// ``` #[repr(C)] pub struct TcpSocket { + /// The socket file descriptor fd: i32, + /// Whether the socket is connected is_connected: bool, + /// The buffer to store data to send buffer: Box, } impl TcpSocket { - #[allow(dead_code)] /// Create a TCP socket + #[allow(dead_code)] pub fn new() -> Result { let fd = unsafe { sys::sceNetInetSocket(netc::AF_INET as i32, netc::SOCK_STREAM, 0) }; if fd < 0 { @@ -74,9 +73,10 @@ impl TcpSocket { /// /// # Returns /// - `Ok(())` if the connection was successful + /// - `Err(String)` if the connection was unsuccessful. #[allow(dead_code)] #[allow(clippy::cast_possible_truncation)] - /// - `Err(String)` if the connection was unsuccessful. + #[allow(dead_code)] pub fn connect(&mut self, remote: SocketAddr) -> Result<(), SocketError> { if self.is_connected { return Err(SocketError::AlreadyConnected); @@ -104,6 +104,7 @@ impl TcpSocket { } } + /// Return the underlying socket's file descriptor #[allow(unused)] pub fn get_socket(&self) -> i32 { self.fd @@ -206,6 +207,7 @@ impl Write for TcpSocket { self._write(buf) } + /// Flush the socket fn flush(&mut self) -> Result<(), SocketError> { self._flush() } diff --git a/src/socket/tls.rs b/src/socket/tls.rs index bfd8292..cea71b5 100644 --- a/src/socket/tls.rs +++ b/src/socket/tls.rs @@ -38,7 +38,9 @@ impl<'a> TlsSocket<'a> { /// - `cert`: An optional certificate to use for the connection /// /// # Returns - /// A new TLS socket. The returned connection is not yet ready. + /// A new TLS socket. + /// + /// The returned connection is not ready yet. /// You must call [`Self::open()`] before you can start sending/receiving data. /// /// # Example @@ -46,6 +48,10 @@ impl<'a> TlsSocket<'a> { /// let mut read_buf = TlsSocket::new_buffer(); /// let mut write_buf = TlsSocket::new_buffer(); /// let tls_socket = TlsSocket::new(tcp_socket, &mut read_buf, &mut write_buf, "example.com", None); + /// ``` + /// + /// # Notes + /// In most cases you can pass `None` for the `cert` parameter. pub fn new( socket: TcpSocket, record_read_buf: &'a mut [u8], diff --git a/src/socket/udp.rs b/src/socket/udp.rs index 97ad193..b5e5d1a 100644 --- a/src/socket/udp.rs +++ b/src/socket/udp.rs @@ -28,12 +28,6 @@ pub enum UdpSocketState { /// A UDP socket /// -/// # Fields -/// - [`fd`](Self::fd): The socket file descriptor -/// - [`remote`](Self::remote): The remote host to connect to -/// - [`state`](Self::state): The state of the socket -/// - [`buffer`](Self::buffer): The buffer to store data to send -/// /// # Notes /// - Remote host ([`Self::remote`]) is set when the socket is bound calling [`bind()`](UdpSocket::bind) /// - In addition to supporting the creation (with [`new`](Self::new)) and manual management of the socket, @@ -41,11 +35,16 @@ pub enum UdpSocketState { /// providing the [`open`](Self::open) method as an alternative to [`new`](Self::new). /// This method return a [`UdpSocket`] already connected, and ready to send/receive data (using the /// [`write`](embedded_io::Write::write) and [`read`](embedded_io::Read::read) methods). +/// - The socket is closed when the struct is dropped. Closing via drop is best-effort. #[repr(C)] pub struct UdpSocket { + /// The socket file descriptor fd: i32, + /// The remote host to connect to remote: Option, + /// The state of the socket state: UdpSocketState, + /// The buffer to store data to send buffer: Box, } @@ -69,7 +68,7 @@ impl UdpSocket { /// Bind the socket /// /// # Parameters - /// - `addr`: The address to bind to, if `None` bind to `0.0.0.0:0` + /// - `addr`: The address to bind to, if `None` binds to `0.0.0.0:0` /// /// # Returns /// - `Ok(())` if the binding was successful @@ -110,6 +109,7 @@ impl UdpSocket { /// /// # Notes /// The socket must be in state [`UdpSocketState::Bound`] to connect to a remote host. + /// To bind the socket use [`bind()`](UdpSocket::bind). #[allow(unused)] pub fn connect(&mut self, addr: SocketAddr) -> Result<(), SocketError> { match self.state { @@ -213,8 +213,8 @@ impl UdpSocket { } } - #[allow(unused)] /// Write to a socket in state [`UdpSocketState::Connected`] + #[allow(unused)] fn _write(&mut self, buf: &[u8]) -> Result { if self.state != UdpSocketState::Connected { return Err(SocketError::NotConnected); @@ -322,6 +322,7 @@ impl Write for UdpSocket { } } + /// Flush the socket fn flush(&mut self) -> Result<(), Self::Error> { match self.get_state() { UdpSocketState::Unbound => Err(SocketError::NotBound), diff --git a/src/traits/dns.rs b/src/traits/dns.rs index c8a1ed7..7f5892e 100644 --- a/src/traits/dns.rs +++ b/src/traits/dns.rs @@ -5,15 +5,23 @@ use alloc::string::String; use embedded_nal::SocketAddr; use psp::sys::in_addr; -// trait defining a type that can resolve a hostname to an IP address +/// Trait for resolving hostnames +/// +/// A type implementing this trait can resolve a hostname to an IP address. pub trait ResolveHostname { type Error: Debug; fn resolve_hostname(&mut self, hostname: &str) -> Result; } +/// Trait for resolving IP addresses +/// +/// A type implementing this trait can resolve an IP address to a hostname. pub trait ResolveAddr { type Error: Debug; fn resolve_addr(&mut self, addr: in_addr) -> Result; } +/// Trait for resolving hostnames and IP addresses. +/// +/// This trait combines [`ResolveHostname`] and [`ResolveAddr`]. pub trait DnsResolver: ResolveHostname + ResolveAddr {} diff --git a/src/traits/mod.rs b/src/traits/mod.rs index 184981b..77f5b3f 100644 --- a/src/traits/mod.rs +++ b/src/traits/mod.rs @@ -5,6 +5,7 @@ pub mod io; /// A trait for a buffer that can be used with a socket pub trait SocketBuffer { + /// Create a new buffer fn new() -> Self where Self: Sized; @@ -12,7 +13,8 @@ pub trait SocketBuffer { /// Append a buffer to the end of itself fn append_buffer(&mut self, buf: &[u8]); - /// Shift the buffer to the left by amount. + /// Shift the buffer to the left by amount + /// /// This is used to remove data from the buffer. fn shift_left_buffer(&mut self, amount: usize);