docs(fzn-rs): Comments and naming of types

Author: maartenflippo

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["./pumpkin-solver", "./drcp-format", "./pumpkin-solver-py", "./pumpkin-macros", "./drcp-debugger", "./pumpkin-crates/*", "./fzn_rs", "./fzn_rs_derive"]
+members = ["./pumpkin-solver", "./drcp-format", "./pumpkin-solver-py", "./pumpkin-macros", "./drcp-debugger", "./pumpkin-crates/*", "./fzn-rs", "./fzn-rs-derive"]
 default-members = ["./pumpkin-solver", "./drcp-format", "./pumpkin-solver-py", "./pumpkin-macros", "./pumpkin-crates/*"]
 resolver = "2"
 

fzn-rs/src/lib.rs

@@ -1,43 +1,17 @@
 //! # fzn-rs
 //!
-//! `fzn-rs` is a crate that allows for easy parsing of FlatZinc instances in Rust.
-//!
-//! ## Comparison to other FlatZinc crates
-//! There are two well-known crates for parsing FlatZinc files:
-//! - [flatzinc](https://docs.rs/flatzinc), for parsing the original `fzn` format,
-//! - and [flatzinc-serde](https://docs.rs/flatzinc-serde), for parsing `fzn.json`.
-//!
-//! The goal of this crate is to be able to parse both the original `fzn` format, as well as the
-//! newer `fzn.json` format. Additionally, there is a derive macro that allows for strongly-typed
-//! constraints as they are supported by your application. Finally, our aim is to improve the error
-//! messages that are encountered when parsing invalid FlatZinc files.
-//!
-//! ## Typed Instance
-//! The main type exposed by the crate is [`TypedInstance`], which is a fully typed representation
-//! of a FlatZinc model.
+//! `fzn-rs` is a crate that allows for easy parsing of FlatZinc instances in Rust. It facilitates
+//! type-driven parsing of a FlatZinc file using derive macros.
 //!
+//! ## Example
 //! ```
-//! use fzn_rs::TypedInstance;
-//!
-//! enum Constraints {
-//!     // ...
-//! }
-//!
-//! type Instance = TypedInstance<i32, Constraints>;
-//! ```
-//!
-//! ## Derive Macro
-//! When parsing a FlatZinc file, the result is an [`ast::Ast`]. That type describes any valid
-//! FlatZinc file. However, when consuming FlatZinc, typically you need to process that AST
-//! further. For example, to support the [`int_lin_le`][1] constraint, you have to validate that the
-//! [`ast::Constraint`] has three arguments, and that each of the arguments has the correct type.
-//!
-//! When using this crate with the `derive` feature, you can instead do the following:
-//! ```rust
 //! use fzn_rs::ArrayExpr;
 //! use fzn_rs::FlatZincConstraint;
+//! use fzn_rs::TypedInstance;
 //! use fzn_rs::VariableExpr;
 //!
+//! /// The FlatZincConstraint derive macro enables the parsing of a strongly typed constraint
+//! /// based on the FlatZinc Ast.
 //! #[derive(FlatZincConstraint)]
 //! pub enum MyConstraints {
 //!     /// The variant name is converted to snake_case to serve as the constraint identifier by
@@ -69,9 +43,27 @@
 //!     b: VariableExpr<i64>,
 //!     c: VariableExpr<i64>,
 //! }
+//!
+//! /// The `TypedInstance` is parameterized by the constraint type, as well as any annotations you
+//! /// may need to parse.
+//! type MyInstance = TypedInstance<i64, MyConstraints>;
+//!
+//! fn parse_flatzinc(source: &str) -> MyInstance {
+//!     // First, the source string is parsed into a structured representation.
+//!     //
+//!     // Note: the `fzn_rs::fzn` module is only available with the `fzn` feature enabled.
+//!     let ast = fzn_rs::fzn::parse(source).expect("source is valid flatzinc");
+//!
+//!     // Then, the strongly-typed instance is created from the AST
+//!     MyInstance::from_ast(ast).expect("type-checking passes")
+//! }
 //! ```
-//! The macro automatically implements [`FlatZincConstraint`] and will handle the parsing
-//! of arguments for you.
+//!
+//! ## Derive Macros
+//! When parsing a FlatZinc file, the result is an [`ast::Ast`]. That type describes any valid
+//! FlatZinc file. However, when consuming FlatZinc, typically you need to process that AST
+//! further. For example, to support the [`int_lin_le`][1] constraint, you have to validate that the
+//! [`ast::Constraint`] has three arguments, and that each of the arguments has the correct type.
 //!
 //! Similar to typed constraints, the derive macro for [`FlatZincAnnotation`] allows for easy
 //! parsing of annotations:
@@ -101,6 +93,16 @@
 //! annotation whose name does not match one of the variants in the enum, then the annotation is
 //! simply ignored.
 //!
+//! ## Comparison to other FlatZinc crates
+//! There are two well-known crates for parsing FlatZinc files:
+//! - [flatzinc](https://docs.rs/flatzinc), for parsing the original `fzn` format,
+//! - and [flatzinc-serde](https://docs.rs/flatzinc-serde), for parsing `fzn.json`.
+//!
+//! These crates produce what we call the [`ast::Ast`] in this crate, although the concrete types
+//! can be different. `fzn-rs` builds the strong typing of constraints and annotations on-top of
+//! a unified AST for both file formats. Finally, our aim is to improve the error messages that
+//! are encountered when parsing invalid FlatZinc files.
+//!
 //! [1]: https://docs.minizinc.dev/en/stable/lib-flatzinc-int.html#int-lin-le
 
 mod error;

fzn-rs/src/typed/instance.rs

@@ -38,14 +38,14 @@ pub struct TypedInstance<
     pub constraints: Vec<AnnotatedConstraint<Constraint, ConstraintAnnotations>>,
 
     /// The solve item indicating how to solve the model.
-    pub solve: Solve<Int, SolveAnnotations>,
+    pub solve: SolveItem<Int, SolveAnnotations>,
 }
 
 /// Specifies how to solve a [`TypedInstance`].
 ///
 /// This is generic over the integer type.
 #[derive(Clone, Debug, PartialEq, Eq)]
-pub struct Solve<Int, Ann> {
+pub struct SolveItem<Int, Ann> {
     pub method: ast::Node<Method<Int>>,
     pub annotations: Vec<ast::Node<Ann>>,
 }
@@ -95,9 +95,6 @@ where
     ///
     /// This parses the constraints and annotations, and can fail e.g. if the number or type of
     /// arguments do not match what is expected in the parser.
-    ///
-    /// This does _not_ type-check the variables. I.e., if a constraint takes a `var int`, but
-    /// is provided with an identifier of a `var bool`, then this function will gladly accept that.
     pub fn from_ast(ast: ast::Ast) -> Result<Self, InstanceError> {
         let variables = ast
             .variables
@@ -145,7 +142,7 @@ where
             })
             .collect::<Result<_, _>>()?;
 
-        let solve = Solve {
+        let solve = SolveItem {
             method: match ast.solve.method.node {
                 ast::Method::Satisfy => ast::Node {
                     node: Method::Satisfy,