docs: improve documentation (#2)

* docs: improve documentation

* revert `cfg_attr`

* docs: improvements to documentation

* docs: minor improvements

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;

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 })

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,
         }
     }

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<dyn SocketBuffer>,
 }
 
 impl TcpSocket {
-    #[allow(dead_code)]
     /// Create a TCP socket
+    #[allow(dead_code)]
     pub fn new() -> Result<TcpSocket, SocketError> {
         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()
     }

src/socket/tls.rs

@@ -38,14 +38,20 @@ 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
     /// ```no_run
     /// 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],

src/socket/udp.rs

@@ -28,24 +28,23 @@ 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,
 ///   this struct implements [`EasySocket`] trait, which allows for an easier management of the socket,
 ///   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<sockaddr>,
+    /// The state of the socket
     state: UdpSocketState,
+    /// The buffer to store data to send
     buffer: Box<dyn SocketBuffer>,
 }
 
@@ -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<usize, SocketError> {
         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),

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<SocketAddr, Self::Error>;
 }
 
+/// 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<String, Self::Error>;
 }
 
+/// Trait for resolving hostnames and IP addresses.
+///
+/// This trait combines [`ResolveHostname`] and [`ResolveAddr`].
 pub trait DnsResolver: ResolveHostname + ResolveAddr {}

src/traits/mod.rs

@@ -5,14 +5,16 @@ 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;
 
     /// 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);