Add documentation to lib, ints, and strings

Signed-off-by: Marcel Müller <neikos@neikos.email>

3 files changed, 31 insertions, 0 deletions

diff --git a/mqtt-format/src/lib.rs b/mqtt-format/src/lib.rs
index bed8140..b227b65 100644
--- a/mqtt-format/src/lib.rs
+++ b/mqtt-format/src/lib.rs
@@ -9,5 +9,9 @@
 
 #[cfg(feature = "mqttv3")]
 pub mod v3;
+
+/// MQTTv5 binary format parsing
+///
+#[doc = util::md_speclink!("_Toc3901000")]
 #[cfg(feature = "mqttv5")]
 pub mod v5;
diff --git a/mqtt-format/src/v5/integers.rs b/mqtt-format/src/v5/integers.rs
index 96fa8aa..91990cc 100644
--- a/mqtt-format/src/v5/integers.rs
+++ b/mqtt-format/src/v5/integers.rs
@@ -3,6 +3,9 @@
 //   License, v. 2.0. If a copy of the MPL was not distributed with this
 //   file, You can obtain one at http://mozilla.org/MPL/2.0/.
 //
+//! Various ways to parse MQTT integers
+//!
+//! All integers in MQTT are big-endian
 
 use winnow::combinator::trace;
 use winnow::token::take_while;
@@ -11,6 +14,10 @@ use winnow::Parser;
 
 use super::MResult;
 
+/// Parse a u16
+///
+/// MQTT expects their numbers in big-endian
+#[doc = crate::v5::util::md_speclink!("_Toc3901008")]
 pub fn parse_u16(input: &mut &Bytes) -> MResult<u16> {
     trace(
         "mqtt_u16",
@@ -19,6 +26,10 @@ pub fn parse_u16(input: &mut &Bytes) -> MResult<u16> {
     .parse_next(input)
 }
 
+/// Parse a u32
+///
+/// MQTT expects their numbers in big-endian
+#[doc = crate::v5::util::md_speclink!("_Toc3901009")]
 pub fn parse_u32(input: &mut &Bytes) -> MResult<u32> {
     trace(
         "mqtt_u32",
@@ -27,6 +38,12 @@ pub fn parse_u32(input: &mut &Bytes) -> MResult<u32> {
     .parse_next(input)
 }
 
+/// Parse a variable sized integer
+///
+/// Value range: `0..268_435_455`
+/// The maximal value is smaller than a u32, so that type is used
+///
+#[doc = crate::v5::util::md_speclink!("_Toc3901011")]
 pub fn parse_variable_u32(input: &mut &Bytes) -> MResult<u32> {
     trace("mqtt_variable_u32", |input: &mut &Bytes| {
         let var_bytes = (
diff --git a/mqtt-format/src/v5/strings.rs b/mqtt-format/src/v5/strings.rs
index 48fb102..66e8be9 100644
--- a/mqtt-format/src/v5/strings.rs
+++ b/mqtt-format/src/v5/strings.rs
@@ -13,6 +13,11 @@ use winnow::Parser;
 use super::integers::parse_u16;
 use super::MResult;
 
+/// Parse an UTF-8 String
+///
+/// MQTT expects that all Strings are UTF-8 encoded
+///
+#[doc = crate::v5::util::md_speclink!("_Toc3901010")]
 pub fn parse_string<'i>(input: &mut &'i Bytes) -> MResult<&'i str> {
     winnow::combinator::trace("mqtt_string", |input: &mut &'i Bytes| {
         let maybe_str = length_take(parse_u16).parse_next(input)?;
@@ -23,6 +28,11 @@ pub fn parse_string<'i>(input: &mut &'i Bytes) -> MResult<&'i str> {
     .parse_next(input)
 }
 
+/// Parse a pair of UTF-8 Strings
+///
+/// MQTT expects that all Strings are UTF-8 encoded
+///
+#[doc = crate::v5::util::md_speclink!("_Toc3901013")]
 pub fn string_pair<'i>(input: &mut &'i Bytes) -> MResult<(&'i str, &'i str)> {
     winnow::combinator::trace("mqtt_string_pair", |input: &mut &'i Bytes| {
         let first = parse_string(input)?;