Fix and check documentation

.github/workflows/rust.yml

@@ -32,6 +32,26 @@ jobs:
     - name: Check code formatting
       run: cargo fmt --verbose --all -- --check
 
+  doc:
+    name: Documentation
+    runs-on: ubuntu-latest
+    env:
+      RUSTDOCFLAGS: -D warnings
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions-rust-lang/setup-rust-toolchain@v1
+      with:
+        toolchain: stable
+    - name: Print versions
+      run: |
+        cargo --version
+        rustc --version
+        rustdoc --version
+    - name: Doc
+      run: cargo doc --verbose
+    - name: Doc with all features
+      run: cargo doc --verbose --all-features
+
   miri-test:
     name: Test with miri
     runs-on: ubuntu-latest

engine/src/ast/function_expr.rs

@@ -24,18 +24,17 @@ use serde::Serialize;
 use std::hash::{Hash, Hasher};
 use std::iter::once;
 
-/// FunctionCallArgExpr is a function argument. It can be a sub-expression with
-/// [`LogicalExpr`], a field with [`IndexExpr`] or a literal with [`Literal`].
+/// Represents a function argument in a function call.
 #[derive(Debug, PartialEq, Eq, Clone, Hash, Serialize)]
 #[serde(tag = "kind", content = "value")]
 pub enum FunctionCallArgExpr<'s> {
-    /// IndexExpr is a field that supports the indexing operator.
+    /// A sub-expression which evaluates to a value.
     IndexExpr(IndexExpr<'s>),
-    /// A Literal.
+    /// A literal value.
     Literal(RhsValue),
-    /// LogicalExpr is a sub-expression which can evaluate to either true/false
-    /// or a list of true/false. It compiles to a CompiledExpr and is coerced
-    /// into a CompiledValueExpr.
+    /// A sub-expression which evaluates to either `true`/`false`
+    /// or a list of `true`/`false`. It compiles to a [`CompiledExpr`]
+    /// and is coerced into a [`CompiledValueExpr`]`.
     // Renaming is necessary for backward compability.
     #[serde(rename = "SimpleExpr")]
     Logical(LogicalExpr<'s>),

engine/src/ast/index_expr.rs

@@ -18,10 +18,10 @@ use serde::{ser::SerializeSeq, Serialize, Serializer};
 
 /// IndexExpr is an expr that destructures an index into an IdentifierExpr.
 ///
-/// For example, given a scheme which declares a field, http.request.headers,
+/// For example, given a scheme which declares a field `http.request.headers`,
 /// as a map of string to list of strings, then the expression
-/// http.request.headers["Cookie"][0] would have an IdentifierExpr
-/// http.request.headers and indexes ["Cookie", 0].
+/// `http.request.headers["Cookie"][0]` would have an IdentifierExpr
+/// of `http.request.headers` and indexes `["Cookie", 0]`.
 #[derive(Debug, PartialEq, Eq, Clone, Hash)]
 pub struct IndexExpr<'s> {
     /// The accessed identifier.

engine/src/ast/mod.rs

@@ -39,7 +39,7 @@ pub trait Expr<'s>:
     }
 }
 
