DOC: Fill out API docs for catlog-wasm and warn on missing docs. (#663)

Author: epatters

packages/catlog-wasm/README.md

@@ -1,22 +1,28 @@
+//! Auxiliary structs for data passed to/from analyses.
+
 use serde::{Deserialize, Serialize};
 use tsify::Tsify;
 use uuid::Uuid;
 
 use super::result::JsResult;
 use catlog::stdlib::analyses;
 
+/// The result of an ODE analysis, containing the solution when successful.
 #[derive(Serialize, Deserialize, Tsify)]
 #[tsify(into_wasm_abi, from_wasm_abi)]
 pub struct ODEResult(pub JsResult<analyses::ode::ODESolution<Uuid>, String>);
 
+/// Input data for a Lokta-Volterra analysis of a model.
 #[derive(Serialize, Deserialize, Tsify)]
 #[tsify(into_wasm_abi, from_wasm_abi)]
 pub struct LotkaVolterraModelData(pub analyses::ode::LotkaVolterraProblemData<Uuid>);
 
+/// Input data for a linear ODE analysis of a model.
 #[derive(Serialize, Deserialize, Tsify)]
 #[tsify(into_wasm_abi, from_wasm_abi)]
 pub struct LinearODEModelData(pub analyses::ode::LinearODEProblemData<Uuid>);
 
+/// Input data for a mass-action dynamics analysis of a model.
 #[derive(Serialize, Deserialize, Tsify)]
 #[tsify(into_wasm_abi, from_wasm_abi)]
 pub struct MassActionModelData(pub analyses::ode::MassActionProblemData<Uuid>);

packages/catlog-wasm/src/analyses.rs

@@ -1,3 +1,17 @@
+/*! Rust-TypeScript interop for categorical logic.
+
+This crate provides [WebAssembly](https://webassembly.org/) (Wasm) bindings for
+the [`catlog`] crate using Rust's `wasm-bindgen`. The aim is to keep the logic
+here as simple as possible, with [`catlog`] doing all the real work. However,
+the translation is nontrivial because there is a single, catch-all type
+definition for a double theory in TypeScript, but several kinds of double
+theories implemented in Rust (discrete theories, modal theories, and so on). The
+same is true for other structures, such as models of theories and diagrams in
+models.
+*/
+
+#![warn(missing_docs)]
+
 pub mod notation;
 pub mod result;
 
@@ -8,6 +22,7 @@ pub mod theory;
 
 pub mod analyses;
 #[allow(clippy::new_without_default)]
+#[allow(missing_docs)]
 pub mod theories;
 
 use wasm_bindgen::prelude::*;
@@ -29,14 +44,16 @@ export type Ustr = string;
 export type NonEmpty<T> = Array<T>;
 "#;
 
+/** Set panic hook to get better error messages on panics.
+
+When the `console_error_panic_hook` feature is enabled, we can call the
+`set_panic_hook` function at least once during initialization, and then we will
+get better error messages if our code ever panics.
+
+For more details see <https://github.com/rustwasm/console_error_panic_hook#readme>
+ */
 #[wasm_bindgen]
 pub fn set_panic_hook() {
-    // When the `console_error_panic_hook` feature is enabled, we can call the
-    // `set_panic_hook` function at least once during initialization, and then
-    // we will get better error messages if our code ever panics.
-    //
-    // For more details see
-    // https://github.com/rustwasm/console_error_panic_hook#readme
     #[cfg(feature = "console_error_panic_hook")]
     console_error_panic_hook::set_once();
 }

packages/catlog-wasm/src/lib.rs

@@ -1,3 +1,5 @@
+//! Wasm bindings for models of a double theory.
+
 use all_the_same::all_the_same;
 use derive_more::{From, TryInto};
 use serde::{Deserialize, Serialize};
@@ -31,11 +33,15 @@ See [`DblTheoryBox`] for motivation.
 #[derive(From, TryInto)]
 #[try_into(ref, ref_mut)]
 pub enum DblModelBox {
+    /// A model of a discrete double theory.
     Discrete(DiscreteDblModel),
+    /// A model of a discrete tabulator theory.
     DiscreteTab(DiscreteTabModel),
+    /// A model of a modal double theory.
     Modal(ModalDblModel),
 }
 
+/// Wasm binding of a model of a double theory.
 #[wasm_bindgen]
 pub struct DblModel(#[wasm_bindgen(skip)] pub DblModelBox);
 
@@ -455,6 +461,7 @@ impl DblModel {
         })
     }
 
