docs: improve crate docs

Author: josecelano

src/lib.rs

@@ -1,8 +1,39 @@
 //! This lib contains functions to convert bencoded bytes into a JSON string.
 //!
-//! There are high-level functions for common purposes that call the lower level
-//! parser. You can use the low-lever parser if the high-level wrappers are not
-//! suitable for your needs.
+//! Bencode is a simple encoding format that is used to encode arbitrary
+//! data structures. It is commonly used in the context of torrent files,
+//! where the data structures are used to describe the contents of the torrent
+//! file.
+//!
+//! To learn more about bencode, you can refer to the following resources:
+//!
+//! - <https://en.wikipedia.org/wiki/Bencode>
+//! - <https://www.bittorrent.org/beps/bep_0003.html>
+//!
+//! Thi lib has high-level functions for common purposes that call the lower
+//! level parser. You can use the low-lever parser if the high-level wrappers
+//! are not suitable for your needs.
+//!
+//! The most straightforward way to use this lib is to use the `try_bencode_to_json`
+//! function:
+//!
+//! ```rust
+//! use torrust_bencode2json::{try_bencode_to_json};
+//!
+//! let result = try_bencode_to_json(b"d4:spam4:eggse").unwrap();
+//!
+//! assert_eq!(result, r#"{"spam":"eggs"}"#);
+//! ```
+//!
+//! The primary goal of this lib is to provide a simple and easy-to-use API for
+//! converting bencoded data into JSON. It's also designed to be flexible and
+//! efficient, making it suitable for a wide range of use cases.
+//!
+//! A design requirement is to be able to parse bencoded data without building
+//! an in-memory representation of the whole bencoded data structure.
+//!
+//! > __NOTICE__: In the context of this lib, parser is a function that takes an input
+//! > containing bencoded data and produces a JSON output (raw bytes or UTF-8 string).
 use parsers::{error::Error, BencodeParser};
 
 pub mod parsers;

src/parsers/error.rs

@@ -11,70 +11,110 @@ use crate::rw;
 
 use super::BencodeType;
 
+/// Errors that can occur while parsing a bencoded value.
 #[derive(Debug, Error)]
 pub enum Error {
+    /// I/O error.
     #[error("I/O error: {0}")]
     Io(#[from] io::Error),
 
+    /// R/W error.
     #[error("R/W error: {0}")]
     Rw(#[from] rw::error::Error),
 
+    /// Read byte after peeking does match peeked byte.
+    ///
+    /// The main parser peeks one byte ahead to know what kind of bencoded value
+    /// is being parsed. If the byte read after peeking does not match the
+    /// peeked byte, it means the input is being consumed somewhere else.
     #[error("Read byte after peeking does match peeked byte; {0}; {1}")]
     ReadByteAfterPeekingDoesMatchPeekedByte(ReadContext, WriteContext),
 
+    /// Unrecognized first byte for new bencoded value.
+    ///
+    /// The main parser peeks one byte ahead to know what kind of bencoded value
+    /// is being parsed. This error is raised when the peeked byte is not a
+    /// valid first byte for a bencoded value.
     #[error("Unrecognized first byte for new bencoded value; {0}; {1}")]
     UnrecognizedFirstBencodeValueByte(ReadContext, WriteContext),
 
     // Integers
+    /// Unexpected byte parsing integer.
+    ///
+    /// The main parser parses integers by reading bytes until it finds the
+    /// end of the integer. This error is raised when the byte read is not a
+    /// valid byte for an integer bencoded value.
     #[error("Unexpected byte parsing integer; {0}; {1}")]
     UnexpectedByteParsingInteger(ReadContext, WriteContext),
 
+    /// Unexpected end of input parsing integer.
+    ///
+    /// The input ends before the integer ends.
     #[error("Unexpected end of input parsing integer; {0}; {1}")]
     UnexpectedEndOfInputParsingInteger(ReadContext, WriteContext),
 
+    /// Leading zeros in integers are not allowed, for example b'i00e'.
     #[error("Leading zeros in integers are not allowed, for example b'i00e'; {0}; {1}")]
     LeadingZerosInIntegersNotAllowed(ReadContext, WriteContext),
 
     // Strings
+    /// Invalid string length byte, expected a digit.
+    ///
+    /// The string parser found an invalid byte for the string length. The
+    /// length can only be made of digits (0-9).
     #[error("Invalid string length byte, expected a digit; {0}; {1}")]
     InvalidStringLengthByte(ReadContext, WriteContext),
 
+    /// Unexpected end of input parsing string length.
+    ///
+    /// The input ends before the string length ends.
     #[error("Unexpected end of input parsing string length; {0}; {1}")]
     UnexpectedEndOfInputParsingStringLength(ReadContext, WriteContext),
 
+    /// Unexpected end of input parsing string value.
+    ///
+    /// The input ends before the string value ends.
     #[error("Unexpected end of input parsing string value; {0}; {1}")]
     UnexpectedEndOfInputParsingStringValue(ReadContext, WriteContext),
 
     // Lists
+    /// Unexpected end of input parsing list. Expecting first list item or list end.
     #[error(
         "Unexpected end of input parsing list. Expecting first list item or list end; {0}; {1}"
     )]
     UnexpectedEndOfInputExpectingFirstListItemOrEnd(ReadContext, WriteContext),
 
+    /// Unexpected end of input parsing list. Expecting next list item.
     #[error("Unexpected end of input parsing list. Expecting next list item; {0}; {1}")]
     UnexpectedEndOfInputExpectingNextListItem(ReadContext, WriteContext),
 
     // Dictionaries
+    /// Unexpected end of input parsing dictionary. Expecting first dictionary field or dictionary end.
     #[error("Unexpected end of input parsing dictionary. Expecting first dictionary field or dictionary end; {0}; {1}")]
     UnexpectedEndOfInputExpectingFirstDictFieldOrEnd(ReadContext, WriteContext),
 
+    /// Unexpected end of input parsing dictionary. Expecting dictionary field value.
     #[error(
         "Unexpected end of input parsing dictionary. Expecting dictionary field value; {0}; {1}"
     )]
     UnexpectedEndOfInputExpectingDictFieldValue(ReadContext, WriteContext),
 
