async UDP: Documentation fixes; receive_into consistency

One trait's receive_into still used the old receive name.

Author: chrysn

embedded-nal-async/src/stack/udp.rs

@@ -27,10 +27,12 @@ use no_std_net::SocketAddr;
 /// `bind()` call in the creation of such sockets, these are implicitly bound to a suitable local
 /// address at connect time.
 pub trait ConnectedUdp {
+    /// Error type returned by send and receive operations.
     type Error: embedded_io::Error;
 
     /// Send the provided data to the connected peer
     fn send(&mut self, data: &[u8]) -> Self::SendFuture<'_>;
+    /// Return type of the [`.send()`] method
     type SendFuture<'a>: Future<Output = Result<(), Self::Error>> where Self: 'a;
 
     /// Receive a datagram into the provided buffer.
@@ -45,6 +47,7 @@ pub trait ConnectedUdp {
     /// (a possibility not considered there). The name deviates from the original `receive()` to
     /// make room for a version that is more zero-copy friendly.
     fn receive_into(&mut self, buffer: &mut [u8]) -> Self::ReceiveIntoFuture<'_>;
+    /// Return type of the [`.receive_into()`] method
     type ReceiveIntoFuture<'a>: Future<Output = Result<usize, Self::Error>> where Self: 'a;
 
     // WIP to allow zero-copy operation
@@ -67,6 +70,7 @@ pub trait ConnectedUdp {
 /// caller MUST pass in the same (or compatible) values, MAY and pass in unspecified values where
 /// applicable. The implementer MAY check them for compatibility, and SHOULD do that in debug mode.
 pub trait UnconnectedUdp {
+    /// Error type returned by send and receive operations.
     type Error: embedded_io::Error;
 
     /// Send the provided data to a peer
@@ -86,13 +90,14 @@ pub trait UnconnectedUdp {
     /// address. Both are valid choices in some situations, and the right choice depends on the
     /// protocol used.
     ///
-    /// Note that users of sockets created through [`UdpSocket::bind_single()`] should always pass
+    /// Note that users of sockets created through [`UdpStack::bind_single()`] should always pass
     /// in that single address -- even though they've made their intention clear at construction.
     /// They can pass either the one obtained at socket creation time, or the one obtained at
     /// receive time; these should be equal. This allows implementations of the trait to use a
     /// single kind of socket for both sockets bound to a single and sockets bound to multiple
     /// addresses.
     fn send(&mut self, local: SocketAddr, remote: SocketAddr, data: &[u8]) -> Self::SendFuture<'_>;
+    /// Return type of the [`.send()`] method
     type SendFuture<'a>: Future<Output = Result<(), Self::Error>> where Self: 'a;
 
     /// Receive a datagram into the provided buffer.
@@ -103,8 +108,9 @@ pub trait UnconnectedUdp {
     ///
     /// The local and remote address are given, in that order, in the result along with the number
     /// of bytes.
-    fn receive(&mut self, buffer: &mut [u8]) -> Self::ReceiveFuture<'_>;
-    type ReceiveFuture<'a>: Future<Output = Result<(usize, SocketAddr, SocketAddr), Self::Error>> where Self: 'a;
+    fn receive_into(&mut self, buffer: &mut [u8]) -> Self::ReceiveIntoFuture<'_>;
+    /// Return type of the [`.receive_into()`] method
+    type ReceiveIntoFuture<'a>: Future<Output = Result<(usize, SocketAddr, SocketAddr), Self::Error>> where Self: 'a;
 }
 
 /// This trait is implemented by UDP/IP stacks. The trait allows the underlying driver to
@@ -116,8 +122,11 @@ pub trait UdpStack {
     /// Error type returned on socket creation failure.
     type Error: embedded_io::Error;
 
+    /// Eventual socket return type of the [`.connect()`] method
     type Connected<'m>: ConnectedUdp where Self: 'm;
+    /// Eventual socket return type of the [`.bind_single()`] method
     type Bound<'m>: UnconnectedUdp where Self: 'm;
+    /// Eventual return type of the [`.bind_multiple()`] method
     type Unbound<'m>: UnconnectedUdp where Self: 'm;
 
     /// Create a socket that has a fixed remote address.
@@ -126,8 +135,9 @@ pub trait UdpStack {
     ///
     /// While asynchronous traits implemented through GAT can not have provided default methods,
     /// implementers are encouraged to use the hidden `.connect_default()` method if all they would
-    /// do is delegating to [`connect_from`] with a suitable unspecified local address.
+    /// do is delegating to [`.connect_from`] with a suitable unspecified local address.
     fn connect(&self, remote: SocketAddr) -> Self::ConnectFuture<'_>;
+    /// Future return type of the [`.connect()`] method
     type ConnectFuture<'a>: Future<Output = Result<(SocketAddr, Self::Connected<'a>), Self::Error>> where Self: 'a;
 
     /// Create a socket that has a fixed remote address.
@@ -136,6 +146,7 @@ pub trait UdpStack {
     /// network stack at connection time. The full local address is returned along with the
     /// connected socket, primarily for debugging purposes.
     fn connect_from(&self, local: SocketAddr, remote: SocketAddr) -> Self::ConnectFromFuture<'_>;
+    /// Future return type of the [`.connect_from()`] method
     type ConnectFromFuture<'a>: Future<Output = Result<(SocketAddr, Self::Connected<'a>), Self::Error>> where Self: 'a;
 
     /// Helper that implements [`connect()`] using [`connect_from()`].
@@ -159,6 +170,7 @@ pub trait UdpStack {
     /// The full local address is returned along with the bound socket; it may then be passed on to
     /// other protocols for advertising purposes.
     fn bind_single(&self, local: SocketAddr) -> Self::BindSingleFuture<'_>;
+    /// Future return type of the [`.bind_single()`] method
     type BindSingleFuture<'a>: Future<Output = Result<(SocketAddr, Self::Bound<'a>), Self::Error>> where Self: 'a;
 
     /// Create a socket that has no single fixed local address.
@@ -184,5 +196,6 @@ pub trait UdpStack {
     ///   binding to `[::]:0`, that is, picking some available port but then still leaving the
     ///   interface and IP address unspecified.
     fn bind_multiple(&self, local: SocketAddr) -> Self::BindMultipleFuture<'_>;
+    /// Future return type of the [`.bind_multiple()`] method
     type BindMultipleFuture<'a>: Future<Output = Result<Self::Unbound<'a>, Self::Error>> where Self: 'a;
 }