3 files changed, 41 insertions, 0 deletions

diff --git a/src/ctype.c b/src/ctype.c
index 2c8fe83..3923def 100644
--- a/src/ctype.c
+++ b/src/ctype.c
@@ -268,6 +268,12 @@ int _toupper(int c)
 
 
 
+/**
+ * Create a variant, with specifiable locale,
+ * of one of the functions.
+ * 
+ * @param  The name of the function without the `_l`-suffix.
+ */
 #define CTYPE_LOCALE(F)			\
   int F##_l(int c, locale_t locale)	\
   {					\
diff --git a/src/slibc-alloc.c b/src/slibc-alloc.c
index 604eff1..a7ae30a 100644
--- a/src/slibc-alloc.c
+++ b/src/slibc-alloc.c
@@ -25,8 +25,31 @@
 
 
 
+/**
+ * Get the alignment-shift of a pointer.
+ * 
+ * @param   p:void*  The pointer.
+ * @return  :size_t  The number of bytes added for alignment.
+ *                   This excludes the information this macro
+ *                   reads, and the storage of the allocation-size.
+ */
 #define __ALIGN(p)      (*(size_t*)(((char*)(p)) - sizeof(size_t)))
+
+/**
+ * Get the allocated pointer from a returned pointer.
+ * 
+ * @param   p:void*  The pointer returned by a `malloc`-family function.
+ * @return           The pointer allocated by a `malloc`-family function.
+ */
 #define PURE_ALLOC(p)   (((char*)(p)) - (__ALIGN(p) + 2 * sizeof(size_t)))
+
+/**
+ * Get the real allocation is of a pointer, including
+ * the size of the metadata storage and the alignment-padding.
+ * 
+ * @param   p:void*  The pointer.
+ * @return  :size_t  The real allocation size of the pointer.
+ */
 #define PURE_SIZE(p)    (*(size_t*)PURE_ALLOC(p) + 2 * sizeof(size_t))
 
 
diff --git a/src/string/substring.h b/src/string/substring.h
index 9d6dbfe..05ef7cc 100644
--- a/src/string/substring.h
+++ b/src/string/substring.h
@@ -30,6 +30,16 @@
 /* The Knuth–Morris–Pratt algorithm. */
 
 
+/**
+ * Test whether to characters are equal.
+ * Case-sensitivity depends on `CASE` being defined.
+ * 
+ * @param   a  One of the characters.
+ * @param   b  The other character.
+ * @return     1 if `a` and `b` or equal, 0 otherwise.
+ *             The comparison is case-insensitive if
+ *             `CASE` is defined.
+ */
 #if !defined(CASE)
 # define CHREQ(a, b)  (a == b)
 #elif !defined(WIDE)
@@ -42,6 +52,8 @@
 /* TODO add support for RIGHT */
 
 
+/* The implementation of the algorithm, read
+ * elsewhere for documentation/explanation. */
 {
   ssize_t* next_map = alloca((needle_length + 1) * sizeof(ssize_t));
   ssize_t hay, ned, skp;