Add a short description of what each module does
There was already a short introduction to _who_ should use each module, but
not to _what_ each module does.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/library/bignum_core.h b/library/bignum_core.h
index dc802ab..d64111b 100644
--- a/library/bignum_core.h
+++ b/library/bignum_core.h
@@ -6,6 +6,11 @@
* modules should use the high-level modular bignum interface (bignum_mod.h)
* or the legacy bignum interface (bignum.h).
*
+ * This module is about processing non-negative integers with a fixed upper
+ * bound that's of the form 2^#biL-1. Many operations treat these numbers
+ * as the principal representation of a number modulo 2^#biL or a smaller
+ * bound.
+ *
*/
/*
diff --git a/library/bignum_mod.h b/library/bignum_mod.h
index 982a9ac..c25eb87 100644
--- a/library/bignum_mod.h
+++ b/library/bignum_mod.h
@@ -1,5 +1,7 @@
/**
* Modular bignum functions
+ *
+ * This module implements operations on integers modulo some fixed modulus.
*/
/*
diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h
index aba5d06..aef8a04 100644
--- a/library/bignum_mod_raw.h
+++ b/library/bignum_mod_raw.h
@@ -5,6 +5,12 @@
* module (bignum_mod.c) and the ECP module (ecp.c, ecp_curves.c). All other
* modules should use the high-level modular bignum interface (bignum_mod.h)
* or the legacy bignum interface (bignum.h).
+ *
+ * This is a low-level interface to operations on integers modulo which
+ * has no protection against passing invalid arguments such as arrays of
+ * the wrong size. The functions in bignum_mod.h provide a higher-level
+ * interface that includes protections against accidental misuse, at the
+ * expense of code size and sometimes more cumbersome memory management.
*/
/*