etymology for some functions

Signed-off-by: Mattias Andrée <maandree@operamail.com>

9 files changed, 54 insertions, 2 deletions

diff --git a/src/ctype.c b/src/ctype.c
index 3923def..a5eb75c 100644
--- a/src/ctype.c
+++ b/src/ctype.c
@@ -23,6 +23,8 @@
  * Check whether a character is an alphabetical
  * character or a decimal digit.
  * 
+ * @etymology  (Is) character either (al)phabetical or (num)erical [(al)pha(num)erical]?
+ * 
  * @param   c  The character.
  * @return     Whether the character is in
  *             ['0', '9'], ['A', 'Z'], or ['a', 'z'].
@@ -36,6 +38,8 @@ int (isalnum)(int c)
 /**
  * Check whether a character is an alphabetical character.
  * 
+ * @etymology  (Is) character (alpha)betical?
+ * 
  * @param   c  The character.
  * @return     Whether the character is in
  *             ['A', 'Z'] or ['a', 'z'].
@@ -50,6 +54,8 @@ int (isalpha)(int c)
  * Check whether a character is a regular blank space
  * or a horizontal tabulation.
  * 
+ * @etymology  (Is) character a (blank) space?
+ * 
  * @param   c  The character.
  * @return     Whether the character is a ' ' or a '\t'.
  */
@@ -63,6 +69,8 @@ int (isblank)(int c)
  * Check whether a character is a non-printable
  * ASCII character.
  * 
+ * @etymology  (Is) character a (c)o(ntr)o(l) character?
+ * 
  * @param   c  The character.
  * @return     Whether the character is lower than ' '.
  */
@@ -75,6 +83,8 @@ int (iscntrl)(int c)
 /**
  * Check whether a character is a decimal digit.
  * 
+ * @etymology  (Is) character a (digit)?
+ * 
  * @param   c  The character.
  * @return     Whether the character is in ['0', '9'].
  */
@@ -87,6 +97,8 @@ int (isdigit)(int c)
 /**
  * Check whether a character is has a printable glyph.
  * 
+ * @etymology  (Is) character (graph)ical?
+ * 
  * @param   c  The character.
  * @return     Whether the character is greater than ' '.
  */
@@ -100,6 +112,8 @@ int (isgraph)(int c)
  * Check whether a character is a lowercase
  * alphabetical character.
  * 
+ * @etymology  (Is) character a (lower)case character?
+ * 
  * @param   c  The character.
  * @return     Whether the character is in ['a', 'z'].
  */
@@ -113,6 +127,8 @@ int (islower)(int c)
  * Check whether a character is has a printable glyph
  * or a blank space.
  * 
+ * @etymology  (Is) character (print)able?
+ * 
  * @param   c  The character.
  * @return     Whether the character is at least
  *             as great as ' '.
@@ -128,6 +144,8 @@ int (isprint)(int c)
  * that is, a printable character but a blank space,
  * numerical or alphabetical.
  * 
+ * @etymology  (Is) character a (punct)uation?
+ * 
  * @param   c  The character.
  * @return     Whether the character is a punctuation.
  */
@@ -140,6 +158,8 @@ int (ispunct)(int c)
 /**
  * Check whether a character is a whitespace character.
  * 
+ * @etymology  (Is) character white(space)?
+ * 
  * @param   c  The character.
  * @return     Whether the character is a ' ', '\f',
  *             '\n', '\r', '\t', or '\v'.
@@ -154,6 +174,8 @@ int (isspace)(int c)
  * Check whether a character is an uppercase
  * alphabetical character.
  * 
+ * @etymology  (Is) character a (upper)case character?
+ * 
  * @param   c  The character.
  * @return     Whether the character is in ['A', 'Z'].
  */
@@ -168,6 +190,8 @@ int (isupper)(int c)
  * hexadecimal digit. Both uppercase and
  * lowercase is supported.
  * 
+ * @etymology  (Is) character a he(x)adecimal digit?
+ * 
  * @param   c  The character.
  * @return     Whether the character is in
  *             ['0', '9'], ['A', 'Z'], or ['a', 'z'].
@@ -183,11 +207,13 @@ int (isxdigit)(int c)
  * Convert a uppercase ASCII character to
  * an lowercase ASCII character.
  * 
- * The function's behaviour is unspecifed
+ * The function's behaviour is unspecified
  * of the character is not alphabetical.
  * You should consider running
  * `(isupper(c) ? tolower(c) : c)` instead.
  * 
+ * @etymology  Convert character (to) (lower)case!
+ * 
  * @param   c  The character.
  * @return     The character in lowercase.
  *             Guaranteed to be unchanged if the
@@ -203,11 +229,13 @@ int (tolower)(int c)
  * Convert a lowercase ASCII character to
  * an uppercase ASCII character.
  * 
