From 99725815af43f078a4dd9a0461d722a66a2ed5ea Mon Sep 17 00:00:00 2001
From: Quentin Dufour <quentin@deuxfleurs.fr>
Date: Mon, 24 Jul 2023 14:41:21 +0200
Subject: [PATCH] Document a little bit the code

---
 src/error.rs    |  2 ++
 src/header.rs   |  1 +
 src/imf/mod.rs  |  2 ++
 src/lib.rs      | 81 ++++++++++++++++++++++++++++++++++++++++++++++---
 src/mime/mod.rs |  7 +++++
 src/part/mod.rs |  5 +++
 6 files changed, 94 insertions(+), 4 deletions(-)

diff --git a/src/error.rs b/src/error.rs
index 4ac3c86..127c45a 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -1,3 +1,5 @@
+/// Errors triggered when parsing email
+
 #[derive(Debug, PartialEq)]
 pub enum EMLError<'a> {
     ParseError(nom::Err<nom::error::Error<&'a [u8]>>),
diff --git a/src/header.rs b/src/header.rs
index b5fe4cd..637ef9d 100644
--- a/src/header.rs
+++ b/src/header.rs
@@ -1,3 +1,4 @@
+
 use crate::text::misc_token::{unstructured, Unstructured};
 use crate::text::whitespace::{foldable_line, obs_crlf};
 use nom::{
diff --git a/src/imf/mod.rs b/src/imf/mod.rs
index 9831d05..8aad350 100644
--- a/src/imf/mod.rs
+++ b/src/imf/mod.rs
@@ -1,3 +1,5 @@
+/// Parse and represent IMF (Internet Message Format) headers (RFC822, RFC5322)
+
 pub mod address;
 pub mod datetime;
 pub mod field;
diff --git a/src/lib.rs b/src/lib.rs
index b535fb5..2f5383f 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,18 +1,91 @@
 #![doc = include_str!("../README.md")]
 
-pub mod error;
-mod header;
-pub mod imf;
-pub mod mime;
+/// Parse and represent full emails as "parts" as defined by MIME (RFC 2046)
 pub mod part;
+
+/// Parse and represent IMF (Internet Message Format) headers (RFC 822, RFC 5322)
+pub mod imf;
+
+/// Parse and represent MIME headers (RFC 2045, RFC 2047)
+pub mod mime;
+
+/// MIME and IMF represent headers the same way: module contains their commong logic
+pub mod header;
+
+/// Low-level email-specific text-based representation for data
 pub mod text;
 
+/// Error management
+pub mod error;
+
+/// Parse a whole email including its (MIME) body
+///
+/// Returns the parsed content, but also the remaining bytes
+/// if the parser stopped before arriving to the end (for example
+/// due to a multipart delimiter).
+///
+/// # Arguments
+///
+/// * `input` - A buffer of bytes containing your full email
+///
+/// # Examples
+/// 
+/// ```
+/// let input = br#"Date: 7 Mar 2023 08:00:00 +0200
+/// From: deuxfleurs@example.com
+/// To: someone_else@example.com
+/// Subject: An RFC 822 formatted message
+/// MIME-Version: 1.0
+/// Content-Type: text/plain; charset=us-ascii
+///
+/// This is the plain text body of the message. Note the blank line
+/// between the header information and the body of the message."#;
+///
+/// let email = eml_codec::email(input).unwrap();
+/// println!(
+///     "{} raw message is:\n{}",
+///     email.imf.from[0].to_string(),
+///     String::from_utf8_lossy(email.child.as_text().unwrap().body),
+/// );
+/// ```
 pub fn email(input: &[u8]) -> Result<part::composite::Message, error::EMLError> {
     part::composite::message(mime::Message::default())(input)
         .map(|(_, v)| v)
         .map_err(error::EMLError::ParseError)
 }
 
+/// Only extract the headers of the email that are part of the Internet Message Format spec
+///
+/// Emails headers contain MIME and IMF (Internet Message Format) headers.
+/// Sometimes you only need to know the recipient or the sender of an email,
+/// and are not interested in its content. In this case, you only need to parse the IMF
+/// fields and can ignore the MIME headers + the body. This is what this function does.
+///
+/// # Arguments
+///
+/// * `input` - A buffer of bytes containing either only the headers of your email or your full
+/// email (in both cases, the body will be ignored)
+///
+/// # Examples
+///
+/// ```
+/// let input = br#"Date: 7 Mar 2023 08:00:00 +0200
+/// From: deuxfleurs@example.com
+/// To: someone_else@example.com
+/// Subject: An RFC 822 formatted message
+/// MIME-Version: 1.0
+/// Content-Type: text/plain; charset=us-ascii
+///
+/// This is the plain text body of the message. Note the blank line
+/// between the header information and the body of the message."#;
+///
+/// let header = eml_codec::imf(input).unwrap();
+/// println!(
+///     "{} just sent you an email with subject \"{}\"",
+///     header.from[0].to_string(),
+///     header.subject.unwrap().to_string(),
+/// );
+/// ```
 pub fn imf(input: &[u8]) -> Result<imf::Imf, error::EMLError> {
     imf::field::imf(input)
         .map(|(_, v)| v)
diff --git a/src/mime/mod.rs b/src/mime/mod.rs
index 9065938..5b0a314 100644
--- a/src/mime/mod.rs
+++ b/src/mime/mod.rs
@@ -1,6 +1,13 @@
+/// Parsed and represent an email character set 
 pub mod charset;
+
+/// MIME specific headers
 pub mod field;
+
+/// Transfer-Encoding representation
 pub mod mechanism;
+
+/// Content-Type representation
 pub mod r#type;
 
 use crate::imf::identification::MessageID;
diff --git a/src/part/mod.rs b/src/part/mod.rs
index 12c142a..d3db613 100644
--- a/src/part/mod.rs
+++ b/src/part/mod.rs
@@ -1,5 +1,10 @@
+/// Parts that contain other parts inside them
 pub mod composite;
+
+/// Parts that have a body and no child parts
 pub mod discrete;
+
+/// IMF + MIME fields parsed at once
 pub mod field;
 
 use nom::{