docs: document deserialization modules and update lib module's doc (#…

…1334)

* Document Program deserialization modules

* Update lib.rs module documentation

* Update changelog

* Make deserialize utils private

* Update fuzzer's Cargo.lock

* Make take_until_unbalanced private

* Update docs

* Fix links

* Update changelog entry

---------

Co-authored-by: Pedro Fontana <fontana.pedro93@gmail.com>

CHANGELOG.md

@@ -2,9 +2,15 @@
 
 #### Upcoming Changes
 
-* perf: changed `ok_or` usage for `ok_or_else` in expensive cases [#1332](https://github.com/lambdaclass/cairo-vm/pull/1332)
+* docs: improved crate documentation [#1334](https://github.com/lambdaclass/cairo-vm/pull/1334)
+
+* chore!: made `deserialize_utils` module private [#1334](https://github.com/lambdaclass/cairo-vm/pull/1334)
+  BREAKING:
+  * `deserialize_utils` is no longer exported
+  * functions `maybe_add_padding`, `parse_value`, and `take_until_unbalanced` are no longer exported
+  * `ReferenceParseError` is no more
 
-* feat: add `arbitrary` feature to enable arbitrary derive in `Program` and `CairoRunConfig` [#1306](https://github.com/lambdaclass/cairo-vm/pull/1306)
+* perf: changed `ok_or` usage for `ok_or_else` in expensive cases [#1332](https://github.com/lambdaclass/cairo-vm/pull/1332)
 
 * feat: updated the old WASM example and moved it to [`examples/wasm-demo`](examples/wasm-demo/) [#1315](https://github.com/lambdaclass/cairo-vm/pull/1315)
 

vm/src/lib.rs

@@ -1,9 +1,14 @@
-//! An implementation of the Cairo virtual machine
+//! # An implementation of the Cairo virtual machine
 //!
-//! # Feature Flags
+//! ## Feature Flags
+//! - `std`: Enables usage of the [`std`] standard library. Enabled by default.
 //! - `skip_next_instruction_hint`: Enable the `skip_next_instruction()` hint. Not enabled by default.
-//! - `hooks`: Enable [Hooks](vm::hooks) support for the [VirtualMachine](vm::vm_core::VirtualMachine). Not enabled by default.
-//! - `with_mimalloc`: Use [MiMalloc](https://crates.io/crates/mimalloc) as the program global allocator.
+//! - `hooks`: Enable [`Hooks`](crate::vm::hooks::Hooks) support for the [VirtualMachine](vm::vm_core::VirtualMachine). Not enabled by default.
+//! - `test_utils`: Enables test utils (`hooks` and `skip_next_instruction` features). Not enabled by default.
+//! - `with_mimalloc`: Use [`MiMalloc`](https://crates.io/crates/mimalloc) as the program global allocator.
+//! - `cairo-1-hints`: Enable hints that were introduced in Cairo 1. Not enabled by default.
+//! - `arbitrary`: Enables implementations of [`arbitrary::Arbitrary`](https://docs.rs/arbitrary/latest/arbitrary/) for some structs. Not enabled by default.
+//! - `lambdaworks-felt`: Enables usage of the [**lambdaworks**](https://github.com/lambdaclass/lambdaworks) backend for [`felt::Felt252`]. Not enabled by default.
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
 #![deny(warnings)]

vm/src/serde/deserialize_program.rs

@@ -1,3 +1,11 @@
+//! # Program deserialization
+//!
+//! This module contains the logic for [`Program`] deserialization.
+//! Users shouldn't need to use it directly (except for [`BuiltinName`]).
+//!
+//! To generate a [`Program`] from a JSON string, see [`Program::from_bytes()`].
+//! To do the same from a JSON file, see [`Program::from_file()`].
+
 use crate::stdlib::{collections::HashMap, fmt, prelude::*, sync::Arc};
 
 use crate::vm::runners::builtin_runner::SEGMENT_ARENA_BUILTIN_NAME;

vm/src/serde/deserialize_utils.rs

@@ -1,10 +1,16 @@
-use crate::stdlib::{fmt, num::ParseIntError, prelude::*, str::FromStr};
-
+//! # Deserialization utils
+//!
+//! This module contains some helper functions used in [`Program`](crate::types::program::Program) deserialization.
+//! Namely, [`maybe_add_padding`] and [`parse_value`].
+//!
+//! See [the docs](/docs/references_parsing/README.md) for context and grammar explanation.
+
+use crate::stdlib::{prelude::*, str::FromStr};
 use crate::{
     serde::deserialize_program::{OffsetValue, ValueAddress},
     types::instruction::Register,
 };
-use felt::{Felt252, ParseFeltError};
+use felt::Felt252;
 use nom::{
     branch::alt,
     bytes::{
@@ -19,47 +25,19 @@ use nom::{
 };
 use num_integer::Integer;
 
-#[derive(Debug, PartialEq, Eq)]
-pub enum ReferenceParseError {
-    IntError(ParseIntError),
-    Felt252Error(ParseFeltError),
-    InvalidStringError(String),
-}
-
-impl fmt::Display for ReferenceParseError {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        match self {
-            ReferenceParseError::IntError(error) => {
-                write!(f, "Int parsing error: ")?;
-                error.fmt(f)
-            }
-            ReferenceParseError::Felt252Error(error) => {
-                write!(f, "Felt252 parsing error: ")?;
-                error.fmt(f)
-            }
-            ReferenceParseError::InvalidStringError(error) => {
-                write!(f, "Invalid reference string error: ")?;
-                error.fmt(f)
-            }
-        }
-    }
-}
-
 // Checks if the hex string has an odd length.
 // If that is the case, prepends '0' to it.
-pub fn maybe_add_padding(mut hex: String) -> String {
+pub(crate) fn maybe_add_padding(mut hex: String) -> String {
     if hex.len().is_odd() {
         hex.insert(0, '0');
         return hex;
     }
     hex
 }
 
-/*
-NOM PARSERS
-See the docs for context and grammar explanation:
-cleopatra_cairo/docs/references_parsing/README.md
-*/
+// -----------------------
+//       NOM PARSERS
+// -----------------------
 
 // Checks if the input has outer brackets. This is used to set
 // the `dereference` field of ValueAddress.
@@ -162,7 +140,7 @@ fn no_inner_dereference(input: &str) -> IResult<&str, OffsetValue> {
     Ok((rem_input, offset_value))
 }
 
-pub fn parse_value(input: &str) -> IResult<&str, ValueAddress> {
+pub(crate) fn parse_value(input: &str) -> IResult<&str, ValueAddress> {
     let (rem_input, (dereference, second_arg, fst_offset, snd_offset)) = tuple((
         outer_brackets,
         take_cast_first_arg,
@@ -216,10 +194,15 @@ pub fn parse_value(input: &str) -> IResult<&str, ValueAddress> {
 /// work inside the `nom::sequence::delimited()` parser.
 ///
 /// # Basic usage
-/// ```
+/// ```no_run
 /// use nom::bytes::complete::tag;
 /// use nom::sequence::delimited;
-/// use cairo_take_until_unbalanced::take_until_unbalanced;
+/// # use nom::IResult;
+///
+/// # fn take_until_unbalanced(
+/// #     opening_bracket: char,
+/// #     closing_bracket: char,
+/// # ) -> impl Fn(&str) -> IResult<&str, &str> { |_| Ok(("", "")) }
 ///
 /// let mut parser = delimited(tag("<"), take_until_unbalanced('<', '>'), tag(">"));
 /// assert_eq!(parser("<<inside>inside>abc"), Ok(("abc", "<inside>inside")));
@@ -229,7 +212,7 @@ pub fn parse_value(input: &str) -> IResult<&str, ValueAddress> {
 /// very similar to `nom::bytes::complete::take_until(">")`, except it also takes nested brackets.
 /// NOTE: trimmed down from https://docs.rs/parse-hyperlinks to fix bugs. The project itself seems
 /// abandonned.
-pub fn take_until_unbalanced(
+fn take_until_unbalanced(
     opening_bracket: char,
     closing_bracket: char,
 ) -> impl Fn(&str) -> IResult<&str, &str> {

vm/src/serde/mod.rs

@@ -1,2 +1,2 @@
 pub mod deserialize_program;
-pub mod deserialize_utils;
+mod deserialize_utils;

vm/src/vm/mod.rs

@@ -7,6 +7,6 @@ pub mod trace;
 pub mod vm_core;
 pub mod vm_memory;
 
-#[cfg(any(feature = "hooks"))]
+#[cfg(feature = "hooks")]
 #[cfg_attr(docsrs, doc(cfg(feature = "hooks")))]
 pub mod hooks;