- * The function's behaviour is unspecifed
+ * The function's behaviour is unspecified
  * of the character is not alphabetical.
  * You should consider running
  * `(isupper(c) ? tolower(c) : c)` instead.
  * 
+ * @etymology  Convert character (to) (upper)case!
+ * 
  * @param   c  The character.
  * @return     The character in uppercase.
  *             Guaranteed to be unchanged if the
@@ -223,6 +251,8 @@ int (toupper)(int c)
 /**
  * Check whether a character is an ASCII character.
  * 
+ * @etymology  (Is) character an (ASCII) character?
+ * 
  * @param   c  The character
  * @return     Whether the character is an ASCII character.
  */
@@ -238,6 +268,12 @@ int (isascii)(int c)
  * Note that this does not make a proper character set
  * convertion and the result is virtually arbitrary.
  * 
+ * Justification for existence:
+ *   The highest bit has historically been used as a
+ *   parity bit.
+ * 
+ * @etymology  Truncate character (to) fit (ASCII) character set!
+ * 
  * @param   c  The character.
  * @return     The character with the 8:th bit cleared.
  */
diff --git a/src/err/err.c b/src/err/err.c
index 64062b8..d6d754a 100644
--- a/src/err/err.c
+++ b/src/err/err.c
@@ -26,6 +26,8 @@
  * 
  * This is a non-standard BSD extension.
  * 
+ * @etymology  Report (err)or!
+ * 
  * @parma  status  The exit status the process should have.
  * @param  format  Formatting-string for the warning.
  * @param  ...     Formatting-arguments.
diff --git a/src/err/errx.c b/src/err/errx.c
index 07b4e2b..c8e11c9 100644
--- a/src/err/errx.c
+++ b/src/err/errx.c
@@ -26,6 +26,8 @@
  * 
  * This is a non-standard BSD extension.
  * 
+ * @etymology  (`err`), [x=](lesser variant).
+ * 
  * @parma  status  The exit status the process should have.
  * @param  format  Formatting-string for the warning.
  * @param  ...     Formatting-arguments.
diff --git a/src/err/verr.c b/src/err/verr.c
index f0fb3f7..f88d944 100644
--- a/src/err/verr.c
+++ b/src/err/verr.c
@@ -28,6 +28,8 @@
  * 
  * This is a non-standard BSD extension.
  * 
+ * @etymology  (V)ariadic version of (`err`).
+ * 
  * @parma  status  The exit status the process should have.
  * @param  format  Formatting-string for the warning.
  * @param  args    Formatting-arguments.
diff --git a/src/err/verrx.c b/src/err/verrx.c
index ab30380..1c9e40c 100644
--- a/src/err/verrx.c
+++ b/src/err/verrx.c
@@ -27,6 +27,8 @@
  * 
  * This is a non-standard BSD extension.
  * 
+ * @etymology  (V)ariadic version of (`errx`).
+ * 
  * @parma  status  The exit status the process should have.
  * @param  format  Formatting-string for the warning.
  * @param  args    Formatting-arguments.
diff --git a/src/err/vwarn.c b/src/err/vwarn.c
index 43949e5..78676d4 100644
--- a/src/err/vwarn.c
+++ b/src/err/vwarn.c
@@ -26,6 +26,8 @@
  * 
  * This is a non-standard BSD extension.
  * 
+ * @etymology  (V)ariadic version of (`warn`).
+ * 
  * @param  format  Formatting-string for the warning.
  * @param  args    Formatting-arguments.
  */
diff --git a/src/err/vwarnx.c b/src/err/vwarnx.c
index 594dfc7..c44e57a 100644
--- a/src/err/vwarnx.c
+++ b/src/err/vwarnx.c
@@ -25,6 +25,8 @@
  * 
  * This is a non-standard BSD extension.
  * 
+ * @etymology  (V)ariadic version of (`warnx`).
+ * 
  * @param  format  Formatting-string for the warning.
  * @param  args    Formatting-arguments.
  */
diff --git a/src/err/warn.c b/src/err/warn.c
index ea5aacb..de5c793 100644
--- a/src/err/warn.c
+++ b/src/err/warn.c
@@ -26,6 +26,8 @@
  * 
  * This is a non-standard BSD extension.
  * 
+ * @etymology  Print (warn)ing!
+ * 
  * @param  format  Formatting-string for the warning.
  * @param  ...     Formatting-arguments.
  */
diff --git a/src/err/warnx.c b/src/err/warnx.c
index 835044a..d80dfd8 100644
--- a/src/err/warnx.c
+++ b/src/err/warnx.c
@@ -26,6 +26,8 @@
  * 
  * This is a non-standard BSD extension.
  * 
+ * @etymology  (`warn`), [x=](lesser variant).
+ * 
  * @param  format  Formatting-string for the warning.
  * @param  ...     Formatting-arguments.
  */