Fix clippy::too-long-first-doc-paragraph

ext/crates/algebra/src/algebra/algebra_trait.rs

@@ -290,9 +290,11 @@ pub trait UnstableAlgebra: Algebra {
     }
 }
 
-/// An algebra that is maybe unstable. Every Algebra implements MuAlgebra<false> by ignoring the
-/// excess parameter, and every UnstableAlgebra implements MuAlgebra<true>. This makes it possible
-/// to write code that is generic over stable and unstable algebras.
+/// An algebra that is maybe unstable.
+///
+/// Every Algebra implements MuAlgebra<false> by ignoring the excess parameter, and every
+/// UnstableAlgebra implements MuAlgebra<true>. This makes it possible to write code that is generic
+/// over stable and unstable algebras.
 pub trait MuAlgebra<const U: bool>: Algebra {
     fn dimension_unstable(&self, degree: i32, excess: i32) -> usize;
 

ext/crates/algebra/src/algebra/milnor_algebra.rs

@@ -1205,9 +1205,11 @@ impl std::ops::IndexMut<usize> for Matrix2D {
     }
 }
 
-/// The parts of a PPartMultiplier that involve heap allocation. This lets us reuse the allocation
-/// across multiple different multipliers. Reusing the whole PPartMultiplier is finicky but doable
-/// due to lifetime issues, but it appears to be less performant.
+/// The parts of a PPartMultiplier that involve heap allocation.
+///
+/// This lets us reuse the allocation across multiple different multipliers. Reusing the whole
+/// PPartMultiplier is finicky but doable due to lifetime issues. However, it appears to be less
+/// performant.
 #[derive(Default)]
 pub struct PPartAllocation {
     m: Matrix2D,

ext/crates/algebra/src/algebra/pair_algebra.rs

@@ -1,7 +1,8 @@
 //! This implements the notion of a split pair algebra in the sense of
-//! <https://arxiv.org/abs/2105.07628>, whose notation we will use throughout. The Steenrod algebra
-//! admits a lift to a split pair algebra, which can be used to compute d2 differentials
-//! algorithmically.
+//! <https://arxiv.org/abs/2105.07628v1>, whose notation we will use throughout.
+//!
+//! The Steenrod algebra admits a lift to a split pair algebra, which can be used to compute d2
+//! differentials algorithmically.
 //!
 //! To keep the pair algebra business contained, we put the implementation of the Milnor algebra as
 //! a pair algebra in this file instead of `milnor_algebra.rs`.

ext/crates/algebra/src/module/block_structure.rs

@@ -10,12 +10,14 @@ pub struct GeneratorBasisEltPair {
     pub basis_index: usize,
 }
 
-/// A block structure is a structure that makes it efficient to convert between an index
-/// into a sum of vector spaces and an index into an individual one. For instance, a FreeModule
-/// has some collection of generators in various degrees and a general element is a homogenous sum
-/// \sum Op^i x_i. The basis for the FreeModule is divided into a block for each generator x_i.
-/// The entries in the block correspond to a basis for the algebra. In order to multiply by a steenrod operation,
-/// we have to pull out each block and multiply each block separately by the steenrod operation.
+/// A structure that makes it efficient to convert between an index into a sum of vector spaces and
+/// an index into an individual one.
+///
+/// For instance, a FreeModule has some collection of generators in various degrees and a general
+/// element is a homogenous sum \sum Op^i x_i. The basis for the FreeModule is divided into a block
+/// for each generator x_i. The entries in the block correspond to a basis for the algebra. In order
+/// to multiply by a steenrod operation, we have to pull out each block and multiply each block
+/// separately by the steenrod operation.
 #[derive(Debug)]
 pub struct BlockStructure {
     basis_element_to_block_idx: Vec<GeneratorBasisEltPair>,

ext/crates/algebra/src/module/hom_module.rs

@@ -10,8 +10,10 @@ use crate::{
 };
 
 /// Given a module N and a free module M, this is the module Hom(M, N) as a module over the ground
-/// field. This requires N to be bounded, and is graded *opposite* to the usual grading so that
-/// Hom(M, N) is bounded below.
+/// field.
+///
+/// This requires N to be bounded, and is graded *opposite* to the usual grading so that Hom(M, N)
+/// is bounded below.
 pub struct HomModule<M: Module> {
     algebra: Arc<Field>,
     source: Arc<FreeModule<M::Algebra>>,

ext/crates/algebra/src/module/homomorphism/mod.rs

@@ -28,9 +28,11 @@ pub use hom_pullback::HomPullback;
 use maybe_rayon::prelude::*;
 pub use quotient_homomorphism::{QuotientHomomorphism, QuotientHomomorphismSource};
 
+/// A trait that represents a homomorphism between two modules.
+///
 /// Each `ModuleHomomorphism` may come with auxiliary data, namely the kernel, image and
-/// quasi_inverse at each degree (the quasi-inverse is a map that is a right inverse when
-/// restricted to the image). These are computed via
+/// quasi_inverse at each degree (the quasi-inverse is a map that is a right inverse when restricted
+/// to the image). These are computed via
 /// [`ModuleHomomorphism::compute_auxiliary_data_through_degree`] and retrieved through
 /// [`ModuleHomomorphism::kernel`], [`ModuleHomomorphism::quasi_inverse`] and
 /// [`ModuleHomomorphism::image`].

ext/crates/algebra/src/module/module_trait.rs

@@ -9,9 +9,11 @@ use itertools::Itertools;
 
 use crate::algebra::Algebra;
 
-/// A bounded below module over an algebra. To accommodate for infinite modules (e.g. modules in a
-/// free resolution), every module is potentially only define up to a degree. The extent to which
-/// the module is defined is kept track by two functions:
+/// A bounded below module over an algebra.
+///
+/// To accommodate for infinite modules (e.g. modules in a free resolution), every module is
+/// potentially only define up to a degree. The extent to which the module is defined is kept track
+/// by two functions:
 ///
 ///  - [`Module::max_computed_degree`] gives the maximum degree for which the module is fully
 ///    defined. It is guaranteed that the module will never change up to this degree in the future.

ext/crates/fp/src/field/element.rs

@@ -12,11 +12,13 @@ pub trait FieldElementContainer:
 {
 }
 
-/// An element of a field. This contains the field itself so that it knows how to do arithmetic
-/// operations. We want this to be a _struct_ rather than a trait, which means that we want the
-/// _actual_ storage of the value to be managed by the field itself. Therefore, we have an internal
-/// field trait that knows about arithmetic operations and other implementation details, but these
-/// operations are only accessible from outside the crate using this struct.
+/// An element of a field.
+///
+/// This contains the field itself so that it knows how to do arithmetic operations. We want this to
+/// be a _struct_ rather than a trait, which means that we want the _actual_ storage of the value to
+/// be managed by the field itself. Therefore, we have an internal field trait that knows about
+/// arithmetic operations and other implementation details, but these operations are only accessible
+/// from outside the crate using this struct.
 ///
 /// It might seem wasteful to handle, say, `FieldElement<Fp<P>>`s rather than `u32` in the API for
 /// `FqVector<Fp<P>>`. However, this gives us type-level guarantees that the invariants of the

ext/crates/fp/src/matrix/matrix_inner.rs

@@ -14,9 +14,11 @@ use crate::{
     vector::{FpSlice, FpSliceMut, FpVector},
 };
 
-/// A matrix! In particular, a matrix with values in F_p. The way we store matrices means it is
-/// easier to perform row operations than column operations, and the way we use matrices means we
-/// want our matrices to act on the right. Hence we think of vectors as row vectors.
+/// A matrix! In particular, a matrix with values in F_p.
+///
+/// The way we store matrices means it is easier to perform row operations than column operations,
+/// and the way we use matrices means we want our matrices to act on the right. Hence we think of
+/// vectors as row vectors.
 #[derive(Clone)]
 pub struct Matrix {
     p: ValidPrime,

ext/crates/fp/src/vector/inner.rs

@@ -3,7 +3,7 @@
 
 use crate::{field::Field, limb::Limb};
 
-/// An `FqVector` is a vector over a finite field.
+/// A vector over a finite field.
 ///
 /// Interally, it packs entries of the vectors into limbs. However, this is an abstraction that must
 /// not leave the `fp` library.
@@ -14,8 +14,9 @@ pub struct FqVector<F: Field> {
     pub(super) limbs: Vec<Limb>,
 }
 
-/// An `FqSlice` is a slice of an `FqVector`. This immutably borrows the vector and implements
-/// `Copy`
+/// A slice of an `FqVector`.
+///
+/// This immutably borrows the vector and implements `Copy`.
 #[derive(Debug, Copy, Clone)]
 pub struct FqSlice<'a, F: Field> {
     pub(super) fq: F,
@@ -24,10 +25,11 @@ pub struct FqSlice<'a, F: Field> {
     pub(super) end: usize,
 }
 
-/// An `FqSliceMut` is a mutable slice of an `FqVector`. This mutably borrows the vector. Since it
-/// is a mutable borrow, it cannot implement `Copy`. However, it has a [`FqSliceMut::copy`] function
-/// that imitates the reborrowing, that mutably borrows `FqSliceMut` and returns a `FqSliceMut` with
-/// a shorter lifetime.
+/// A mutable slice of an `FqVector`.
+///
+/// This mutably borrows the vector. Since it is a mutable borrow, it cannot implement `Copy`.
+/// However, it has a [`FqSliceMut::copy`] function that imitates the reborrowing, that mutably
+/// borrows `FqSliceMut` and returns a `FqSliceMut` with a shorter lifetime.
 #[derive(Debug)]
 pub struct FqSliceMut<'a, F: Field> {
     pub(super) fq: F,

ext/crates/sseq/src/coordinates/mod.rs

@@ -9,6 +9,8 @@ pub use generator::BidegreeGenerator;
 use maybe_rayon::prelude::*;
 pub use range::BidegreeRange;
 
+/// Execute a function on a range of bidegrees, possibly in parallel.
+///
 /// Given a function `f(s, t)`, compute it for every `s` in `[min_s, max_s]` and every `t` in
 /// `[min_t, max_t(s)]`.  Further, we only compute `f(s, t)` when `f(s - 1, t')` has been computed
 /// for all `t' < t`.

ext/src/nassau.rs

@@ -1,16 +1,16 @@
-//! This module implements [Nassau's algorithm](https://arxiv.org/abs/1910.04063). The main export
-//! is the [`Resolution`] object, which is a resolution of the sphere at the prime 2 using Nassau's
-//! algorithm. It aims to provide an API similar to
+//! This module implements [Nassau's algorithm](https://arxiv.org/abs/1910.04063).
+//!
+//! The main export is the [`Resolution`] object, which is a resolution of the sphere at the prime 2
+//! using Nassau's algorithm. It aims to provide an API similar to
 //! [`resolution::Resolution`](crate::resolution::Resolution). From an API point of view, the main
 //! difference between the two is that our `Resolution` is a chain complex over [`MilnorAlgebra`]
 //! over [`SteenrodAlgebra`](algebra::SteenrodAlgebra).
 //!
 //! To make use of this resolution in the example scripts, enable the `nassau` feature. This will
 //! cause [`utils::query_module`](crate::utils::query_module) to return the `Resolution` from this
 //! module instead of [`resolution`](crate::resolution). There is no formal polymorphism involved;
-//! the feature changes the return type of the function. While this is an incorrect use of
-//! features, we find that this the easiest way to make all scripts support both types of
-//! resolutions.
+//! the feature changes the return type of the function. While this is an incorrect use of features,
+//! we find that this the easiest way to make all scripts support both types of resolutions.
 
 use std::{
     fmt::Display,
@@ -382,10 +382,12 @@ enum Magic {
     Fix = -3,
 }
 
-/// A resolution of `S_2` using Nassau's algorithm. This aims to have an API similar to that of
+/// A resolution of `S_2` using Nassau's algorithm.
+///
+/// This aims to have an API similar to that of
 /// [`resolution::Resolution`](crate::resolution::Resolution). From an API point of view, the main
-/// difference between the two is that this is a chain complex over [`MilnorAlgebra`]
-/// over [`SteenrodAlgebra`](algebra::SteenrodAlgebra).
+/// difference between the two is that this is a chain complex over [`MilnorAlgebra`] over
+/// [`SteenrodAlgebra`](algebra::SteenrodAlgebra).
 pub struct Resolution<M: ZeroModule<Algebra = MilnorAlgebra>> {
     lock: Mutex<()>,
     name: String,

ext/src/secondary.rs

@@ -330,6 +330,8 @@ impl<A: PairAlgebra + Send + Sync> SecondaryHomotopy<A> {
     }
 }
 
+/// Logic that is common to all secondary lifts.
+///
 /// When lifting a thing to its secondary version, often what we have to do is to specify an
 /// explicit homotopy to witnesses that some equation holds. For example, to lift a chain complex,
 /// we need a homotopy witnessing the fact that $d^2 \simeq 0$. This homotopy in turn is required

ext/src/utils.rs

@@ -269,6 +269,8 @@ where
     crate::resolution::MuResolution::new_with_save(chain_complex, save_dir)
 }
 
+/// Load a module specification from a JSON file.
+///
 /// Given the name of a module file (without the `.json` extension), find a json file with this
 /// name, and return the parsed json object. The search path for this json file is described
 /// [here](../index.html#module-specification).
@@ -369,9 +371,11 @@ pub fn query_module_only(
 }
 
 /// Query the user for a module and a bidegree, and return a resolution resolved up to said
-/// bidegree. This is mainly a wrapper around [`query_module_only`] that also asks for the bidegree
-/// to resolve up to as well. The prompt of [`query_module_only`] is always set to `"Module"` when
-/// invoked through this function.
+/// bidegree.
+///
+/// This is mainly a wrapper around [`query_module_only`] that also asks for the bidegree to resolve
+/// up to as well. The prompt of [`query_module_only`] is always set to `"Module"` when invoked
+/// through this function.
 pub fn query_module(
     algebra: Option<AlgebraType>,
     load_quasi_inverse: bool,
@@ -420,9 +424,10 @@ pub fn query_unstable_module(load_quasi_inverse: bool) -> anyhow::Result<Unstabl
     Ok(resolution)
 }
 
-/// Given a resolution, return a resolution of the unit, together with a boolean indicating whether
-/// this is the original resolution was already a resolution of the unit. If the boolean is true,
-/// then the original resolution is returned.
+/// Given a resolution, return a resolution of the unit.
+///
+/// The return value comes with a boolean indicating whether the original resolution was already a
+/// resolution of the unit. If the boolean is true, then the original resolution is returned.
 pub fn get_unit(
     resolution: Arc<QueryModuleResolution>,
 ) -> anyhow::Result<(bool, Arc<QueryModuleResolution>)> {
@@ -541,10 +546,12 @@ mod logging {
 
 pub use logging::{ext_tracing_subscriber, init_logging, LogWriter};
 
-/// The value of the SECONDARY_JOB environment variable. This is used for distributing the
-/// `secondary`. If set, only data with `s = SECONDARY_JOB` will be computed. The minimum value of
-/// `s` is the `shift_s` of the [`SecondaryLift`](crate::secondary::SecondaryLift) and the maximum
-/// value (inclusive) is the maximum `s` of the resolution.
+/// The value of the SECONDARY_JOB environment variable.
+///
+/// This is used for distributing the `secondary`. If set, only data with `s = SECONDARY_JOB` will
+/// be computed. The minimum value of `s` is the `shift_s` of the
+/// [`SecondaryLift`](crate::secondary::SecondaryLift) and the maximum value (inclusive) is the
+/// maximum `s` of the resolution.
 pub fn secondary_job() -> Option<u32> {
     let val = std::env::var("SECONDARY_JOB").ok()?;
     let parsed: Option<u32> = str::parse(&val).ok();

web_ext/sseq_gui/src/main.rs

@@ -40,10 +40,12 @@ fn print_time(time: OffsetDateTime) -> String {
     format!("{}:{}:{}", time.hour(), time.minute(), time.hour())
 }
 
+/// A struct that dispatches messages to ResolutionManager and SseqManager.
+///
 /// The reason the code is structured this way is that messages sent to the WebSocket are blocked
-/// until `on_message` returned. Hence we start the ResolutionManager on a separate thread, and
-/// when we receive a message, we can let ResolutionManager handle it asynchronously and let
-/// `on_message` return as soon as possible.
+/// until `on_message` returned. Hence we start the ResolutionManager on a separate thread, and when
+/// we receive a message, we can let ResolutionManager handle it asynchronously and let `on_message`
+/// return as soon as possible.
 ///
 /// We also spawn a separate thread waiting for messages from ResolutionManager, and then relay it
 /// to the WebSocket, again, we do this because we don't want anything to be blocking.
@@ -182,7 +184,9 @@ impl Manager {
     }
 }
 
-/// The server implements the `ws::Handler` trait. It doesn't really do much. When we receive a
+/// A simple WebSocket server that serves static files and passes messages to [`Manager`].
+///
+/// The server implements the [`ws::Handler`] trait. It doesn't really do much. When we receive a
 /// request, it is either looking for some static files, as specified in `FILE_LIST`, or it is
 /// WebSocket message. If it is the former, we return the file. If it is the latter, we parse it
 /// into a string and pass it on to Manager.

web_ext/sseq_gui/src/managers.rs

@@ -10,9 +10,10 @@ use sseq::coordinates::Bidegree;
 
 use crate::{actions::*, resolution_wrapper::Resolution, sseq::SseqWrapper, Sender};
 
-/// ResolutionManager is a struct that manipulates a Resolution. It is constructed with a "sender"
-/// which is used to relay the results of the computation. This sender should send all messages to
-/// SseqManager.
+/// A struct that manipulates a Resolution.
+///
+/// It is constructed with a "sender" which is used to relay the results of the computation. This
+/// sender should send all messages to SseqManager.
 ///
 /// # Fields
 ///  * `sender` : A Sender object.