Fixes from tnull review

properly link struct and function definitions in `ser_macro.rs` docs

Author: mariocynicys

lightning/src/util/ser_macros.rs

@@ -41,7 +41,7 @@ macro_rules! _encode_tlv {
 	};
 }
 
-/// Implements the TLVs serialization part in a Writeable implementation of a struct.
+/// Implements the TLVs serialization part in a [`Writeable`] implementation of a struct.
 ///
 /// This should be called inside a method which returns `Result<_, `[`io::Error`]`>`, such as
 /// [`Writeable::write`]. It will only return an `Err` if the stream `Err`s or [`Writeable::write`]
@@ -75,6 +75,7 @@ macro_rules! _encode_tlv {
 /// # }
 /// ```
 ///
+/// [`Writeable`]: crate::util::ser::Writeable
 /// [`io::Error`]: crate::io::Error
 /// [`Writeable::write`]: crate::util::ser::Writeable::write
 /// [`Writer`]: crate::util::ser::Writer
@@ -107,8 +108,10 @@ macro_rules! encode_tlv_stream {
 	} }
 }
 
-/// Adds the length of the serialized field to a LengthCalculatingWriter.
+/// Adds the length of the serialized field to a [`LengthCalculatingWriter`].
 /// This is exported for use by other exported macros, do not use directly.
+///
+/// [`LengthCalculatingWriter`]: crate::util::ser::LengthCalculatingWriter
 #[doc(hidden)]
 #[macro_export]
 macro_rules! _get_varint_length_prefixed_tlv_length {
@@ -134,7 +137,7 @@ macro_rules! _get_varint_length_prefixed_tlv_length {
 	};
 }
 
-/// See the documentation of write_tlv_fields!().
+/// See the documentation of [`write_tlv_fields`].
 /// This is exported for use by other exported macros, do not use directly.
 #[doc(hidden)]
 #[macro_export]
@@ -261,7 +264,7 @@ macro_rules! _decode_tlv {
 	}};
 }
 
-/// Implements the TLVs deserialization part in a Readable implementation of a struct.
+/// Implements the TLVs deserialization part in a [`Readable`] implementation of a struct.
 ///
 /// This should be called inside a method which returns `Result<_, `[`DecodeError`]`>`, such as
 /// [`Readable::read`]. It will either return an `Err` or ensure all `required` fields have been