+    /// Validates the model, returning any validation failures.
     pub fn validate(&self) -> ModelValidationResult {
         all_the_same!(match &self.0 {
             DblModelBox::[Discrete, DiscreteTab, Modal](model) => {
@@ -478,6 +485,7 @@ pub fn collect_product(ob: Ob) -> Result<Vec<Ob>, String> {
     Ok(vec.into_iter().map(|ob| Quoter.quote(&ob)).collect())
 }
 
+/// Elaborates a model defined by a notebook into a catlog model.
 #[wasm_bindgen(js_name = "elaborateModel")]
 pub fn elaborate_model(doc: &ModelDocumentContent, theory: &DblTheory) -> DblModel {
     let mut model = DblModel::new(theory);

packages/catlog-wasm/src/model.rs

@@ -23,11 +23,12 @@ use super::theory::DblTheory;
 /// A box containing a diagram in a model of a double theory.
 #[derive(From)]
 pub enum DblModelDiagramBox {
+    /// A diagram in a model of a discrete double theory.
     Discrete(diagram::DblModelDiagram<DiscreteDblModelMapping, DiscreteDblModel>),
     // DiscreteTab(), # TODO: Not implemented.
 }
 
-/// Wasm bindings for a diagram in a model of a double theory.
+/// Wasm binding for a diagram in a model of a double theory.
 #[wasm_bindgen]
 pub struct DblModelDiagram(#[wasm_bindgen(skip)] pub DblModelDiagramBox);
 
@@ -203,6 +204,7 @@ pub struct ModelDiagramValidationResult(
     pub JsResult<(), Vec<diagram::InvalidDiscreteDblModelDiagram<Uuid>>>,
 );
 
+/// Elaborates a diagram defined by a notebook into a catlog diagram.
 #[wasm_bindgen(js_name = "elaborateDiagram")]
 pub fn elaborate_diagram(doc: &DiagramDocumentContent, theory: &DblTheory) -> DblModelDiagram {
     let mut diagram = DblModelDiagram::new(theory);

packages/catlog-wasm/src/model_diagram.rs

@@ -1,3 +1,5 @@
+//! Wasm bindings for morphisms between models of a double theory.
+
 use std::hash::Hash;
 
 use serde::{Deserialize, Serialize};

packages/catlog-wasm/src/model_morphism.rs

@@ -9,6 +9,10 @@ singleton.
  */
 pub struct Elaborator;
 
+/** A type that can elaborated into another.
+
+Says that objects of type `T` can be elaborated into objects of type `S`.
+ */
 pub trait CanElaborate<T, S> {
     /// Transform notation into syntax.
     fn elab(&self, x: &T) -> Result<S, String>;
@@ -21,6 +25,10 @@ Unlike elaboration, quotation is infallible.
  */
 pub struct Quoter;
 
+/** A typed that quoted into another.
+
+Says that objects of type `T` can be quoted as objects of type `S`.
+ */
 pub trait CanQuote<T, S> {
     /// Transform syntax or value into notation.
     fn quote(&self, x: &T) -> S;

packages/catlog-wasm/src/notation.rs

@@ -1,7 +1,7 @@
-/*! Wasm bindings for double theories from the `catlog` standard library.
+/*! Wasm bindings for the standard library of theories in `catlog`.
 
-Each struct in this module provides a [`DblTheory`] plus possibly
-theory-specific analysis methods.
+Each struct in this module provides a [`DblTheory`], possibly with additional
+methods for theory-specific analyses.
  */
 
 use std::rc::Rc;

packages/catlog-wasm/src/theories.rs

@@ -261,13 +261,15 @@ explicitly enumerate the supported kinds of double theories in this enum.
 #[derive(From, TryInto)]
 #[try_into(ref)]
 pub enum DblTheoryBox {
+    /// A discrete double theory.
     Discrete(Rc<theory::UstrDiscreteDblTheory>),
+    /// A discrete tabulator theory.
     DiscreteTab(Rc<theory::UstrDiscreteTabTheory>),
+    /// A modal double theory.
     Modal(Rc<theory::UstrModalDblTheory>),
 }
 
-/** Wasm bindings for a double theory.
- */
+/// Wasm binding for a double theory.
 #[wasm_bindgen]
 pub struct DblTheory(#[wasm_bindgen(skip)] pub DblTheoryBox);
 

packages/catlog-wasm/src/theory.rs

@@ -169,11 +169,12 @@ impl StockFlowMassActionAnalysis {
             };
         }
 
-        let terms: Vec<(Id, Polynomial<Id, Parameter<Id>, u8>)> = terms
+        let terms: Vec<_> = terms
             .into_iter()
             .map(|(flow, term)| {
                 let param = Parameter::generator(flow.clone());
-                (flow, [(param, term)].into_iter().collect())
+                let poly: Polynomial<_, _, _> = [(param, term)].into_iter().collect();
+                (flow, poly)
             })
             .collect();