+    /// Unexpected end of input parsing dictionary. Expecting dictionary field key or end.
     #[error(
         "Unexpected end of input parsing dictionary. Expecting dictionary field key or end; {0}; {1}"
     )]
     UnexpectedEndOfInputExpectingDictFieldKeyOrEnd(ReadContext, WriteContext),
 
+    /// Unexpected end of dictionary. Premature end of dictionary.
     #[error("Unexpected end of dictionary. Premature end of dictionary; {0}; {1}")]
     PrematureEndOfDict(ReadContext, WriteContext),
 
+    /// Expected string for dictionary field key.
     #[error("Expected string for dictionary field key, but got: {0}, {1}")]
     ExpectedStringForDictKeyGot(BencodeType, ReadContext, WriteContext),
 
     // List and dictionaries
+    /// Unexpected end of list or dict. No matching start for the list or dict end.
     #[error(
         "Unexpected end of list or dict. No matching start for the list or dict end: {0}, {1}"
     )]

src/parsers/mod.rs

@@ -1,5 +1,8 @@
 //! Parsers, including the main parser and the parsers for the basic types
-//! (integer and string)
+//! (integer and string).
+//! 
+//! ``BencodeParser`` is the main parser. It is generic over the type of the
+//! input buffer.
 pub mod error;
 pub mod integer;
 pub mod stack;

src/parsers/stack.rs

@@ -2,11 +2,14 @@
 //! current parsing state.
 use std::fmt::Display;
 
-/// Stack with containing states for nested Bencoded values.
+/// Stack containing states for nested Bencoded values.
 ///
-/// The stat has an immutable initial state.
+/// The stack has an immutable initial state.
+///
+/// > NOTICE!: It's not allowed to pop or change the initial state.
 #[derive(Debug)]
 pub struct Stack {
+    /// The stack of states.
     states: Vec<State>,
 }
 
@@ -17,21 +20,36 @@ pub struct Stack {
 ///
 /// States are displayed with a short name using only one letter:
 ///
-/// I, L, M, D, E, F
+/// `I`, `L`, `M`, `D`, `E`, `F`
 ///
-/// This comes from the original implementation.
+/// This comes from the original implementation in C.
 #[derive(Debug, PartialEq, Clone)]
 pub enum State {
+    /// The initial state.
+    /// /// The sort display name for the state is L.
     Initial, // I
 
     // States while parsing lists
-    ExpectingFirstListItemOrEnd, // L
-    ExpectingNextListItem,       // M
+    /// Expecting the first list item or the end of the list.
+    /// The sort display name for the state is L.
+    ExpectingFirstListItemOrEnd,
+
+    /// Expecting the next list item. List contains at least one item.
+    /// The sort display name for the state is M.
+    ExpectingNextListItem,
 
     // States while parsing dictionaries
-    ExpectingFirstDictFieldOrEnd, // D
-    ExpectingDictFieldValue,      // E
-    ExpectingDictFieldKeyOrEnd,   // F
+    /// Expecting the first dict field or the end of the dict.
+    /// The sort display name for the state is D.
+    ExpectingFirstDictFieldOrEnd,
+
+    /// Expecting the dict field value.
+    /// The sort display name for the state is E.
+    ExpectingDictFieldValue,
+
+    /// Expecting the dict field key or the end of the dict.
+    /// The sort display name for the state is F.
+    ExpectingDictFieldKeyOrEnd,
 }
 
 impl Display for State {