Update docs

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

@@ -1146,7 +1146,7 @@ impl<'a> MatrixSliceMut<'a> {
         }
     }
 
-    /// For each row, add the v[i]th entry of `other` to `self`.
+    /// For each row, add the `v[i]`th entry of `other` to `self`.
     pub fn add_masked(&mut self, other: &Matrix, mask: &[usize]) {
         assert_eq!(self.rows(), other.rows());
 

ext/examples/resolve_through_stem.rs

@@ -1,4 +1,4 @@
-//! Resolves a module up to a $(s, n)$ and prints an ASCII depiction of the Ext groups:
+//! Resolves a module up to an $(n, s)$ and prints an ASCII depiction of the Ext groups:
 //! ```text
 //! ·
 //! ·                                                     ·

ext/examples/secondary.rs

@@ -1,17 +1,12 @@
 //! This computes $d_2$ differentials in the Adams spectral sequence. This only works for fairly
 //! specific modules, but tends to cover most cases of interest.
 //!
-//! In general, the set of possible $d_2$'s is a torsor over $\Ext^{2, 1}(M, M)$; the
-//! action of $\chi \in \Ext^{2, 1}(M, M)$ is given by adding $\chi$-multiplication
-//! to the $d_2$ map. This algorithm computes one possible set of $d_2$'s. If $\Ext^{2, 1}(M, M)$
-//! is non-zero, some differentials will have to be calculated by hand to determine the actual set
-//! of $d_2$'s.
-//!
 //! # Usage
-//! This asks for a module in the usual way. It only works with the Milnor basis,
+//! This asks for a module in the usual way, and verifies that the module satisfies the conditions
+//! necessary for the algorithm the work. It only works with the Milnor basis.
 //!
 //! # Output
-//! We omit differentials if the target bidegree is zero
+//! We omit differentials if the target bidegree is zero.
 
 use algebra::module::Module;
 use std::sync::Arc;

ext/examples/secondary_massey.rs

@@ -1,4 +1,26 @@
-//! Computes massey products in $\Mod_{C\tau^2}$. This is only correct up to a sign!!!
+//! Computes massey products in $\Mod_{C\tau^2}$.
+//!
+//! # Usage
+//! This computes all Massey products of the form $\langle a, b, -\rangle$, where
+//! $a \in \Ext^{\*, \*}(M, k)$ and $b, (-) \in \Ext^{\*, \*}(k, k)$. It does not verify that the
+//! Massey product is valid, i.e. $a$ and $b$ both lift to $\Mod_{C\tau^2}$ and have trivial
+//! product.
+//!
+//! Since we must choose $a$ and $b$ to have trivial product, it is necessary to be able to specify
+//! the $\tau$ part of them, and not insist that they are standard lifts of the $\Ext$ classes.
+//! Thus, the user is first prompted for the $\Ext$ part, then the $\tau$ part of each class. If
+//! the bidegree right above the class is empty, the user is not prompted for the $\tau$ part.
+//!
+//! Note that for the purposes of save files, the name of the product should include the $\tau$
+//! part as well. Products with different $\tau$ parts should have separate save directories. (If
+//! one wishes to save some of computation, one can symlink the `secondary_composites` directory,
+//! which *can* be shared for products with the same $\Ext$ part but different $\tau$ part) There
+//! is no theoretical reason this has to be the case, but it is rather unpleasant to make it use
+//! the same save file, and such a need has not arisen yet.
+//!
+//! # Output
+//! This computes the Massey products up to a sign. Brave souls are encouraged to figure out the
+//! correct sign for the products.
 
 use std::path::PathBuf;
 use std::sync::Arc;

ext/examples/secondary_product.rs

@@ -1,4 +1,20 @@
 //! Computes products in $\Mod_{C\tau^2}$.
+//!
+//! # Usage
+//! The program asks for a module $M$ and an element $x \in \Ext^{\*, \*}(M, k)$. It then
+//! computes the secondary product of the standard lift of $x$ with all (standard lifts of)
+//! elements in $\Ext^{\*, \*}(M, k)$ that survive $d_2$.
+//!
+//! These products are computed for all elements whose product with $x$ lies in the specified
+//! bidegree of $M$, and $k$ is resolved as far as necessary to support this computation.
+//!
+//! Running this program requires computing the secondary resolution of both $M$ and $k$, i.e. the
+//! calculations performed by [`secondary`](../secondary/index.html). The user is encouraged to
+//! make use of a save file to reuse these calculations for different products. (When $M$ is not
+//! equal to $k$, the user will be prompted for the save directory of $k$)
+//!
+//! # Notes
+//! The program verifies that $x$ is indeed permanent.
 
 use std::path::PathBuf;
 use std::sync::Arc;

ext/src/lib.rs

@@ -159,8 +159,8 @@
 //!   configured via the `RAYON_NUM_THREADS` environment variable.
 //! - `use-zstd`: Support reading zstd-compressed save files.
 //! - `cache-multiplication`: Precompute and cache the multiplication table under the Milnor basis.
-//!    This is only feasible when using a small, finite subalgebra, e.g. when working with tmf
-//!    modules.
+//!    This is only feasible when using a small, finite subalgebra, e.g. when working with
+//!    $\mathrm{tmf}$ modules.
 
 #![allow(clippy::upper_case_acronyms)]
 

ext/src/nassau.rs

@@ -17,8 +17,8 @@ use once::OnceVec;
 #[cfg(feature = "concurrent")]
 use std::sync::mpsc;
 
-/// See [`Resolution::SenderData`]. This differs by not having the `new` field.
 #[cfg(feature = "concurrent")]
+/// See [`resolution::SenderData`](../resolution/struct.SenderData.html). This differs by not having the `new` field.
 struct SenderData {
     s: u32,
     t: i32,