util: add links to tokio-util + example to BytesCodec (#2207)

tokio-util/src/codec/decoder.rs

@@ -8,14 +8,17 @@ use std::io;
 
 /// Decoding of frames via buffers.
 ///
-/// This trait is used when constructing an instance of `Framed` or
-/// `FramedRead`. An implementation of `Decoder` takes a byte stream that has
+/// This trait is used when constructing an instance of [`Framed`] or
+/// [`FramedRead`]. An implementation of `Decoder` takes a byte stream that has
 /// already been buffered in `src` and decodes the data into a stream of
 /// `Self::Item` frames.
 ///
 /// Implementations are able to track state on `self`, which enables
 /// implementing stateful streaming parsers. In many cases, though, this type
 /// will simply be a unit struct (e.g. `struct HttpDecoder`).
+///
+/// [`Framed`]: crate::codec::Framed
+/// [`FramedRead`]: crate::codec::FramedRead
 pub trait Decoder {
     /// The type of decoded frames.
     type Item;
@@ -27,17 +30,19 @@ pub trait Decoder {
     /// useful to report the failure as an `Item`.
     ///
     /// `From<io::Error>` is required in the interest of making `Error` suitable
-    /// for returning directly from a `FramedRead`, and to enable the default
+    /// for returning directly from a [`FramedRead`], and to enable the default
     /// implementation of `decode_eof` to yield an `io::Error` when the decoder
     /// fails to consume all available data.
     ///
     /// Note that implementors of this trait can simply indicate `type Error =
     /// io::Error` to use I/O errors as this type.
+    ///
+    /// [`FramedRead`]: crate::codec::FramedRead
     type Error: From<io::Error>;
 
     /// Attempts to decode a frame from the provided buffer of bytes.
     ///
-    /// This method is called by `FramedRead` whenever bytes are ready to be
+    /// This method is called by [`FramedRead`] whenever bytes are ready to be
     /// parsed. The provided buffer of bytes is what's been read so far, and
     /// this instance of `Decode` can determine whether an entire frame is in
     /// the buffer and is ready to be returned.
@@ -49,7 +54,7 @@ pub trait Decoder {
     /// most circumstances.
     ///
     /// If the bytes look valid, but a frame isn't fully available yet, then
-    /// `Ok(None)` is returned. This indicates to the `Framed` instance that
+    /// `Ok(None)` is returned. This indicates to the [`Framed`] instance that
     /// it needs to read some more bytes before calling this method again.
     ///
     /// Note that the bytes provided may be empty. If a previous call to
@@ -58,9 +63,12 @@ pub trait Decoder {
     /// be read.
     ///
     /// Finally, if the bytes in the buffer are malformed then an error is
-    /// returned indicating why. This informs `Framed` that the stream is now
+    /// returned indicating why. This informs [`Framed`] that the stream is now
     /// corrupt and should be terminated.
     ///
+    /// [`Framed`]: crate::codec::Framed
+    /// [`FramedRead`]: crate::codec::FramedRead
+    ///
     /// # Buffer management
     ///
     /// Before returning from the function, implementations should ensure that
@@ -128,7 +136,7 @@ pub trait Decoder {
         }
     }
 
-    /// Provides a `Stream` and `Sink` interface for reading and writing to this
+    /// Provides a [`Stream`] and [`Sink`] interface for reading and writing to this
     /// `Io` object, using `Decode` and `Encode` to read and write the raw data.
     ///
     /// Raw I/O objects work with byte sequences, but higher-level code usually
@@ -143,8 +151,12 @@ pub trait Decoder {
     /// underlying object.
     ///
     /// If you want to work more directly with the streams and sink, consider
-    /// calling `split` on the `Framed` returned by this method, which will
+    /// calling `split` on the [`Framed`] returned by this method, which will
     /// break them into separate objects, allowing them to interact more easily.
+    ///
+    /// [`Stream`]: tokio::stream::Stream
+    /// [`Sink`]: futures_sink::Sink
+    /// [`Framed`]: crate::codec::Framed
     fn framed<T: AsyncRead + AsyncWrite + Sized>(self, io: T) -> Framed<T, Self>
     where
         Self: Encoder + Sized,