File-level documentation for some of src/lib.

10 files changed, 65 insertions, 0 deletions

diff --git a/src/lib/intmath/addsub.c b/src/lib/intmath/addsub.c
index 816c5a2bd7..fcfdca6822 100644
--- a/src/lib/intmath/addsub.c
+++ b/src/lib/intmath/addsub.c
@@ -3,6 +3,14 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file addsub.c
+ *
+ * \brief Helpers for addition and subtraction.
+ *
+ * Currently limited to non-wrapping (saturating) addition.
+ **/
+
 #include "lib/intmath/addsub.h"
 #include "lib/cc/compat_compiler.h"
 
diff --git a/src/lib/intmath/addsub.h b/src/lib/intmath/addsub.h
index 5277adfa49..5bbc32e4a9 100644
--- a/src/lib/intmath/addsub.h
+++ b/src/lib/intmath/addsub.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file addsub.h
+ *
+ * \brief Header for addsub.c
+ **/
+
 #ifndef TOR_INTMATH_ADDSUB_H
 #define TOR_INTMATH_ADDSUB_H
 
diff --git a/src/lib/intmath/bits.c b/src/lib/intmath/bits.c
index 85d901f71b..4b5729e99a 100644
--- a/src/lib/intmath/bits.c
+++ b/src/lib/intmath/bits.c
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file bits.c
+ *
+ * \brief Count the bits in an integer, manipulate powers of 2, etc.
+ **/
+
 #include "lib/intmath/bits.h"
 
 /** Returns floor(log2(u64)).  If u64 is 0, (incorrectly) returns 0. */
diff --git a/src/lib/intmath/bits.h b/src/lib/intmath/bits.h
index 70f855089c..80eebe9358 100644
--- a/src/lib/intmath/bits.h
+++ b/src/lib/intmath/bits.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file bits.h
+ *
+ * \brief Header for bits.c
+ **/
+
 #ifndef TOR_INTMATH_BITS_H
 #define TOR_INTMATH_BITS_H
 
diff --git a/src/lib/intmath/cmp.h b/src/lib/intmath/cmp.h
index 627e5d18b4..16952bee3e 100644
--- a/src/lib/intmath/cmp.h
+++ b/src/lib/intmath/cmp.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file cmp.h
+ *
+ * \brief Macro definitions for MIN, MAX, and CLAMP.
+ **/
+
 #ifndef TOR_INTMATH_CMP_H
 #define TOR_INTMATH_CMP_H
 
diff --git a/src/lib/intmath/logic.h b/src/lib/intmath/logic.h
index 0510a621dc..b3eabc652e 100644
--- a/src/lib/intmath/logic.h
+++ b/src/lib/intmath/logic.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file logic.h
+ *
+ * \brief Macros for comparing the boolean value of integers.
+ **/
+
 #ifndef HAVE_TOR_LOGIC_H
 #define HAVE_TOR_LOGIC_H
 
diff --git a/src/lib/intmath/muldiv.c b/src/lib/intmath/muldiv.c
index 3e627b237a..c5fc689e2d 100644
--- a/src/lib/intmath/muldiv.c
+++ b/src/lib/intmath/muldiv.c
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file muldiv.c
+ *
+ * \brief Integer math related to multiplication, division, and rounding.
+ **/
+
 #include "lib/intmath/muldiv.h"
 #include "lib/err/torerr.h"
 
diff --git a/src/lib/intmath/muldiv.h b/src/lib/intmath/muldiv.h
index de76d9eb68..45b896922f 100644
--- a/src/lib/intmath/muldiv.h
+++ b/src/lib/intmath/muldiv.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file muldiv.h
+ *
+ * \brief Header for muldiv.c
+ **/
+
 #ifndef TOR_INTMATH_MULDIV_H
 #define TOR_INTMATH_MULDIV_H
 
diff --git a/src/lib/intmath/weakrng.c b/src/lib/intmath/weakrng.c
index 2ecab97cc1..36cf5fb0aa 100644
--- a/src/lib/intmath/weakrng.c
+++ b/src/lib/intmath/weakrng.c
@@ -3,6 +3,15 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file weakrng.c
+ *
+ * \brief A weak but fast PRNG based on a linear congruential generator.
+ *
+ * We don't want to use the platform random(), since some of them are even
+ * worse than this.
+ **/
+
 #include "lib/intmath/weakrng.h"
 #include "lib/err/torerr.h"
 
diff --git a/src/lib/intmath/weakrng.h b/src/lib/intmath/weakrng.h
index e5a88b30fe..679bf2449c 100644
--- a/src/lib/intmath/weakrng.h
+++ b/src/lib/intmath/weakrng.h
@@ -3,6 +3,12 @@
  * Copyright (c) 2007-2018, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
+/**
+ * \file weakrng.h
+ *
+ * \brief Header for weakrng.c
+ **/
+
 #ifndef TOR_WEAKRNG_H
 #define TOR_WEAKRNG_H