diff -r c73c39a59dd4 -r 006194daea99 mojoshader.h
--- a/mojoshader.h	Sat May 28 11:55:07 2016 -0400
+++ b/mojoshader.h	Sat May 28 15:58:05 2016 -0400
@@ -467,6 +467,9 @@
     MOJOSHADER_preshaderInstruction *instructions;
     unsigned int register_count;
     float *registers;
+    MOJOSHADER_malloc malloc;
+    MOJOSHADER_free free;
+    void *malloc_data;
 } MOJOSHADER_preshader;
 
 /*
@@ -801,7 +804,27 @@
 DECLSPEC void MOJOSHADER_freeParseData(const MOJOSHADER_parseData *data);
 
 
-/* !!! FIXME: document me. */
+/*
+ * You almost certainly don't need this function, unless you absolutely know
+ *  why you need it without hesitation. This is useful if you're doing
+ *  extremely low-level shader work or building specialized tools.
+ *
+ * Parse a preshader structure. This expects a buffer of bytes that represents
+ *  the preshader data starting with its magic number token and ending at
+ *  the end of the comment tokens that contain this preshader. Note that it
+ *  does _not_ start at the beginning of the comment tokens.
+ *
+ * On success, this will return a MOJOSHADER_preshader. This can be
+ *  deallocated later by calling MOJOSHADER_freePreshader(). On failure,
+ *  this will return NULL. Unlike other MojoShader APIs, this assumes you
+ *  either have a complete and valid buffer of preshader tokens or you have
+ *  incomplete/corrupted data, so there is no explicit error reporting. Please
+ *  note that if the system runs out of memory, this function will also return
+ *  NULL without distinction.
+ *
+ * This function is thread safe, so long as any allocator you passed into
+ *  MOJOSHADER_parsePreshader() is, too.
+ */
 DECLSPEC const MOJOSHADER_preshader *MOJOSHADER_parsePreshader(const unsigned char *buf,
                                                                const unsigned int len,
                                                                MOJOSHADER_malloc m,
@@ -809,10 +832,26 @@
                                                                void *d);
 
 
-/* !!! FIXME: document me. */
-DECLSPEC void MOJOSHADER_freePreshader(const MOJOSHADER_preshader *preshader,
-                                       MOJOSHADER_free f,
-                                       void *d);
+/*
+ * You almost certainly don't need this function, unless you absolutely know
+ *  why you need it without hesitation. This is useful if you're doing
+ *  extremely low-level shader work or building specialized tools.
+ *
+ * Call this to dispose of preshader parsing results when you are done with
+ *  them. This will call the MOJOSHADER_free function you provided to
+ *  MOJOSHADER_parsePreshader() multiple times, if you provided one.
+ *  Passing a NULL here is a safe no-op.
+ *
+ * You only need to call this function for results from a call to
+ *  MOJOSHADER_parsePreshader(). Other MojoShader structures with a preshader
+ *  field, such as MOJOSHADER_parseData(), should not use this function, as
+ *  the preshader will be deallocated with everything else in
+ *  MOJOSHADER_freeParseData(), etc.
+ *
+ * This function is thread safe, so long as any allocator you passed into
+ *  MOJOSHADER_parsePreshader() is, too.
+ */
+DECLSPEC void MOJOSHADER_freePreshader(const MOJOSHADER_preshader *preshader);
 
 
 /* Effects interface... */