chore: require docstrings in hugr-passes (#2391)

`missing_docs` is still allowed in `hugr-llvm`

https://github.com/CQCL/hugr/blob/7902ebcf47c427dc2fc9ed74f81b78254c0724b5/hugr-llvm/src/lib.rs#L64

Author: aborgna-q

hugr-passes/src/call_graph.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 //! Data structure for call graphs of a Hugr
 use std::collections::HashMap;
 

hugr-passes/src/composable.rs

@@ -9,11 +9,16 @@ use itertools::Either;
 /// An optimization pass that can be sequenced with another and/or wrapped
 /// e.g. by [`ValidatingPass`]
 pub trait ComposablePass<H: HugrMut>: Sized {
+    /// Error thrown by this pass.
     type Error: Error;
+    /// Result returned by this pass.
     type Result; // Would like to default to () but currently unstable
 
+    /// Run the pass on the given HUGR.
     fn run(&self, hugr: &mut H) -> Result<Self::Result, Self::Error>;
 
+    /// Apply a function to the error type of this pass, returning a new
+    /// [`ComposablePass`] that has the same result type.
     fn map_err<E2: Error>(
         self,
         f: impl Fn(Self::Error) -> E2,
@@ -52,7 +57,9 @@ pub trait ComposablePass<H: HugrMut>: Sized {
 /// Trait for combining the error types from two different passes
 /// into a single error.
 pub trait ErrorCombiner<A, B>: Error {
+    /// Create a combined error from the first pass's error.
     fn from_first(a: A) -> Self;
+    /// Create a combined error from the second pass's error.
     fn from_second(b: B) -> Self;
 }
 
@@ -113,18 +120,25 @@ pub enum ValidatePassError<N, E>
 where
     N: HugrNode + 'static,
 {
+    /// Validation failed on the initial HUGR.
     #[error("Failed to validate input HUGR: {err}\n{pretty_hugr}")]
     Input {
+        /// The validation error that occurred.
         #[source]
         err: ValidationError<N>,
+        /// A pretty-printed representation of the HUGR that failed validation.
         pretty_hugr: String,
     },
+    /// Validation failed on the final HUGR.
     #[error("Failed to validate output HUGR: {err}\n{pretty_hugr}")]
     Output {
+        /// The validation error that occurred.
         #[source]
         err: ValidationError<N>,
+        /// A pretty-printed representation of the HUGR that failed validation.
         pretty_hugr: String,
     },
+    /// An error from the underlying pass.
     #[error(transparent)]
     Underlying(#[from] E),
 }
@@ -134,6 +148,7 @@ where
 pub struct ValidatingPass<P, H>(P, PhantomData<H>);
 
 impl<P: ComposablePass<H>, H: HugrMut> ValidatingPass<P, H> {
+    /// Return a new [`ValidatingPass`] that wraps the given underlying pass.
     pub fn new(underlying: P) -> Self {
         Self(underlying, PhantomData)
     }

hugr-passes/src/const_fold.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 //! Constant-folding pass.
 //! An (example) use of the [dataflow analysis framework](super::dataflow).
 

hugr-passes/src/dataflow.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 //! Dataflow analysis of Hugrs.
 
 mod datalog;

hugr-passes/src/dead_funcs.rs

@@ -1,4 +1,3 @@
-#![warn(missing_docs)]
 //! Pass for removing statically-unreachable functions from a Hugr
 
 use std::collections::HashSet;

hugr-passes/src/lib.rs

@@ -1,5 +1,4 @@
 //! Compilation passes acting on the HUGR program representation.
-#![expect(missing_docs)] // TODO: Fix...
 
 pub mod call_graph;
 pub mod composable;

hugr-passes/src/lower.rs

@@ -1,3 +1,5 @@
+//! Passes to lower operations in a HUGR.
+
 use hugr_core::{
     Hugr, Node,
     hugr::{hugrmut::HugrMut, views::SiblingSubgraph},

hugr-passes/src/non_local.rs

@@ -1,6 +1,5 @@
 //! This module provides functions for finding non-local edges
 //! in a Hugr and converting them to local edges.
-#![warn(missing_docs)]
 use itertools::Itertools as _;
 
 use hugr_core::{

hugr-passes/src/replace_types.rs

@@ -1,5 +1,4 @@
 #![allow(clippy::type_complexity)]
-#![warn(missing_docs)]
 //! Replace types with other types across the Hugr. See [`ReplaceTypes`] and [Linearizer].
 //!
 use std::borrow::Cow;