Big improvement to the documentation of this crate

Author: marcdejonge

Cargo.toml

@@ -43,7 +43,5 @@ proc-macro2 = "1.0"
 syn = { version = "2.0", features = ["extra-traits", "full", "visit", "visit-mut"] }
 itertools = "0.14.0"
 phf = { version = "0.11.2", features = ["macros"] }
-
-[dev-dependencies]
 nom-parse-trait = "0.2.0"
-nom = "7.1"
+nom = "7.1.3"

src/lib.rs

@@ -1,3 +1,46 @@
+//! # nom-parse-trait
+//!
+//! This macro generates a `ParseFrom` implementation for a struct or enum using the provided
+//! nom expression(s). The expression should return a tuple for the parsed fields.
+//!
+//! There are 2 separate macros available, [`parse_from()`] and [`parse_match()`].
+//! The first one is really generic and can be useful in many cases, since you have the full
+//! flexibility of nom functions and combinators. The second one is a very simple one that
+//! matches a string verbatim. This is useful when you have a very simple format that you want
+//! to parse.
+//!
+//! # nom functions
+//!
+//! The expression in the `parse_from` attribute will be translated to be using valid nom functions.
+//! The main function here is to automatically put the namespace before the function name, so you
+//! don't need a ton of use statements in your code. But there are also a couple of special cases:
+//!
+//! - `{}` or `()` will be replaced with a [`nom_parse_trait::ParseFrom::parse`] call for the
+//! corresponding field. This is useful when you are using types that have implemented the
+//! `ParseFrom` trait already.
+//! - Strings, bytes strings and characters will be translated to match the input verbatim using
+//! the [`nom::bytes::complete::tag`] function.
+//!
+//! # Input types that are supported
+//!
+//! The generated `ParseFrom` implementation is made to be very generic, where it supports any
+//! input and error type from nom. This is done with a where clause with many traits that the input
+//! should have implemented. All of these are true for the standard `&str` and `&[u8]` types.
+//!
+//! If you run into a situation where the trait limitations on the input type does not match your
+//! use case, please open an issue on the GitHub repository.
+//!
+//! # Known limitations
+//!
+//! - When your try to use a custom parser combinator, the nom function parser will try to change
+//! all parameters to be nom parsers. This is useful in many cases, but when you need to pass in
+//! a normal string for example, it won't work. In these cases, you can define a separate function
+//! to wrap the call. I'm not sure how to fix that right now, but I'm open to suggestions.
+//!
+//! - Since the generated input type is very generic, all functions that you want to use in the
+//! nom expression should also be very generic. In the future I might add a way to specify if you
+//! want to generate a specific input type, but for now it's not possible.
+
 extern crate proc_macro;
 mod fields;
 mod nom_packages;
@@ -16,6 +59,63 @@ use syn::{
     LitStr, TypeParam, WhereClause, WherePredicate,
 };
 
+/// This macro generates a [`nom_parse_trait::ParseFrom`] implementation for a struct or enum using
+/// the provided nom expression(s). The expression should return a tuple for the parsed fields.
+///
+/// # Examples
+///
+/// ## Basic struct with fields
+///
+/// This first example shows how to parse a simple struct with two fields, using the `separated_pair`
+/// combinator. Here we also show some of the special parsing that goes on behind the scenes, where
+/// the special {} syntax means that it infers the type parser it needs to use in that place. Also,
+/// we accept normal strings as matching input, which will be translated to `tag` function calls.
+///
+/// ```rust
+/// use nom_parse_macros::parse_from;
+///
+/// #[parse_from(separated_pair({}, tuple(space0, ",", space0), {}))]
+/// struct NumberPair {
+///     x: u32,
+///     y: u32,
+/// }
+/// ```
+///
+/// ## Basic enum with variants
+///
+/// This example shows how we can define a format for each variant in an enum. The first variant
+/// actually uses the default `ParseFrom` implementation for parsing the u32. The `Numbers` variant
+/// uses a custom format, which is a delimited list of u32 values.
+///
+/// ```rust
+/// use nom_parse_macros::parse_from;
+///
+/// #[parse_from]
+/// enum MultipleTypes {
+///     Number(u32),
+///     #[format(delimited('(', separated_list0(",", {}), ')'))]
+///     Numbers(Vec<u32>),
+/// }
+/// ```
+///
+/// ## Derived fields
+///
+/// Sometimes it's useful to have a field that is not actually parsed, but derived from the other
+/// fields. This can be done with the `#[derived]` attribute. In this example, we derive the sum of
+/// the two fields `x` and `y`.
+///
+/// ```rust
+/// use nom_parse_macros::parse_from;
+///
+/// #[parse_from(separated_pair({}, tuple(space0, ",", space0), {}))]
+/// struct NumberPair {
+///     x: u32,
+///     y: u32,
+///     #[derived(x + y)]
+///     sum: u32,
+/// }
+/// ```
+
 #[proc_macro_attribute]
 pub fn parse_from(attrs: TokenStream, object: TokenStream) -> TokenStream {
     match parse_macro_input!(object as Item) {
@@ -135,6 +235,27 @@ fn generate_enum_parser(mut object: ItemEnum) -> TokenStream {
     )
 }
 
+/// The `parse_match` macro can be used to match strings verbatim. This is useful when you have
+/// a very simple format that you want to parse. The {} gets replaced with a parser for the
+/// corresponding field. The rest of the characters are matched verbatim.
+///
+/// # Example
+///
+/// This example shows how to parse a three-dimensional vector from a string with a fixed format.
+/// As you can see, this macro is limited in its use, but is very straightforward to use in cases
+/// where it works.
+///
+/// ```rust
+/// use nom_parse_macros::parse_match;
+///
+/// #[parse_match("({},{},{})")]
+/// struct Vector3 {
+///     x: u32,
+///     y: u32,
+///     z: u32,
+/// }
+/// ```
+///
 #[proc_macro_attribute]
 pub fn parse_match(attrs: TokenStream, object: TokenStream) -> TokenStream {
     let literal = parse_macro_input! { attrs as LitStr };