@@ -293,6 +296,7 @@ macro_rules! _decode_tlv {
 /// # }
 /// ```
 ///
+/// [`Readable`]: crate::util::ser::Readable
 /// [`DecodeError`]: crate::ln::msgs::DecodeError
 /// [`Readable::read`]: crate::util::ser::Readable::read
 /// [`Read`]: crate::io::Read
@@ -308,9 +312,12 @@ macro_rules! decode_tlv_stream {
 /// Similar to [`decode_tlv_stream`] with a custom TLV decoding capabilities.
 ///
 /// `$decode_custom_tlv` is a closure that may be optionally provided to handle custom message types.
-/// If it is provided, it will be called with the custom type and the `FixedLengthReader` containing
+/// If it is provided, it will be called with the custom type and the [`FixedLengthReader`] containing
 /// the message contents. It should return `Ok(true)` if the custom message is successfully parsed,
-/// `Ok(false)` if the message type is unknown, and `Err(DecodeError)` if parsing fails.
+/// `Ok(false)` if the message type is unknown, and `Err(`[`DecodeError`]`)` if parsing fails.
+///
+/// [`FixedLengthReader`]: crate::util::ser::FixedLengthReader
+/// [`DecodeError`]: crate::ln::msgs::DecodeError
 macro_rules! decode_tlv_stream_with_custom_tlv_decode {
 	($stream: expr, {$(($type: expr, $field: ident, $fieldty: tt)),* $(,)*}
 	 $(, $decode_custom_tlv: expr)?) => { {
@@ -464,12 +471,14 @@ macro_rules! impl_writeable {
 ///               object.
 /// $min_version_that_can_read_this is the minimum reader version which can understand this
 ///                                 serialized object. Previous versions will simply err with a
-///                                 DecodeError::UnknownVersion.
+///                                 [`DecodeError::UnknownVersion`].
 ///
 /// Updates to either $this_version or $min_version_that_can_read_this should be included in
 /// release notes.
 ///
 /// Both version fields can be specific to this type of object.
+///
+/// [`DecodeError::UnknownVersion`]: crate::ln::msgs::DecodeError::UnknownVersion
 macro_rules! write_ver_prefix {
 	($stream: expr, $this_version: expr, $min_version_that_can_read_this: expr) => {
 		$stream.write_all(&[$this_version; 1])?;
@@ -481,20 +490,22 @@ macro_rules! write_ver_prefix {
 /// fields which old nodes can happily ignore.
 ///
 /// It is written out in TLV format and, as with all TLV fields, unknown even fields cause a
-/// DecodeError::UnknownRequiredFeature error, with unknown odd fields ignored.
+/// [`DecodeError::UnknownRequiredFeature`] error, with unknown odd fields ignored.
 ///
 /// This is the preferred method of adding new fields that old nodes can ignore and still function
 /// correctly.
+///
+/// [`DecodeError::UnknownRequiredFeature`]: crate::ln::msgs::DecodeError::UnknownRequiredFeature
 #[macro_export]
 macro_rules! write_tlv_fields {
 	($stream: expr, {$(($type: expr, $field: expr, $fieldty: tt)),* $(,)*}) => {
 		$crate::_encode_varint_length_prefixed_tlv!($stream, {$(($type, $field, $fieldty)),*})
 	}
 }
 
-/// Reads a prefix added by write_ver_prefix!(), above. Takes the current version of the
+/// Reads a prefix added by [`write_ver_prefix`], above. Takes the current version of the
 /// serialization logic for this object. This is compared against the
-/// $min_version_that_can_read_this added by write_ver_prefix!().
+/// $min_version_that_can_read_this added by [`write_ver_prefix`].
 macro_rules! read_ver_prefix {
 	($stream: expr, $this_version: expr) => { {
 		let ver: u8 = Readable::read($stream)?;
@@ -506,7 +517,9 @@ macro_rules! read_ver_prefix {
 	} }
 }
 
-/// Reads a suffix added by write_tlv_fields!().
+/// Reads a suffix added by [`write_tlv_fields`].
+///
+/// [`write_tlv_fields`]: crate::write_tlv_fields
 #[macro_export]
 macro_rules! read_tlv_fields {
 	($stream: expr, {$(($type: expr, $field: ident, $fieldty: tt)),* $(,)*}) => { {
@@ -570,11 +583,14 @@ macro_rules! _init_and_read_tlv_fields {
 	}
 }
 
-/// Implements Readable/Writeable for a struct storing it as a set of TLVs
+/// Implements [`Readable`]/[`Writeable`] for a struct storing it as a set of TLVs
 /// If $fieldty is `required`, then $field is a required field that is not an Option nor a Vec.
 /// If $fieldty is `option`, then $field is optional field.
 /// if $fieldty is `vec_type`, then $field is a Vec, which needs to have its individual elements
 /// serialized.
+///
+/// [`Readable`]: crate::util::ser::Readable
+/// [`Writeable`]: crate::util::ser::Writeable
 #[macro_export]
 macro_rules! impl_writeable_tlv_based {
 	($st: ident, {$(($type: expr, $field: ident, $fieldty: tt)),* $(,)*}) => {
@@ -717,13 +733,18 @@ macro_rules! _impl_writeable_tlv_based_enum_common {
 	}
 }
 
-/// Implement MaybeReadable and Writeable for an enum, with struct variants stored as TLVs and
+/// Implement [`MaybeReadable`] and [`Writeable`] for an enum, with struct variants stored as TLVs and
 /// tuple variants stored directly.
 ///
-/// This is largely identical to `impl_writeable_tlv_based_enum`, except that odd variants will
-/// return `Ok(None)` instead of `Err(UnknownRequiredFeature)`. It should generally be preferred
-/// when `MaybeReadable` is practical instead of just `Readable` as it provides an upgrade path for
+/// This is largely identical to [`impl_writeable_tlv_based_enum`], except that odd variants will
+/// return `Ok(None)` instead of `Err(`[`DecodeError::UnknownRequiredFeature`]`)`. It should generally be preferred
+/// when [`MaybeReadable`] is practical instead of just [`Readable`] as it provides an upgrade path for
 /// new variants to be added which are simply ignored by existing clients.
+///
+/// [`MaybeReadable`]: crate::util::ser::MaybeReadable
+/// [`Writeable`]: crate::util::ser::Writeable
+/// [`DecodeError::UnknownRequiredFeature`]: crate::ln::msgs::DecodeError::UnknownRequiredFeature
+/// [`Readable`]: crate::util::ser::Readable
 macro_rules! impl_writeable_tlv_based_enum_upgradable {
 	($st: ident, $(($variant_id: expr, $variant_name: ident) =>
 		{$(($type: expr, $field: ident, $fieldty: tt)),* $(,)*}
@@ -765,7 +786,7 @@ macro_rules! impl_writeable_tlv_based_enum_upgradable {
 	}
 }
 
-/// Implement Readable and Writeable for an enum, with struct variants stored as TLVs and tuple
+/// Implement [`Readable`] and [`Writeable`] for an enum, with struct variants stored as TLVs and tuple
 /// variants stored directly.
 /// The format is, for example
 /// impl_writeable_tlv_based_enum!(EnumName,
@@ -774,7 +795,11 @@ macro_rules! impl_writeable_tlv_based_enum_upgradable {
 ///   (2, TupleVariantA), (3, TupleVariantB),
 /// );
 /// The type is written as a single byte, followed by any variant data.
-/// Attempts to read an unknown type byte result in DecodeError::UnknownRequiredFeature.
+/// Attempts to read an unknown type byte result in [`DecodeError::UnknownRequiredFeature`].
+///
+/// [`Readable`]: crate::util::ser::Readable
+/// [`Writeable`]: crate::util::ser::Writeable
+/// [`DecodeError::UnknownRequiredFeature`]: crate::ln::msgs::DecodeError::UnknownRequiredFeature
 macro_rules! impl_writeable_tlv_based_enum {
 	($st: ident, $(($variant_id: expr, $variant_name: ident) =>
 		{$(($type: expr, $field: ident, $fieldty: tt)),* $(,)*}