docs: fix wrong examples and time/space claims (#237)

* docs: state unwritten contracts in doc comments

* docs: fix wrong examples and time/space claims

* docs: remove overflow note from matrix_mult per review

---------

Co-authored-by: Cameron Custer <cam@augmentcode.com>

Author: cameroncuster

library/convolution/min_plus_convolution_convex_and_arbitrary.hpp

@@ -2,7 +2,7 @@
 //! @param convex,arbitrary arrays where convex satisfies
 //!   convex[i+1]-convex[i] <= convex[i+2]-convex[i+1]
 //! @returns array `res` where `res[k]` = the min of
-//!   (a[i]+b[j]) for all pairs (i,j) where i+j==k
+//!   (convex[j]+arbitrary[i]) over pairs with i+j==k
 //! @time O((n + m) log (n + m))
 //! @space O(n + m)
 vi min_plus(const vi& convex, const vi& arbitrary) {

library/data_structures_[l,r)/bit.hpp

@@ -5,8 +5,8 @@
 //!     // sum = a[0] + a[1] + ... + a[r - 1]
 //!   });
 //!   int r = bit.walk2(sum);
-//!   // Returns min r s.t. sum of [0,r] >= sum
-//!   // Returns n if sum of [0,n-1] < sum
+//!   // Returns min r s.t. sum of [0,r+1) >= sum
+//!   // Returns n if sum of [0,n) < sum
 //!   // Returns -1 if sum <= 0
 //! @endcode
 //! @time O(n + q log n)

library/graphs/dijkstra.hpp

@@ -4,6 +4,7 @@
 //!   auto d = dijkstra(g, source);
 //! @endcode
 //! d[v] = min dist from source->..->v
+//! requires weights >= 0
 //! @time O(n + (m log m))
 //! @space O(n + m)
 vector<ll> dijkstra(const auto& g, int s) {

library/graphs/min_vertex_cover.hpp

@@ -9,8 +9,8 @@
 //!   auto [mvc_l, mvc_r] = cover(g, r);
 //!   // mvc_l[u] == 1 iff u in mvc
 //! @endcode
-//! @time O(n + q * log n)
-//! @space O(n * \alpha(n))
+//! @time O(n + m)
+//! @space O(n)
 pair<vi, vi> cover(const vector<vi>& g, vi& r) {
   int n = sz(g), t = 0;
   vi cl(n), cr(sz(r)), q(n);

library/graphs/uncommon/enumerate_triangles.hpp

@@ -5,6 +5,7 @@
 //!       //u, v, w form a triangle
 //!   });
 //! @endcode
+//! requires no self loops or multi edges
 //! @time O(n + m ^ (3/2))
 //! @space O(n + m)
 void enumerate_triangles(const vector<pii>& edges, int n,

library/loops/submasks.hpp

@@ -1,5 +1,6 @@
 #pragma once
 //! loops over submasks in decreasing order
+//! excludes the empty submask
 //! @param mask a submask of 2^n-1
 //! @time O(3^n) to iterate every submask
 //!   of every mask of size n

library/math/derangements.hpp

@@ -4,6 +4,7 @@
 //!   auto der = derangements(n, mod);
 //! @endcode
 //! der[i] = number of permutations p with p[i]!=i
+//! requires n >= 1
 //! @time O(n)
 //! @space O(n)
 vector<ll> derangements(int n, int mod) {

library/math/matrix_related/row_reduce.hpp

@@ -6,6 +6,7 @@
 //! columns [0,cols) of mat represent a matrix
 //! columns [cols,m) of mat are also
 //!   affected by row operations
+//! requires mod is prime
 //! @time O(n * m * min(cols, n))
 //! @space O(1)
 pii row_reduce(vector<vi>& mat, int cols) {

library/math/mod_division.hpp

@@ -3,6 +3,7 @@
 //! @code
 //!   int quotient = mod_div(x, y); // returns x * y^-1
 //! @endcode
+//! requires gcd(y, mod) == 1
 //! @time O(log(y))
 //! @space O(1)
 const int mod = 998244353;

library/math/num_distinct_subsequences.hpp

@@ -1,6 +1,6 @@
 #pragma once
 //! returns the number of distinct subsequences
-//!   of a, including the empty subsquence
+//!   of a, including the empty subsequence
 //! @time O(n log n)
 //! @space O(n)
 int num_subsequences(const vi& a, int mod) {