fix doc gen and add to CI (#201)

.github/workflows/ci.yml

@@ -28,11 +28,13 @@ jobs:
               run: python3 driver.py --all-features
             - name: Install python reqs
               run: python3 driver.py --install
-            - name: Check
-              run: python3 driver.py --check
             - name: Format
               run: cargo fmt -- --check
+            - name: Check
+              run: python3 driver.py --check
             - name: Lint
               run: python3 driver.py --lint
+            - name: Document
+              run: python3 driver.py --doc
             - name: Build, then Test
               run: python3 driver.py --test

driver.py

@@ -115,6 +115,22 @@ def check_all():
         )
 
 
+def doc(features):
+    """
+    Run cargo doc
+
+    Parameters
+    ----------
+        features : set of str
+            set of features required
+    """
+
+    cmd = ["cargo", "doc", "--document-private-items"]
+    if features:
+        cmd = cmd + ["--features"] + [",".join(features)]
+    log_run_check(cmd)
+
+
 def build(features):
     """
     Run cargo build and any test cases in the feature list
@@ -321,6 +337,7 @@ def format_sub_process_cmd(r: subprocess.CalledProcessError) -> str:
             action="store_true",
             help="install all dependencies from the feature set",
         )
+        parser.add_argument("-d", "--doc", action="store_true", help="run `cargo doc`")
         parser.add_argument(
             "-c", "--check", action="store_true", help="run `cargo check`"
         )
@@ -419,6 +436,9 @@ def verify_extra_implies_flamegraph_or_test(args: argparse.Namespace):
         if args.check_all:
             check_all()
 
+        if args.doc:
+            doc(features)
+
         if args.build:
             build(features)
 

src/cfg.rs

@@ -4,9 +4,9 @@
 //! * A type [CircCfg] for configuration information.
 //! * Static configuration storage
 //!    * set with [set] and [set_cfg]
-//!    * read with [cfg]
+//!    * read with [cfg()]
 //!    * it can only be set once per process
-//!       * if you want to unit-test your component, we recommend that it **should not** use [cfg].
+//!       * if you want to unit-test your component, we recommend that it **should not** use [cfg()].
 
 use circ_fields::FieldT;
 

src/front/mod.rs

@@ -52,7 +52,7 @@ impl Display for Mode {
     }
 }
 
-/// This module contains [FieldList].
+/// This module contains [field_list::FieldList].
 ///
 /// It gets its own module so that its member can be private.
 mod field_list {

src/ir/opt/mem/ram/checker/rom.rs

@@ -1,4 +1,4 @@
-//! Implementation of ROM checking based on https://eprint.iacr.org/2022/1530.pdf
+//! Implementation of ROM checking based on <https://eprint.iacr.org/2022/1530.pdf>
 //!
 //! Cost: about (N + A)(L + 1) where the ROM size is N, there are A reads, and values have size L.
 //! If the ROM contents are fixed, cost drops to N + A(L + 1)

src/ir/term/ext/haboeck.rs

@@ -1,6 +1,6 @@
 //! Witness computation for Haboeck's lookup argument
 //!
-//! https://eprint.iacr.org/2022/1530.pdf
+//! <https://eprint.iacr.org/2022/1530.pdf>
 //!
 //! Given a haystack array of values h1, ..., hN and an array of needles v1, ..., vA, outputs
 //! an array of counts c1, ..., cN such that hI occurs cI times in v1, ..., vA.

src/ir/term/ext/ram.rs

@@ -28,8 +28,8 @@ pub fn check(arg_sorts: &[&Sort]) -> Result<Sort, TypeErrorReason> {
 ///
 /// Takes two arguments:
 ///
-/// * entries: [(val_init_i, val_fin_i)] (len E)
-/// * indices: [idx_i] (len I)
+/// * entries: `[(val_init_i, val_fin_i)]` (len E)
+/// * indices: `[idx_i]` (len I)
 ///
 /// assumes I < E and 0 <= idx_i < E.
 ///

src/ir/term/mod.rs

@@ -11,7 +11,7 @@
 //!       * [Sort]: the type of a term
 //!       * [check]: get the type of a term
 //!    * Term construction
-//!       * [term!]: from an operator and a syntactic list of children
+//!       * [term]: from an operator and a syntactic list of children
 //!       * [leaf_term]: from an operator alone
 //!       * [term()]: from an operator and vector of children
 //!    * Term data-structures and algorithms
@@ -182,7 +182,7 @@ pub enum Op {
     Call(Box<CallOp>),
 
     /// Cyclic right rotation of an array
-    /// i.e. (Rot(1) [1,2,3,4]) --> ([4,1,2,3])
+    /// i.e. `(Rot(1) [1,2,3,4]) --> ([4,1,2,3])`
     Rot(usize),
 
     /// Assume that the field element is 0 or 1, and treat it as a boolean.

src/lib.rs

@@ -4,6 +4,7 @@
 
 #![warn(missing_docs)]
 #![deny(warnings)]
+#![allow(rustdoc::private_intra_doc_links)]
 
 #[macro_use]
 pub mod ir;

src/target/r1cs/mirage/cp_link.rs

@@ -16,8 +16,8 @@
 //!
 //! The relation holds when for i in 1..C:
 //!
-//! * common_cmts[i] = Commit(common_ck, data[i]) AND
-//! * cmts[i] = Commit(cks[i], data[i])
+//! * `common_cmts[i] = Commit(common_ck, data[i])` AND
+//! * `cmts[i] = Commit(cks[i], data[i])`
 //!
 //! Thus, the relation "links" the commitments cmts under different keys to the commitments
 //! common_cmts under the same key.
@@ -27,11 +27,11 @@
 //! We build a matrix containing commit keys. Let N be the new data length and C be the number of
 //! commitments. Our KW15 scheme is (0-)indexed as follows. The matrix is 2C by (N+2) C
 //!
-//! * For i in 0..C: commitment i is common_cmts[i]
-//! * For i in 0..C: commitment C + i is cmts[i]
-//! * For i in 0..C: for j in 0..N: scalar i * N + j is data[i][j]
-//! * For i in 0..C: scalar N * C + i is common_rands[i]
-//! * For i in 0..C: scalar N * C + C + i is rands[i]
+//! * For i in 0..C: `commitment i is common_cmts[i]`
+//! * For i in 0..C: `commitment C + i is cmts[i]`
+//! * For i in 0..C: `for j in 0..N: scalar i * N + j is data[i][j]`
+//! * For i in 0..C: `scalar N * C + i is common_rands[i]`
+//! * For i in 0..C: `scalar N * C + C + i is rands[i]`
 
 use ff::{Field, PrimeFieldBits};
 use group::Group;