-/// Trait used to represent node that evaluates to an [`LhsValue`].
+/// Trait used to represent node that evaluates to an [`crate::LhsValue`].
 pub trait ValueExpr<'s>:
     Sized + Eq + Debug + for<'i, 'p> LexWith<'i, &'p FilterParser<'s>> + Serialize
 {
@@ -63,7 +63,7 @@ pub trait ValueExpr<'s>:
 ///
 /// It's attached to its corresponding [`Scheme`](struct@Scheme) because all
 /// parsed fields are represented as indices and are valid only when
-/// [`ExecutionContext`](::ExecutionContext) is created from the same scheme.
+/// [`crate::ExecutionContext`] is created from the same scheme.
 #[derive(PartialEq, Eq, Serialize, Clone, Hash)]
 #[serde(transparent)]
 pub struct FilterAst<'s> {
@@ -176,7 +176,7 @@ impl<'s> FilterAst<'s> {
 ///
 /// It's attached to its corresponding [`Scheme`](struct@Scheme) because all
 /// parsed fields are represented as indices and are valid only when
-/// [`ExecutionContext`](::ExecutionContext) is created from the same scheme.
+/// [`crate::ExecutionContext`] is created from the same scheme.
 #[derive(PartialEq, Eq, Serialize, Clone, Hash)]
 #[serde(transparent)]
 pub struct FilterValueAst<'s> {

engine/src/compiler.rs

@@ -3,9 +3,9 @@ use crate::{
     IndexExpr, LogicalExpr, ValueExpr,
 };
 
-/// Trait used to drive the compilation of a [`FilterAst`] into a [`Filter`].
+/// Trait used to drive the compilation of a [`crate::FilterAst`] into a [`crate::Filter`].
 pub trait Compiler<'s>: Sized + 's {
-    /// The user data type passed in the  [`ExecutionContext`].
+    /// The user data type passed in the  [`crate::ExecutionContext`].
     type U;
 
     /// Compiles a [`Expr`] node into a [`CompiledExpr`] (boxed closure).

engine/src/execution_context.rs

@@ -11,7 +11,7 @@ use std::fmt;
 use std::fmt::Debug;
 use thiserror::Error;
 
-/// An error that occurs when setting the field value in the [`ExecutionContext`](struct@ExecutionContext)
+/// An error that occurs when setting the field value in the [`crate::ExecutionContext`].
 #[derive(Debug, PartialEq, Eq, Error)]
 pub enum SetFieldValueError {
     /// An error that occurs when trying to assign a value of the wrong type to a field.
@@ -31,8 +31,8 @@ pub struct InvalidListMatcherError {
     list: String,
 }
 
-/// An execution context stores an associated [`Scheme`](struct@Scheme) and a
-/// set of runtime values to execute [`Filter`](::Filter) against.
+/// An execution context stores an associated [`struct@crate::Scheme`] and a
+/// set of runtime values to execute [`crate::Filter`] against.
 ///
 /// It acts as a map in terms of public API, but provides a constant-time
 /// index-based access to values for a filter during execution.

engine/src/filter.rs

@@ -16,7 +16,7 @@ use std::fmt;
 type BoxedClosureToOneBool<'s, U> =
     Box<dyn for<'e> Fn(&'e ExecutionContext<'e, U>) -> bool + Sync + Send + 's>;
 
-/// Boxed closure for [`Expr`] AST node that evaluates to a simple [`bool`].
+/// Boxed closure for [`crate::Expr`] AST node that evaluates to a simple [`bool`].
 pub struct CompiledOneExpr<'s, U = ()>(BoxedClosureToOneBool<'s, U>);
 
 impl<'s, U> fmt::Debug for CompiledOneExpr<'s, U> {
@@ -51,7 +51,7 @@ pub(crate) type CompiledVecExprResult = TypedArray<'static, bool>;
 type BoxedClosureToVecBool<'s, U> =
     Box<dyn for<'e> Fn(&'e ExecutionContext<'e, U>) -> CompiledVecExprResult + Sync + Send + 's>;
 
-/// Boxed closure for [`Expr`] AST node that evaluates to a list of [`bool`].
+/// Boxed closure for [`crate::Expr`] AST node that evaluates to a list of [`bool`].
 pub struct CompiledVecExpr<'s, U = ()>(BoxedClosureToVecBool<'s, U>);
 
 impl<'s, U> fmt::Debug for CompiledVecExpr<'s, U> {
@@ -84,12 +84,12 @@ impl<'s, U> CompiledVecExpr<'s, U> {
     }
 }
 
-/// Enum of boxed closure for [`Expr`] AST nodes.
+/// Enum of boxed closure for [`crate::Expr`] AST nodes.
 #[derive(Debug)]
 pub enum CompiledExpr<'s, U = ()> {
-    /// Variant for [`Expr`] AST node that evaluates to a simple [`bool`].
+    /// Variant for [`crate::Expr`] AST node that evaluates to a simple [`bool`].
     One(CompiledOneExpr<'s, U>),
-    /// Variant for [`Expr`] AST node that evaluates to a list of [`bool`].
+    /// Variant for [`crate::Expr`] AST node that evaluates to a list of [`bool`].
     Vec(CompiledVecExpr<'s, U>),
 }
 
@@ -131,7 +131,7 @@ impl<'a> From<Type> for CompiledValueResult<'a> {
 type BoxedClosureToValue<'s, U> =
     Box<dyn for<'e> Fn(&'e ExecutionContext<'e, U>) -> CompiledValueResult<'e> + Sync + Send + 's>;
 
-/// Boxed closure for [`ValueExpr`] AST node that evaluates to an [`LhsValue`].
+/// Boxed closure for [`crate::ValueExpr`] AST node that evaluates to an [`LhsValue`].
 pub struct CompiledValueExpr<'s, U = ()>(BoxedClosureToValue<'s, U>);
 
 impl<'s, U> fmt::Debug for CompiledValueExpr<'s, U> {

engine/src/scheme.rs

@@ -367,7 +367,7 @@ type IdentifierName = Arc<str>;
 /// The main registry for fields and their associated types.
 ///
 /// This is necessary to provide typechecking for runtime values provided
-/// to the [execution context](::ExecutionContext) and also to aid parser
+/// to the [`crate::ExecutionContext`] and also to aid parser
 /// in ambiguous contexts.
 #[derive(Default, Debug)]
 pub struct Scheme {
@@ -428,7 +428,7 @@ impl<'s> Scheme {
         Default::default()
     }
 
-    /// Returns the [`identifier`](struct@Identifier) with name [`name`]
+    /// Returns the [`identifier`](enum@Identifier) with the specified `name`.
     pub fn get(&'s self, name: &str) -> Option<Identifier<'s>> {
         self.items.get(name).map(move |item| match *item {
             SchemeItem::Field(index) => Identifier::Field(Field {
@@ -466,15 +466,15 @@ impl<'s> Scheme {
         }
     }
 
-    /// Returns the [`field`](struct@Field) with name [`name`]
+    /// Returns the [`field`](struct@Field) with the specified `name`.
     pub fn get_field(&'s self, name: &str) -> Result<Field<'s>, UnknownFieldError> {
         match self.get(name) {
             Some(Identifier::Field(f)) => Ok(f),
             _ => Err(UnknownFieldError),
         }
     }
 
-    /// Iterates over fields registered in the [`scheme`](struct@Scheme)
+    /// Iterates over fields registered in the [`scheme`](struct@Scheme).
     #[inline]
     pub fn fields(&'s self) -> impl ExactSizeIterator<Item = Field<'s>> + 's {
         (0..self.fields.len()).map(|index| Field {
@@ -483,13 +483,13 @@ impl<'s> Scheme {
         })
     }
 
-    /// Returns the number of fields in the [`scheme`](struct@Scheme)
+    /// Returns the number of fields in the [`scheme`](struct@Scheme).
     #[inline]
     pub fn field_count(&self) -> usize {
         self.fields.len()
     }
 
-    /// Returns the number of functions in the [`scheme`](struct@Scheme)
+    /// Returns the number of functions in the [`scheme`](struct@Scheme).
     #[inline]
     pub fn function_count(&self) -> usize {
         self.functions.len()
@@ -519,15 +519,15 @@ impl<'s> Scheme {
         }
     }
 
-    /// Returns the [`function`](struct@Function) with name [`name`]
+    /// Returns the [`function`](struct@Function) with the specified `name`.
     pub fn get_function(&'s self, name: &str) -> Result<Function<'s>, UnknownFunctionError> {
         match self.get(name) {
             Some(Identifier::Function(f)) => Ok(f),
             _ => Err(UnknownFunctionError),
         }
     }
 
-    /// Iterates over functions registered in the [`scheme`](struct@Scheme)
+    /// Iterates over functions registered in the [`scheme`](struct@Scheme).
     #[inline]
     pub fn functions(&'s self) -> impl ExactSizeIterator<Item = Function<'s>> + 's {
         (0..self.functions.len()).map(|index| Function {

engine/src/types.rs

@@ -201,9 +201,8 @@ macro_rules! declare_types {
         declare_types! {
             /// An LHS value provided for filter execution.
             ///
-            /// These are passed to the [execution context](::ExecutionContext)
-            /// and are used by [filters](::Filter)
-            /// for execution and comparisons.
+            /// These are passed to the [`crate::ExecutionContext`]
+            /// and are used by [`crate::Filter`] for execution and comparisons.
             #[derive(PartialEq, Eq, Clone, Deserialize, Hash)]
             #[serde(untagged)]
             enum LhsValue<'a> {

ffi/src/transfer_types/raw_ptr_repr/mod.rs

@@ -10,7 +10,7 @@ pub use self::{
 /// with corresponding conversions.
 ///
 /// Later this trait can be used by higher-level wrappers like
-/// [`::transfer_types::RustBox`] and [`::transfer_types::Ref`] to add required
+/// [`crate::transfer_types::RustBox`] and [`crate::transfer_types::Ref`] to add required
 /// ownership semantics while preserving FFI compatibility.
 pub trait ExternPtrRepr {
     type Repr: Copy + From<*const Self>;