Improve documentation

The Cosmo API documentation page is pretty good now
https://justine.lol/cosmopolitan/documentation.html

libc/mem/balloc.c

@@ -20,24 +20,19 @@
 #include "libc/mem/mem.h"
 #include "libc/runtime/buffer.h"
 
-/* TODO(jart): Delete */
-
 #define kGuard PAGESIZE
 #define kGrain FRAMESIZE
 
 /**
  * Allocates page-guarded buffer.
  *
- *     ┌─────────────────────────────────────┬s─i─g─s─e─g─v┐
- *     │   𝑣₀..𝑣ₙ₋₁                          │𝑣ₙ..𝑣ₙ₊₄₀₉₆₋₁│
- *     └─────────────────────────────────────┴s─i─g─s─e─g─v┘
- *
  * @param b is metadata object owned by caller, initialized to zero for
  *     first call; subsequent calls will resize
  * @param a is alignment requirement in bytes, e.g. 1,2,4,8,16,...
  * @param n is buffer size in bytes
  * @return b->p
  * @see ralloc()
+ * @deprecated
  */
 void *balloc(struct GuardedBuffer *b, unsigned a, size_t n) {
   return (b->p = memalign(a, n));

libc/mem/bfree.c

@@ -22,8 +22,10 @@
 #include "libc/mem/mem.h"
 #include "libc/runtime/buffer.h"
 
-/* TODO(jart): Delete */
-
+/**
+ * Frees memory return by balloc().
+ * @deprecated
+ */
 void bfree(struct GuardedBuffer *b) {
   free(b->p);
 }

libc/mem/cxx/free.S

@@ -22,9 +22,9 @@
 
 /	Frees memory the C++ way.
 /
-/	@param	%rdi is pointer, or NULL for no-op
-/	@param	%rsi is ignored
-/	@param	%rdx is ignored
+/	\param	%rdi is pointer, or NULL for no-op
+/	\param	%rsi is ignored
+/	\param	%rdx is ignored
 _ZdlPvSt11align_val_tRKSt9nothrow_t:
 /	operator delete(void*, std::align_val_t, std::nothrow_t const&)
 	nop

libc/mem/cxx/malloc.S

@@ -22,9 +22,9 @@
 
 /	Allocates memory the C++ way.
 /
-/	@param	%rdi is bytes to allocate
-/	@param	%rsi is ignored
-/	@return	new memory or NULL on OOM
+/	\param	%rdi is bytes to allocate
+/	\param	%rsi is ignored
+/	\return	new memory or NULL on OOM
 _ZnamRKSt9nothrow_t:
 /	operator new[](unsigned long, std::nothrow_t const&)
 	nop

libc/mem/cxx/memalign.S

@@ -22,10 +22,10 @@
 
 /	Allocates aligned memory the C++ way.
 /
-/	@param	%rdi is bytes to allocate
-/	@param	%rsi is byte alignment
-/	@param	%rdx is ignored
-/	@return	new memory or NULL on OOM
+/	\param	%rdi is bytes to allocate
+/	\param	%rsi is byte alignment
+/	\param	%rdx is ignored
+/	\return	new memory or NULL on OOM
 _ZnamSt11align_val_tRKSt9nothrow_t:
 /	operator new[](unsigned long, std::align_val_t, std::nothrow_t const&)
 	nop

libc/mem/internal.h

@@ -3,7 +3,7 @@
 #if !(__ASSEMBLER__ + __LINKER__ + 0)
 COSMOPOLITAN_C_START_
 
-int PutEnvImpl(char *string, bool overwrite) hidden;
+int PutEnvImpl(char *, bool) hidden;
 
 COSMOPOLITAN_C_END_
 #endif /* !(__ASSEMBLER__ + __LINKER__ + 0) */

libc/mem/realloc.S

@@ -36,12 +36,12 @@
 /
 /	Please note that p is NOT free()'d should realloc() fail, thus:
 /
-/	  if ((p2 = realloc(p, n2))) {
-/	    p = p2;
-/	    ...
-/	  } else {
-/	    ...
-/	  }
+/	    if ((p2 = realloc(p, n2))) {
+/	      p = p2;
+/	      ...
+/	    } else {
+/	      ...
+/	    }
 /
 /	if n is for fewer bytes than already held by p, the newly unused
 /	space is lopped off and freed if possible.

libc/mem/wcsdup.c

@@ -20,6 +20,9 @@
 #include "libc/mem/mem.h"
 #include "libc/str/str.h"
 
+/**
+ * Allocates copy of wide string.
+ */
 wchar_t *wcsdup(const wchar_t *s) {
   size_t len = wcslen(s);
   char *s2 = malloc(len * sizeof(wchar_t) + 1);