Auto-generate some documentation

libc/bits/abs.c

@@ -20,6 +20,9 @@
 #include "libc/fmt/conv.h"
 #include "libc/macros.h"
 
+/**
+ * Returns absolute value of x.
+ */
 int(abs)(int x) {
   return ABS(x);
 }

libc/bits/bitreverse16.c

@@ -19,6 +19,9 @@
 ╚─────────────────────────────────────────────────────────────────────────────*/
 #include "libc/bits/bits.h"
 
+/**
+ * Reverses bits in 16-bit word.
+ */
 uint16_t(bitreverse16)(uint16_t x) {
   return kReverseBits[x & 0x00FF] << 8 | kReverseBits[(x & 0xFF00) >> 8];
 }

libc/bits/bitreverse32.c

@@ -20,6 +20,9 @@
 #include "libc/bits/bits.h"
 #include "libc/bits/bswap.h"
 
+/**
+ * Reverses bits in 32-bit word.
+ */
 uint32_t(bitreverse32)(uint32_t x) {
   x = bswap_32(x);
   x = ((x & 0xaaaaaaaa) >> 1) | ((x & 0x55555555) << 1);

libc/bits/bitreverse64.c

@@ -20,6 +20,9 @@
 #include "libc/bits/bits.h"
 #include "libc/bits/bswap.h"
 
+/**
+ * Reverses bits in 64-bit word.
+ */
 uint64_t bitreverse64(uint64_t x) {
   x = bswap_64(x);
   x = ((x & 0xaaaaaaaaaaaaaaaa) >> 1) | ((x & 0x5555555555555555) << 1);

libc/bits/bitreverse8.c

@@ -19,6 +19,9 @@
 ╚─────────────────────────────────────────────────────────────────────────────*/
 #include "libc/bits/bits.h"
 
+/**
+ * Reverses bits in 8-bit word.
+ */
 uint8_t(bitreverse8)(uint8_t x) {
   return kReverseBits[x];
 }

libc/bits/emptytonull.c

@@ -17,5 +17,12 @@
 │ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA                │
 │ 02110-1301 USA                                                               │
 ╚─────────────────────────────────────────────────────────────────────────────*/
+#include "libc/bits/safemacros.internal.h"
 
-const char *emptytonull(const char *s) { return s && !*s ? 0 : s; }
+/**
+ * Returns string where empty string is made null.
+ * @see nulltoempty()
+ */
+const char *(emptytonull)(const char *s) {
+  return s && !*s ? 0 : s;
+}

libc/bits/firstnonnull.c

@@ -19,6 +19,9 @@
 ╚─────────────────────────────────────────────────────────────────────────────*/
 #include "libc/runtime/runtime.h"
 
+/**
+ * Returns a or b or aborts if both are null.
+ */
 const char *(firstnonnull)(const char *a, const char *b) {
   if (a) return a;
   if (b) return b;

libc/bits/gray.c

@@ -19,6 +19,11 @@
 ╚─────────────────────────────────────────────────────────────────────────────*/
 #include "libc/bits/bits.h"
 
+/**
+ * Returns gray code for x.
+ * @see https://en.wikipedia.org/wiki/Gray_code
+ * @see ungray()
+ */
 uint32_t gray(uint32_t x) {
   return x ^ (x >> 1);
 }

libc/bits/hamming.c

@@ -21,6 +21,7 @@
 
 /**
  * Counts number of different bits.
+ * @see https://en.wikipedia.org/wiki/Hamming_code
  */
 unsigned long hamming(unsigned long x, unsigned long y) {
   return popcnt(x ^ y);

libc/bits/hilbert.c

@@ -36,7 +36,8 @@ static axdx_t RotateQuadrant(long n, long y, long x, long ry, long rx) {
 /**
  * Generates Hilbert space-filling curve.
  *
- * @see morton()
+ * @see https://en.wikipedia.org/wiki/Hilbert_curve
+ * @see unhilbert()
  */
 long hilbert(long n, long y, long x) {
   axdx_t m;
@@ -56,7 +57,8 @@ long hilbert(long n, long y, long x) {
 /**
  * Decodes Hilbert space-filling curve.
  *
- * @see unmorton()
+ * @see https://en.wikipedia.org/wiki/Hilbert_curve
+ * @see hilbert()
  */
 axdx_t unhilbert(long n, long i) {
   axdx_t m;

libc/bits/isempty.c

@@ -18,4 +18,9 @@
 │ 02110-1301 USA                                                               │
 ╚─────────────────────────────────────────────────────────────────────────────*/
 
-bool isempty(const char *s) { return !s || !*s; }
+/**
+ * Returns true if s is empty string or null.
+ */
+bool isempty(const char *s) {
+  return !s || !*s;
+}

libc/bits/morton.c

@@ -21,6 +21,8 @@
 
 /**
  * Interleaves bits.
+ * @see https://en.wikipedia.org/wiki/Z-order_curve
+ * @see unmorton()
  */
 unsigned long(morton)(unsigned long y, unsigned long x) {
   x = (x | x << 020) & 0x0000FFFF0000FFFF;

libc/bits/nulltoempty.c

@@ -17,5 +17,12 @@
 │ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA                │
 │ 02110-1301 USA                                                               │
 ╚─────────────────────────────────────────────────────────────────────────────*/
+#include "libc/bits/safemacros.internal.h"
 
-const char *nulltoempty(const char *s) { return s ? s : ""; }
+/**
+ * Returns 𝑠 converting null to empty string.
+ * @see emptytonull()
+ */
+const char *(nulltoempty)(const char *s) {
+  return s ? s : "";
+}

libc/bits/popcnt.c

@@ -19,6 +19,9 @@
 ╚─────────────────────────────────────────────────────────────────────────────*/
 #include "libc/bits/popcnt.h"
 
+/**
+ * Returns number of bits set in integer.
+ */
 uint64_t(popcnt)(uint64_t x) {
   x = x - ((x >> 1) & 0x5555555555555555);
   x = ((x >> 2) & 0x3333333333333333) + (x & 0x3333333333333333);

libc/bits/pushpop.h

@@ -3,13 +3,13 @@
 #include "libc/macros.h"
 #if !(__ASSEMBLER__ + __LINKER__ + 0)
 
+#if !defined(__GNUC__) || defined(__STRICT_ANSI__)
+#define pushpop(x) (x)
+#else
 /**
  * PushPop
  * An elegant weapon for a more civilized age.
  */
-#if !defined(__GNUC__) || defined(__STRICT_ANSI__)
-#define pushpop(x) (x)
-#else
 #define pushpop(x)                                          \
   ({                                                        \
     typeof(x) Popped;                                       \

libc/bits/rounddown.c

@@ -19,4 +19,9 @@
 ╚─────────────────────────────────────────────────────────────────────────────*/
 #include "libc/macros.h"
 
-long(rounddown)(long w, long k) { return ROUNDDOWN(w, k); }
+/**
+ * Rounds down 𝑤 to next two power 𝑘.
+ */
+long(rounddown)(long w, long k) {
+  return ROUNDDOWN(w, k);
+}

libc/bits/roundup.c

@@ -19,6 +19,9 @@
 ╚─────────────────────────────────────────────────────────────────────────────*/
 #include "libc/macros.h"
 
+/**
+ * Rounds up 𝑤 to next two power 𝑘.
+ */
 long(roundup)(long w, long k) {
   return ROUNDUP(w, k);
 }

libc/bits/roundup2log.c

@@ -22,7 +22,7 @@
 
 /**
  * Returns 𝑥 rounded up to next two power and log'd.
- * @see roundup2pow
+ * @see roundup2pow()
  */
 unsigned long roundup2log(unsigned long x) {
   return x > 1 ? (bsrl(x - 1) + 1) : x ? 1 : 0;

libc/bits/roundup2pow.c

@@ -24,7 +24,7 @@
  * Returns 𝑥 rounded up to next two power.
  *
  * @define (𝑥>0→2^⌈log₂x⌉, x=0→0, 𝑇→⊥)
- * @see rounddown2pow)()
+ * @see rounddown2pow()
  */
 unsigned long roundup2pow(unsigned long x) {
   return x > 1 ? 1ul << (bsrl(x - 1) + 1) : x ? 1 : 0;

libc/bits/ungray.c

@@ -19,6 +19,11 @@
 ╚─────────────────────────────────────────────────────────────────────────────*/
 #include "libc/bits/bits.h"
 
+/**
+ * Decodes gray code.
+ * @see https://en.wikipedia.org/wiki/Gray_code
+ * @see gray()
+ */
 uint32_t ungray(uint32_t x) {
   x ^= x >> 16;
   x ^= x >> 8;

libc/bits/unmorton.c

@@ -35,6 +35,7 @@ static unsigned long GetOddBits(unsigned long x) {
  * @param 𝑖 is interleaved index
  * @return deinterleaved coordinate {ax := 𝑦, dx := 𝑥}
  * @see en.wikipedia.org/wiki/Z-order_curve
+ * @see morton()
  */
 axdx_t(unmorton)(unsigned long i) {
   return (axdx_t){GetOddBits(i >> 1), GetOddBits(i)};