Docs (#11)

* add doc check to CI

* fail on missing docs and warnings

* sample docs

* fix rmq doc tests

* update docs for rmq & fenwick

* add dsu docs

* add DOCUMENTATION guidelines

* make docs more minimal

* update the documentation guidelines to reflect more minimal docs

* document graphs & update lca test

* add numbers docs

* complete docs

* fix docs

* code coverage?

* unable to fix code coverage

---------

Co-authored-by: Luke Videckis <lukevideckis@gmail.com>
Co-authored-by: Cameron Custer <custer.cameron@gmail.com>

Author: lrvideckis

.github/workflows/ci.yml

@@ -14,32 +14,42 @@ jobs:
     steps:
     - uses: actions/checkout@v3
     - uses: actions/setup-python@v4
+
     - name: Set up Rust (nightly)
       run: |
         rustup install nightly
         rustup override set nightly
         rustup component add --toolchain nightly rustfmt clippy
+
     - name: cargo fmt
       run: cargo fmt --all -- --check
+
     - name: cargo clippy
       run: cargo clippy --all-targets --all-features -- -D warnings
+
     - name: cargo build
       run: cargo build
+
     - name: cargo test
       run: cargo test
 
+    - name: cargo doc
+      run: RUSTDOCFLAGS="-D warnings -D missing_docs" cargo doc --all
+
   library_checker_aizu_tests:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
     - uses: actions/setup-python@v4
+
     - name: Set up Rust (nightly)
       run: |
         rustup install nightly
         rustup override set nightly
         rustup component add --toolchain nightly rustfmt clippy
         cargo install cargo-binutils
         rustup component add llvm-tools-preview
+
     - name: install oj-verify submodule
       run: |
         git submodule init
@@ -49,6 +59,7 @@ jobs:
         cd ..
         # clear submodule afterwards to not run tests in verification-helper
         git submodule deinit --all -f
+
     - name: run tests
       # regarding `--jobs 4`: github CI runs with 4 cores
       # https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories
@@ -63,6 +74,7 @@ jobs:
       # since all tests are rerun on every commit anyways, there's no need for
       # the .verify-helper/timestamps.remote.json file
       run: oj-verify all --tle 20 --jobs 4 --timeout 21600
+
     # https://doc.rust-lang.org/rustc/instrument-coverage.html
     # - name: code coverage
     # run: |

README.md

@@ -1,7 +1,7 @@
-### Mission
+# Mission
 To provide a collection of algorithms and data structures useful for competitive programming in Rust.
 
-### Focus
+# Focus
 This library is written to be optimized for online contests \[Codeforces, AtCoder, etc.\]
 
 Therefore the code is written with these three pillars:
@@ -11,14 +11,14 @@ Therefore the code is written with these three pillars:
 
 Note: the code is **not** written for ICPC style contests and is **not** optimized for code length.
 
-### Rust CF Blogs
+## Rust CF Blogs
 
 - https://codeforces.com/blog/entry/67391
 - https://codeforces.com/blog/entry/103794
 - https://codeforces.com/blog/entry/111573
 - https://codeforces.com/blog/entry/125439
 
-### Other Rust CP Repos
+## Other Rust CP Repos
 
 - https://github.com/rust-lang-ja/ac-library-rs
 - https://github.com/EgorKulikov/rust_algo
@@ -27,3 +27,13 @@ Note: the code is **not** written for ICPC style contests and is **not** optimiz
 - https://github.com/qitoy/rust-library
 - https://github.com/stuart0035/procon-lib-rs
 
+## Contributing
+
+We're open to all feedback. You can submit an issue or email us at
+```
+lrvideckis@gmail.com
+```
+```
+custer.cameron@gmail.com
+```
+

examples/README.md

@@ -4,3 +4,8 @@
 - when using both sites name the files `[algo]_yosupo.rs` and `[algo]_aizu.rs`
 - when only testing a specific function or componenet of some algorithm name the file `[algo]_[component].rs`
 
+# Documentation Guidelines
+- use the `///` syntax for documentation
+- for structs, enums, traits, and standalone functions, provide an example testing every method
+- for member functions explain what the function does and provide the time and space complexity
+

examples/graphs/lca_yosupo.rs

@@ -10,29 +10,35 @@ fn main() {
     }
 
     // forest with an undirected tree and a rooted directed tree
-    let mut adj = vec![vec![]; n + n];
-    for v in 1..n {
+    let mut undir_for = vec![vec![]; n + n];
+    let mut dir = vec![vec![]; n];
+    for c in 1..n {
         input! {
             p: usize,
         }
 
         // undirected tree
-        adj[p].push(v);
-        adj[v].push(p);
+        for &(u, v) in [(p, c), (p + n, c + n)].iter() {
+            undir_for[u].push(v);
+            undir_for[v].push(u);
+        }
 
         // directed tree
-        adj[n + p].push(n + v);
+        dir[p].push(c);
     }
 
-    let lca = LCA::new(&adj);
+    let undir_lca = LCA::new(&undir_for);
+    let dir_lca = LCA::new(&dir);
     for _ in 0..q {
         input! {
             u: usize,
             v: usize,
         }
-        let res_undir = lca.lca(u, v);
-        let res_dir = lca.lca(n + u, n + v) - n;
-        assert!(res_undir == res_dir);
-        println!("{}", res_undir);
+        let res_undir1 = undir_lca.lca(u, v);
+        let res_undir2 = undir_lca.lca(u + n, v + n) - n;
+        let res_dir = dir_lca.lca(u, v);
+        assert_eq!(res_undir1, res_undir2);
+        assert_eq!(res_undir1, res_dir);
+        println!("{}", res_dir);
     }
 }

src/data_structures/dsu.rs

@@ -1,10 +1,38 @@
+//! # Disjoint Set Union
+
+/// # Example
+/// ```
+/// use programming_team_code_rust::data_structures::dsu::DSU;
+///
+/// let mut dsu = DSU::new(10);
+/// assert_eq!(dsu.same(1, 2), false);
+/// dsu.unite(1, 3);
+/// dsu.unite(2, 4);
+/// assert_eq!(dsu.same(1, 4), false);
+/// dsu.unite(2, 3);
+/// assert_eq!(dsu.same(1, 4), true);
+/// assert_eq!(dsu.leader(3), 2);
+/// assert_eq!(dsu.leader(5), 5);
+/// ```
 pub struct DSU {
     e: Vec<i32>,
 }
+
 impl DSU {
+    /// Create a new DSU with n elements
+    ///
+    /// # Complexity
+    /// - Time: O(n)
+    /// - Space: O(n)
     pub fn new(n: usize) -> Self {
         DSU { e: vec![-1; n] }
     }
+
+    /// Get the leader of the group that x belongs to
+    ///
+    /// # Complexity
+    /// - Time: O(α(n))
+    /// - Space: O(1)
     pub fn leader(&mut self, x: usize) -> usize {
         if self.e[x] < 0 {
             x
@@ -15,9 +43,23 @@ impl DSU {
             r
         }
     }
+
+    /// Check if x and y belong to the same group
+    ///
+    /// # Complexity
+    /// - Time: O(α(n))
+    /// - Space: O(1)
     pub fn same(&mut self, x: usize, y: usize) -> bool {
         self.leader(x) == self.leader(y)
     }
+
+    /// Unite the groups that x and y belong to
+    /// Returns true if x and y were in different groups
+    /// Returns false if x and y were in the same group
+    ///
+    /// # Complexity
+    /// - Time: O(α(n))
+    /// - Space: O(1)
     pub fn unite(&mut self, x: usize, y: usize) -> bool {
         let mut x = self.leader(x);
         let mut y = self.leader(y);

src/data_structures/fenwick.rs

@@ -1,28 +1,57 @@
+//! # Fenwick Tree (Binary Indexed Tree)
+
+/// # Example
+/// ```
+/// use programming_team_code_rust::data_structures::fenwick::Fenwick;
+///
+/// let mut fenwick = Fenwick::new(5);
+/// fenwick.add(1, 3);
+/// fenwick.add(2, 2);
+/// fenwick.add(3, 1);
+/// assert_eq!(fenwick.sum(1..3), 5);
+/// ```
 pub struct Fenwick<T> {
     ary: Vec<T>,
 }
+
 impl<T: Clone + Default + std::ops::AddAssign<T>> Fenwick<T> {
+    /// Creates a new Fenwick Tree with size n
+    ///
+    /// # Complexity
+    /// - Time: O(n)
+    /// - Space: O(n)
     pub fn new(n: usize) -> Self {
         Fenwick {
             ary: vec![T::default(); n],
         }
     }
-    pub fn accum(&self, mut idx: usize) -> T {
+
+    fn accum(&self, mut idx: usize) -> T {
         let mut sum = T::default();
         while idx > 0 {
             sum += self.ary[idx - 1].clone();
             idx &= idx - 1;
         }
         sum
     }
-    /// performs data[idx] += val;
+
+    /// Increments the value at `idx` by `val`
+    ///
+    /// # Complexity
+    /// - Time: O(log n)
+    /// - Space: O(1)
     pub fn add(&mut self, mut idx: usize, val: T) {
         while idx < self.ary.len() {
             self.ary[idx] += val.clone();
             idx |= idx + 1;
         }
     }
-    /// Returns data[l] + ... + data[r - 1].
+
+    /// Query the sum of the range [range.start, range.end)
+    ///
+    /// # Complexity
+    /// - Time: O(log n)
+    /// - Space: O(1)
     pub fn sum(&self, range: std::ops::Range<usize>) -> T
     where
         T: std::ops::Sub<Output = T>,

src/data_structures/mod.rs

@@ -1,3 +1,4 @@
+//! # Data Structures
 pub mod dsu;
 pub mod fenwick;
 pub mod rmq;

src/data_structures/rmq.rs

@@ -1,8 +1,25 @@
+//! # Range Minimum Query
+
+/// # Example
+/// ```
+/// use programming_team_code_rust::data_structures::rmq::RMQ;
+///
+/// let a = [1, 3, 2, 4, 5];
+/// let rmq = RMQ::new(&a, std::cmp::min);
+/// assert_eq!(rmq.query(0..5), 1);
+/// assert_eq!(rmq.query(1..4), 2);
+/// ```
 pub struct RMQ<T> {
     t: Vec<Vec<T>>,
     op: fn(T, T) -> T,
 }
+
 impl<T: Copy> RMQ<T> {
+    /// Create a new RMQ instance
+    ///
+    /// # Complexity (n = a.len())
+    /// - Time: O(n log n)
+    /// - Space: O(n log n)
     pub fn new(a: &[T], op: fn(T, T) -> T) -> Self {
         let mut t = vec![a.to_owned(); 1];
         let mut i = 0;
@@ -17,6 +34,11 @@ impl<T: Copy> RMQ<T> {
         Self { t, op }
     }
 
+    /// Query the range [range.start, range.end)
+    ///
+    /// # Complexity
+    /// - Time: O(1)
+    /// - Space: O(1)
     pub fn query(&self, range: std::ops::Range<usize>) -> T {
         let lg = range.len().ilog2() as usize;
         (self.op)(self.t[lg][range.start], self.t[lg][range.end - (1 << lg)])

src/graphs/dijk.rs

@@ -1,10 +1,34 @@
-use std::cmp::Reverse;
-use std::collections::BinaryHeap;
+//! # Dijkstra's algorithm
 
+/// # Example
+/// ```
+/// use programming_team_code_rust::graphs::dijk::dijk;
+///
+/// let adj = vec![
+///    vec![(1, 1), (2, 4)],
+///    vec![(2, 2), (3, 5)],
+///    vec![(3, 1)],
+///    vec![],
+///    vec![(0, 7)],
+///    vec![(1, 3), (3, 2)],
+///    vec![(0, 2), (2, 3)],
+///    vec![(1, 2), (4, 2)],
+/// ];
+///
+/// let dist = dijk(&adj, 0);
+/// assert_eq!(dist, vec![0, 1, 3, 4, u64::MAX, u64::MAX, u64::MAX, u64::MAX]);
+/// ```
+///
+/// # Complexity
+/// - V: number of vertices
+/// - E: number of edges
+/// - Time: O(V + E log E)
+/// - Space: O(V + E)
 pub fn dijk(adj: &[Vec<(usize, u64)>], s: usize) -> Vec<u64> {
+    use std::cmp::Reverse;
     let n = adj.len();
     let mut dist = vec![u64::MAX; n];
-    let mut q = BinaryHeap::new();
+    let mut q = std::collections::BinaryHeap::new();
     q.push(Reverse((0, s)));
     while let Some(Reverse((d, u))) = q.pop() {
         if dist[u] <= d {