From de73ab498d640a6cb22924ed2a96613406c58d1b Mon Sep 17 00:00:00 2001
From: Pavel Charvat <pchar@ucw.cz>
Date: Mon, 10 Nov 2008 14:12:46 +0100
Subject: [PATCH] Doc: Described prime.h.

---
 ucw/doc/Makefile  |  2 +-
 ucw/doc/index.txt |  3 +--
 ucw/doc/prime.txt |  7 +++++++
 ucw/prime.h       | 20 ++++++++++++++++++++
 4 files changed, 29 insertions(+), 3 deletions(-)
 create mode 100644 ucw/doc/prime.txt

diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile
index e5a4c926..253bd3d2 100644
--- a/ucw/doc/Makefile
+++ b/ucw/doc/Makefile
@@ -2,7 +2,7 @@
 
 DIRS+=ucw/doc
 
-UCW_DOCS=fastbuf index config configure install basecode hash docsys conf mempool eltpool mainloop generic growbuf unaligned lists chartype unicode
+UCW_DOCS=fastbuf index config configure install basecode hash docsys conf mempool eltpool mainloop generic growbuf unaligned lists chartype unicode prime
 UCW_INDEX=$(o)/ucw/doc/def_index.html
 UCW_DOCS_HTML=$(addprefix $(o)/ucw/doc/,$(addsuffix .html,$(UCW_DOCS)))
 
diff --git a/ucw/doc/index.txt b/ucw/doc/index.txt
index e254a9a6..60e2b93e 100644
--- a/ucw/doc/index.txt
+++ b/ucw/doc/index.txt
@@ -26,6 +26,7 @@ Modules
 - <<growbuf:,Growing buffers>>
 - <<chartype:,Single-byte characters>>
 - <<unicode:,Multi-byte characters>>
+- <<prime:,Prime numbers>>
 
 Other features
 --------------
@@ -40,8 +41,6 @@ Yet undocumented modules
   * `sorter/`
 - Binary search
   * `binsearch.h`
-- Primes
-  * `prime.h`
 - Heaps
   * `binheap.h`
   * `binheap-node.h`
diff --git a/ucw/doc/prime.txt b/ucw/doc/prime.txt
new file mode 100644
index 00000000..2666de9f
--- /dev/null
+++ b/ucw/doc/prime.txt
@@ -0,0 +1,7 @@
+Prime numbers
+=============
+
+The library defines some simple functions to generate prime numbers.
+They are useful for example in hash tables.
+
+!!ucw/prime.h
diff --git a/ucw/prime.h b/ucw/prime.h
index 9ca2a01e..87d13f92 100644
--- a/ucw/prime.h
+++ b/ucw/prime.h
@@ -21,12 +21,32 @@
 
 /* prime.c */
 
+/**
+ * Return a non-zero value iff @x is a prime number.
+ * The time complexity is `O(sqrt(x))`.
+ **/
 int isprime(uns x);
+
+/**
+ * Return some prime greater than @x. The function does not checks overflows, but it should
+ * be safe at least for @x lower than `1U << 31`.
+ * If the Cramer's conjecture is true, it should have complexity `O(sqrt(x) * log(x)^2)`.
+ **/
 uns nextprime(uns x);
 
 /* primetable.c */
 
+/**
+ * Quickly lookup a precomputed table to return a prime number greater than @x.
+ * Returns zero if there is no such prime (we guarantee the existance of at
+ * least one prime greater than `1U << 31` in the table).
+ **/
 uns next_table_prime(uns x);
+
+/**
+ * Quickly lookup a precomputed table to return a prime number smaller than @x.
+ * Returns zero if @x is smaller than `7`.
+ **/
 uns prev_table_prime(uns x);
 
 #endif // _UCW_PRIME_H
-- 
2.39.5