Surround embedded documentation with a macro so it

can be disabled in a future build.

src/core/array.c

@@ -22,6 +22,7 @@
 
 #include <janet/janet.h>
 #include "gc.h"
+#include "util.h"
 #include <string.h>
 
 /* Initializes an array */
@@ -213,50 +214,50 @@ static Janet cfun_insert(int32_t argc, Janet *argv) {
 
 static const JanetReg cfuns[] = {
     {"array/new", cfun_new,
-        "(array/new capacity)\n\n"
+        JDOC("(array/new capacity)\n\n"
                 "Creates a new empty array with a preallocated capacity. The same as "
-        "(array) but can be more efficient if the maximum size of an array is known."
+                "(array) but can be more efficient if the maximum size of an array is known.")
     },
     {"array/pop", cfun_pop,
-        "(array/pop arr)\n\n"
+        JDOC("(array/pop arr)\n\n"
                 "Remove the last element of the array and return it. If the array is empty, will return nil. Modifies "
-        "the input array."
+                "the input array.")
     },
     {"array/peek", cfun_peek,
-        "(array/peek arr)\n\n"
+        JDOC("(array/peek arr)\n\n"
-        "Returns the last element of the array. Does not modify the array."
+                "Returns the last element of the array. Does not modify the array.")
     },
     {"array/push", cfun_push,
-        "(array/push arr x)\n\n"
+        JDOC("(array/push arr x)\n\n"
-        "Insert an element in the end of an array. Modifies the input array and returns it."
+                "Insert an element in the end of an array. Modifies the input array and returns it.")
     },
     {"array/ensure", cfun_ensure,
-        "(array/ensure arr capacity)\n\n"
+        JDOC("(array/ensure arr capacity)\n\n"
                 "Ensures that the memory backing the array has enough memory for capacity "
                 "items. Capacity must be an integer. If the backing capacity is already enough, "
                 "then this function does nothing. Otherwise, the backing memory will be reallocated "
-        "so that there is enough space."
+                "so that there is enough space.")
     },
     {"array/slice", cfun_slice,
-        "(array/slice arrtup [, start=0 [, end=(length arrtup)]])\n\n"
+        JDOC("(array/slice arrtup [, start=0 [, end=(length arrtup)]])\n\n"
                 "Takes a slice of array or tuple from start to end. The range is half open, "
                 "[start, end). Indexes can also be negative, indicating indexing from the end of the "
                 "end of the array. By default, start is 0 and end is the length of the array. "
-        "Returns a new array."
+                "Returns a new array.")
     },
     {"array/concat", cfun_concat,
-        "(array/concat arr & parts)\n\n"
+        JDOC("(array/concat arr & parts)\n\n"
                 "Concatenates a variadic number of arrays (and tuples) into the first argument "
                 "which must an array. If any of the parts are arrays or tuples, their elements will "
                 "be inserted into the array. Otherwise, each part in parts will be appended to arr in order. "
-        "Return the modified array arr."
+                "Return the modified array arr.")
     },
     {"array/insert", cfun_insert,
-        "(array/insert arr at & xs)\n\n"
+        JDOC("(array/insert arr at & xs)\n\n"
                 "Insert all of xs into array arr at index at. at should be an integer "
                 "0 and the length of the array. A negative value for at will index from "
                 "the end of the array, such that inserting at -1 appends to the array. "
-        "Returns the array."
+                "Returns the array.")
     },
     {NULL, NULL, NULL}
 };

src/core/asm.c

@@ -932,16 +932,16 @@ static Janet cfun_disasm(int32_t argc, Janet *argv) {
 
 static const JanetReg cfuns[] = {
     {"asm", cfun_asm,
-        "(asm assembly)\n\n"
+        JDOC("(asm assembly)\n\n"
                 "Returns a new function that is the compiled result of the assembly.\n"
                 "The syntax for the assembly can be found on the janet wiki. Will throw an\n"
-        "error on invalid assembly."
+                "error on invalid assembly.")
     },
     {"disasm", cfun_disasm,
-        "(disasm func)\n\n"
+        JDOC("(disasm func)\n\n"
                 "Returns assembly that could be used be compile the given function.\n"
                 "func must be a function, not a c function. Will throw on error on a badly\n"
-        "typed argument."
+                "typed argument.")
     },
     {NULL, NULL, NULL}
 };

src/core/buffer.c

@@ -22,6 +22,7 @@
 
 #include <janet/janet.h>
 #include "gc.h"
+#include "util.h"
 
 /* Initialize a buffer */
 JanetBuffer *janet_buffer_init(JanetBuffer *buffer, int32_t capacity) {
@@ -226,42 +227,42 @@ static Janet cfun_slice(int32_t argc, Janet *argv) {
 
 static const JanetReg cfuns[] = {
     {"buffer/new", cfun_new,
-        "(buffer/new capacity)\n\n"
+        JDOC("(buffer/new capacity)\n\n"
                 "Creates a new, empty buffer with enough memory for capacity bytes. "
-        "Returns a new buffer."
+                "Returns a new buffer.")
     },
     {"buffer/push-byte", cfun_u8,
-        "(buffer/push-byte buffer x)\n\n"
+        JDOC("(buffer/push-byte buffer x)\n\n"
                 "Append a byte to a buffer. Will expand the buffer as necessary. "
-        "Returns the modified buffer. Will throw an error if the buffer overflows."
+                "Returns the modified buffer. Will throw an error if the buffer overflows.")
     },
     {"buffer/push-word", cfun_word,
-        "(buffer/push-word buffer x)\n\n"
+        JDOC("(buffer/push-word buffer x)\n\n"
                 "Append a machine word to a buffer. The 4 bytes of the integer are appended "
                 "in twos complement, big endian order, unsigned. Returns the modified buffer. Will "
-        "throw an error if the buffer overflows."
+                "throw an error if the buffer overflows.")
     },
     {"buffer/push-string", cfun_chars,
-        "(buffer/push-string buffer str)\n\n"
+        JDOC("(buffer/push-string buffer str)\n\n"
                 "Push a string onto the end of a buffer. Non string values will be converted "
                 "to strings before being pushed. Returns the modified buffer. "
-        "Will throw an error if the buffer overflows."
+                "Will throw an error if the buffer overflows.")
     },
     {"buffer/popn", cfun_popn,
-        "(buffer/popn buffer n)\n\n"
+        JDOC("(buffer/popn buffer n)\n\n"
-        "Removes the last n bytes from the buffer. Returns the modified buffer."
+                "Removes the last n bytes from the buffer. Returns the modified buffer.")
     },
     {"buffer/clear", cfun_clear,
-        "(buffer/clear buffer)\n\n"
+        JDOC("(buffer/clear buffer)\n\n"
                 "Sets the size of a buffer to 0 and empties it. The buffer retains "
-        "its memory so it can be efficiently refilled. Returns the modified buffer."
+                "its memory so it can be efficiently refilled. Returns the modified buffer.")
     },
     {"buffer/slice", cfun_slice,
-        "(buffer/slice bytes [, start=0 [, end=(length bytes)]])\n\n"
+        JDOC("(buffer/slice bytes [, start=0 [, end=(length bytes)]])\n\n"
                 "Takes a slice of a byte sequence from start to end. The range is half open, "
                 "[start, end). Indexes can also be negative, indicating indexing from the end of the "
                 "end of the array. By default, start is 0 and end is the length of the buffer. "
-        "Returns a new buffer."
+                "Returns a new buffer.")
     },
     {NULL, NULL, NULL}
 };

src/core/compile.c

@@ -24,6 +24,7 @@
 #include "compile.h"
 #include "emit.h"
 #include "vector.h"
+#include "util.h"
 
 JanetFopts janetc_fopts_default(JanetCompiler *c) {
     JanetFopts ret;
@@ -723,11 +724,11 @@ static Janet cfun(int32_t argc, Janet *argv) {
 
 static const JanetReg cfuns[] = {
     {"compile", cfun,
-        "(compile ast env [, source])\n\n"
+        JDOC("(compile ast env [, source])\n\n"
                 "Compiles an Abstract Sytnax Tree (ast) into a janet function. "
                 "Pair the compile function with parsing functionality to implement "
                 "eval. Returns a janet function and does not modify ast. Throws an "
-        "error if the ast cannot be compiled."
+                "error if the ast cannot be compiled.")
     },
     {NULL, NULL, NULL}
 };

src/core/corelib.c

@@ -250,103 +250,103 @@ static Janet janet_core_hash(int32_t argc, Janet *argv) {
 
 static const JanetReg cfuns[] = {
     {"native", janet_core_native,
-        "(native path [,env])\n\n"
+        JDOC("(native path [,env])\n\n"
                 "Load a native module from the given path. The path "
                 "must be an absolute or relative path on the file system, and is "
                 "usually a .so file on Unix systems, and a .dll file on Windows. "
                 "Returns an environment table that contains functions and other values "
-        "from the native module."
+                "from the native module.")
     },
     {"print", janet_core_print,
-        "(print & xs)\n\n"
+        JDOC("(print & xs)\n\n"
                 "Print values to the console (standard out). Value are converted "
                 "to strings if they are not already. After printing all values, a "
-        "newline character is printed. Returns nil."
+                "newline character is printed. Returns nil.")
     },
     {"describe", janet_core_describe,
-        "(describe x)\n\n"
+        JDOC("(describe x)\n\n"
-        "Returns a string that is a human readable description of a value x."
+                "Returns a string that is a human readable description of a value x.")
     },
     {"string", janet_core_string,
-        "(string & parts)\n\n"
+        JDOC("(string & parts)\n\n"
                 "Creates a string by concatenating values together. Values are "
                 "converted to bytes via describe if they are not byte sequences. "
-        "Returns the new string."
+                "Returns the new string.")
     },
     {"symbol", janet_core_symbol,
-        "(symbol & xs)\n\n"
+        JDOC("(symbol & xs)\n\n"
                 "Creates a symbol by concatenating values together. Values are "
                 "converted to bytes via describe if they are not byte sequences. Returns "
-        "the new symbol."
+                "the new symbol.")
     },
     {"keyword", janet_core_keyword,
-        "(keyword & xs)\n\n"
+        JDOC("(keyword & xs)\n\n"
                 "Creates a keyword by concatenating values together. Values are "
                 "converted to bytes via describe if they are not byte sequences. Returns "
-        "the new keyword."
+                "the new keyword.")
     },
     {"buffer", janet_core_buffer,
-        "(buffer & xs)\n\n"
+        JDOC("(buffer & xs)\n\n"
                 "Creates a new buffer by concatenating values together. Values are "
                 "converted to bytes via describe if they are not byte sequences. Returns "
-        "the new buffer."
+                "the new buffer.")
     },
     {"abstract?", janet_core_is_abstract,
-        "(abstract? x)\n\n"
+        JDOC("(abstract? x)\n\n"
-        "Check if x is an abstract type."
+                "Check if x is an abstract type.")
     },
     {"table", janet_core_table,
-        "(table & kvs)\n\n"
+        JDOC("(table & kvs)\n\n"
                 "Creates a new table from a variadic number of keys and values. "
                 "kvs is a sequence k1, v1, k2, v2, k3, v3, ... If kvs has "
                 "an odd number of elements, an error will be thrown. Returns the "
-        "new table."
+                "new table.")
     },
     {"array", janet_core_array,
-        "(array & items)\n\n"
+        JDOC("(array & items)\n\n"
-        "Create a new array that contains items. Returns the new array."
+                "Create a new array that contains items. Returns the new array.")
     },
     {"scan-number", janet_core_scannumber,
-        "(scan-number str)\n\n"
+        JDOC("(scan-number str)\n\n"
                 "Parse a number from a byte sequence an return that number, either and integer "
                 "or a real. The number "
                 "must be in the same format as numbers in janet source code. Will return nil "
-        "on an invalid number."
+                "on an invalid number.")
     },
     {"tuple", janet_core_tuple,
-        "(tuple & items)\n\n"
+        JDOC("(tuple & items)\n\n"
-        "Creates a new tuple that contains items. Returns the new tuple."
+                "Creates a new tuple that contains items. Returns the new tuple.")
     },
     {"struct", janet_core_struct,
-        "(struct & kvs)\n\n"
+        JDOC("(struct & kvs)\n\n"
                 "Create a new struct from a sequence of key value pairs. "
                 "kvs is a sequence k1, v1, k2, v2, k3, v3, ... If kvs has "
                 "an odd number of elements, an error will be thrown. Returns the "
-        "new struct."
+                "new struct.")
     },
     {"gensym", janet_core_gensym,
-        "(gensym)\n\n"
+        JDOC("(gensym)\n\n"
                 "Returns a new symbol that is unique across the runtime. This means it "
                 "will not collide with any already created symbols during compilation, so "
-        "it can be used in macros to generate automatic bindings."
+                "it can be used in macros to generate automatic bindings.")
     },
     {"gccollect", janet_core_gccollect,
-        "(gccollect)\n\n"
+        JDOC("(gccollect)\n\n"
-        "Run garbage collection. You should probably not call this manually."
+                "Run garbage collection. You should probably not call this manually.")
     },
     {"gcsetinterval", janet_core_gcsetinterval,
-        "(gcsetinterval interval)\n\n"
+        JDOC("(gcsetinterval interval)\n\n"
                 "Set an integer number of bytes to allocate before running garbage collection. "
                 "Low valuesi for interval will be slower but use less memory. "
-        "High values will be faster but use more memory."
+                "High values will be faster but use more memory.")
     },
     {"gcinterval", janet_core_gcinterval,
-        "(gcinterval)\n\n"
+        JDOC("(gcinterval)\n\n"
                 "Returns the integer number of bytes to allocate before running an iteration "
-        "of garbage collection."
+                "of garbage collection.")
     },
     {"type", janet_core_type,
-        "(type x)\n\n"
+        JDOC("(type x)\n\n"
                 "Returns the type of x as a keyword symbol. x is one of\n"
                 "\t:nil\n"
                 "\t:boolean\n"
@@ -362,21 +362,21 @@ static const JanetReg cfuns[] = {
                 "\t:keyword\n"
                 "\t:function\n"
                 "\t:cfunction\n\n"
-        "or another symbol for an abstract type."
+                "or another symbol for an abstract type.")
     },
     {"next", janet_core_next,
-        "(next dict key)\n\n"
+        JDOC("(next dict key)\n\n"
                 "Gets the next key in a struct or table. Can be used to iterate through "
                 "the keys of a data structure in an unspecified order. Keys are guaranteed "
                 "to be seen only once per iteration if they data structure is not mutated "
                 "during iteration. If key is nil, next returns the first key. If next "
-        "returns nil, there are no more keys to iterate through. "
+                "returns nil, there are no more keys to iterate through. ")
     },
     {"hash", janet_core_hash,
-        "(hash value)\n\n"
+        JDOC("(hash value)\n\n"
                 "Gets a hash value for any janet value. The hash is an integer can be used "
                 "as a cheap hash function for all janet objects. If two values are strictly equal, "
-        "then they will have the same hash value."
+                "then they will have the same hash value.")
     },
     {NULL, NULL, NULL}
 };
@@ -559,48 +559,48 @@ static void make_apply(JanetTable *env) {
     };
     janet_quick_asm(env, JANET_FUN_APPLY | JANET_FUNCDEF_FLAG_VARARG,
             "apply", 1, 6, apply_asm, sizeof(apply_asm),
-            "(apply f & args)\n\n"
+            JDOC("(apply f & args)\n\n"
                 "Applies a function to a variable number of arguments. Each element in args "
                 "is used as an argument to f, except the last element in args, which is expected to "
                 "be an array-like. Each element in this last argument is then also pushed as an argument to "
                 "f. For example:\n\n"
                 "\t(apply + 1000 (range 10))\n\n"
-            "sums the first 10 integers and 1000.)");
+                "sums the first 10 integers and 1000.)"));
 }
 
-JanetTable *janet_core_env(void) {
+static const uint32_t error_asm[] = {
-    static const uint32_t error_asm[] = {
     JOP_ERROR
-    };
+};
-    static const uint32_t debug_asm[] = {
+static const uint32_t debug_asm[] = {
    JOP_SIGNAL | (2 << 24),
    JOP_RETURN_NIL
-    };
+};
-    static const uint32_t yield_asm[] = {
+static const uint32_t yield_asm[] = {
     JOP_SIGNAL | (3 << 24),
     JOP_RETURN
-    };
+};
-    static const uint32_t resume_asm[] = {
+static const uint32_t resume_asm[] = {
     JOP_RESUME | (1 << 24),
     JOP_RETURN
-    };
+};
-    static const uint32_t get_asm[] = {
+static const uint32_t get_asm[] = {
     JOP_GET | (1 << 24),
     JOP_RETURN
-    };
+};
-    static const uint32_t put_asm[] = {
+static const uint32_t put_asm[] = {
     JOP_PUT | (1 << 16) | (2 << 24),
     JOP_RETURN
-    };
+};
-    static const uint32_t length_asm[] = {
+static const uint32_t length_asm[] = {
     JOP_LENGTH,
     JOP_RETURN
-    };
+};
-    static const uint32_t bnot_asm[] = {
+static const uint32_t bnot_asm[] = {
     JOP_BNOT,
     JOP_RETURN
-    };
+};
 
+JanetTable *janet_core_env(void) {
     JanetTable *env = janet_table(0);
     Janet ret = janet_wrap_table(env);
 
@@ -608,127 +608,127 @@ JanetTable *janet_core_env(void) {
     janet_cfuns(env, NULL, cfuns);
 
     janet_quick_asm(env, JANET_FUN_YIELD, "debug", 0, 1, debug_asm, sizeof(debug_asm),
-            "(debug)\n\n"
+            JDOC("(debug)\n\n"
                 "Throws a debug signal that can be caught by a parent fiber and used to inspect "
-            "the running state of the current fiber. Returns nil.");
+                "the running state of the current fiber. Returns nil."));
     janet_quick_asm(env, JANET_FUN_ERROR, "error", 1, 1, error_asm, sizeof(error_asm),
-            "(error e)\n\n"
+            JDOC("(error e)\n\n"
-            "Throws an error e that can be caught and handled by a parent fiber.");
+                "Throws an error e that can be caught and handled by a parent fiber."));
     janet_quick_asm(env, JANET_FUN_YIELD, "yield", 1, 2, yield_asm, sizeof(yield_asm),
-            "(yield x)\n\n"
+            JDOC("(yield x)\n\n"
                 "Yield a value to a parent fiber. When a fiber yields, its execution is paused until "
                 "another thread resumes it. The fiber will then resume, and the last yield call will "
-            "return the value that was passed to resume.");
+                "return the value that was passed to resume."));
     janet_quick_asm(env, JANET_FUN_RESUME, "resume", 2, 2, resume_asm, sizeof(resume_asm),
-            "(resume fiber [,x])\n\n"
+            JDOC("(resume fiber [,x])\n\n"
                 "Resume a new or suspended fiber and optionally pass in a value to the fiber that "
                 "will be returned to the last yield in the case of a pending fiber, or the argument to "
                 "the dispatch function in the case of a new fiber. Returns either the return result of "
-            "the fiber's dispatch function, or the value from the next yield call in fiber.");
+                "the fiber's dispatch function, or the value from the next yield call in fiber."));
     janet_quick_asm(env, JANET_FUN_GET, "get", 2, 2, get_asm, sizeof(get_asm),
-            "(get ds key)\n\n"
+            JDOC("(get ds key)\n\n"
                 "Get a value from any associative data structure. Arrays, tuples, tables, structs, strings, "
                 "symbols, and buffers are all associative and can be used with get. Order structures, name "
                 "arrays, tuples, strings, buffers, and symbols must use integer keys. Structs and tables can "
                 "take any value as a key except nil and return a value except nil. Byte sequences will return "
-            "integer representations of bytes as result of a get call.");
+                "integer representations of bytes as result of a get call."));
     janet_quick_asm(env, JANET_FUN_PUT, "put", 3, 3, put_asm, sizeof(put_asm),
-            "(put ds key value)\n\n"
+            JDOC("(put ds key value)\n\n"
                 "Associate a key with a value in any mutable associative data structure. Indexed data structures "
                 "(arrays and buffers) only accept non-negative integer keys, and will expand if an out of bounds "
                 "value is provided. In an array, extra space will be filled with nils, and in a buffer, extra "
                 "space will be filled with 0 bytes. In a table, putting a key that is contained in the table prototype "
                 "will hide the association defined by the prototype, but will not mutate the prototype table. Putting "
-            "a value nil into a table will remove the key from the table. Returns the data structure ds.");
+                "a value nil into a table will remove the key from the table. Returns the data structure ds."));
     janet_quick_asm(env, JANET_FUN_LENGTH, "length", 1, 1, length_asm, sizeof(length_asm),
-            "(length ds)\n\n"
+            JDOC("(length ds)\n\n"
                 "Returns the length or count of a data structure in constant time as an integer. For "
-            "structs and tables, returns the number of key-value pairs in the data structure.");
+                "structs and tables, returns the number of key-value pairs in the data structure."));
     janet_quick_asm(env, JANET_FUN_BNOT, "bnot", 1, 1, bnot_asm, sizeof(bnot_asm),
-            "(bnot x)\n\nReturns the bitwise inverse of integer x.");
+            JDOC("(bnot x)\n\nReturns the bitwise inverse of integer x."));
     make_apply(env);
 
     /* Variadic ops */
     templatize_varop(env, JANET_FUN_ADD, "+", 0, 0, JOP_ADD,
-            "(+ & xs)\n\n"
+            JDOC("(+ & xs)\n\n"
-            "Returns the sum of all xs. xs must be integers or real numbers only. If xs is empty, return 0.");
+            "Returns the sum of all xs. xs must be integers or real numbers only. If xs is empty, return 0."));
     templatize_varop(env, JANET_FUN_SUBTRACT, "-", 0, 0, JOP_SUBTRACT,
-            "(- & xs)\n\n"
+            JDOC("(- & xs)\n\n"
             "Returns the difference of xs. If xs is empty, returns 0. If xs has one element, returns the "
             "negative value of that element. Otherwise, returns the first element in xs minus the sum of "
-            "the rest of the elements.");
+            "the rest of the elements."));
     templatize_varop(env, JANET_FUN_MULTIPLY, "*", 1, 1, JOP_MULTIPLY,
-            "(* & xs)\n\n"
+            JDOC("(* & xs)\n\n"
-            "Returns the product of all elements in xs. If xs is empty, returns 1.");
+            "Returns the product of all elements in xs. If xs is empty, returns 1."));
     templatize_varop(env, JANET_FUN_DIVIDE, "/", 1, 1, JOP_DIVIDE,
-            "(/ & xs)\n\n"
+            JDOC("(/ & xs)\n\n"
             "Returns the quotient of xs. If xs is empty, returns 1. If xs has one value x, returns "
             "the reciprocal of x. Otherwise return the first value of xs repeatedly divided by the remaining "
-            "values. Division by two integers uses truncating division.");
+            "values. Division by two integers uses truncating division."));
     templatize_varop(env, JANET_FUN_BAND, "band", -1, -1, JOP_BAND,
-            "(band & xs)\n\n"
+            JDOC("(band & xs)\n\n"
-            "Returns the bitwise and of all values in xs. Each x in xs must be an integer.");
+            "Returns the bitwise and of all values in xs. Each x in xs must be an integer."));
     templatize_varop(env, JANET_FUN_BOR, "bor", 0, 0, JOP_BOR,
-            "(bor & xs)\n\n"
+            JDOC("(bor & xs)\n\n"
-            "Returns the bitwise or of all values in xs. Each x in xs must be an integer.");
+            "Returns the bitwise or of all values in xs. Each x in xs must be an integer."));
     templatize_varop(env, JANET_FUN_BXOR, "bxor", 0, 0, JOP_BXOR,
-            "(bxor & xs)\n\n"
+            JDOC("(bxor & xs)\n\n"
-            "Returns the bitwise xor of all values in xs. Each in xs must be an integer.");
+            "Returns the bitwise xor of all values in xs. Each in xs must be an integer."));
     templatize_varop(env, JANET_FUN_LSHIFT, "blshift", 1, 1, JOP_SHIFT_LEFT,
-            "(blshift x & shifts)\n\n"
+            JDOC("(blshift x & shifts)\n\n"
             "Returns the value of x bit shifted left by the sum of all values in shifts. x "
-            "and each element in shift must be an integer.");
+            "and each element in shift must be an integer."));
     templatize_varop(env, JANET_FUN_RSHIFT, "brshift", 1, 1, JOP_SHIFT_RIGHT,
-            "(brshift x & shifts)\n\n"
+            JDOC("(brshift x & shifts)\n\n"
             "Returns the value of x bit shifted right by the sum of all values in shifts. x "
-            "and each element in shift must be an integer.");
+            "and each element in shift must be an integer."));
     templatize_varop(env, JANET_FUN_RSHIFTU, "brushift", 1, 1, JOP_SHIFT_RIGHT_UNSIGNED,
-            "(brushift x & shifts)\n\n"
+            JDOC("(brushift x & shifts)\n\n"
             "Returns the value of x bit shifted right by the sum of all values in shifts. x "
             "and each element in shift must be an integer. The sign of x is not preserved, so "
-            "for positive shifts the return value will always be positive.");
+            "for positive shifts the return value will always be positive."));
 
     /* Variadic comparators */
     templatize_comparator(env, JANET_FUN_ORDER_GT, "order>", 0, JOP_GREATER_THAN,
-            "(order> & xs)\n\n"
+            JDOC("(order> & xs)\n\n"
                 "Check if xs is strictly descending according to a total order "
-            "over all values. Returns a boolean.");
+                "over all values. Returns a boolean."));
     templatize_comparator(env, JANET_FUN_ORDER_LT, "order<", 0, JOP_LESS_THAN,
-            "(order< & xs)\n\n"
+            JDOC("(order< & xs)\n\n"
                 "Check if xs is strictly increasing according to a total order "
-            "over all values. Returns a boolean.");
+                "over all values. Returns a boolean."));
     templatize_comparator(env, JANET_FUN_ORDER_GTE, "order>=", 1, JOP_LESS_THAN,
-            "(order>= & xs)\n\n"
+            JDOC("(order>= & xs)\n\n"
                 "Check if xs is not increasing according to a total order "
-            "over all values. Returns a boolean.");
+                "over all values. Returns a boolean."));
     templatize_comparator(env, JANET_FUN_ORDER_LTE, "order<=", 1, JOP_GREATER_THAN,
-            "(order<= & xs)\n\n"
+            JDOC("(order<= & xs)\n\n"
                 "Check if xs is not decreasing according to a total order "
-            "over all values. Returns a boolean.");
+                "over all values. Returns a boolean."));
     templatize_comparator(env, JANET_FUN_ORDER_EQ, "=", 0, JOP_EQUALS,
-            "(= & xs)\n\n"
+            JDOC("(= & xs)\n\n"
-            "Returns true if all values in xs are the same, false otherwise.");
+                "Returns true if all values in xs are the same, false otherwise."));
     templatize_comparator(env, JANET_FUN_ORDER_NEQ, "not=", 1, JOP_EQUALS,
-            "(not= & xs)\n\n"
+            JDOC("(not= & xs)\n\n"
-            "Return true if any values in xs are not equal, otherwise false.");
+                "Return true if any values in xs are not equal, otherwise false."));
     templatize_comparator(env, JANET_FUN_GT, ">", 0, JOP_NUMERIC_GREATER_THAN,
-            "(> & xs)\n\n"
+            JDOC("(> & xs)\n\n"
-            "Check if xs is in numerically descending order. Returns a boolean.");
+                "Check if xs is in numerically descending order. Returns a boolean."));
     templatize_comparator(env, JANET_FUN_LT, "<", 0, JOP_NUMERIC_LESS_THAN,
-            "(< & xs)\n\n"
+            JDOC("(< & xs)\n\n"
-            "Check if xs is in numerically ascending order. Returns a boolean.");
+                "Check if xs is in numerically ascending order. Returns a boolean."));
     templatize_comparator(env, JANET_FUN_GTE, ">=", 0, JOP_NUMERIC_GREATER_THAN_EQUAL,
-            "(>= & xs)\n\n"
+            JDOC("(>= & xs)\n\n"
-            "Check if xs is in numerically non-ascending order. Returns a boolean.");
+                "Check if xs is in numerically non-ascending order. Returns a boolean."));
     templatize_comparator(env, JANET_FUN_LTE, "<=", 0, JOP_NUMERIC_LESS_THAN_EQUAL,
-            "(<= & xs)\n\n"
+            JDOC("(<= & xs)\n\n"
-            "Check if xs is in numerically non-descending order. Returns a boolean.");
+                "Check if xs is in numerically non-descending order. Returns a boolean."));
     templatize_comparator(env, JANET_FUN_EQ, "==", 0, JOP_NUMERIC_EQUAL,
-            "(== & xs)\n\n"
+            JDOC("(== & xs)\n\n"
-            "Check if all values in xs are numerically equal (4.0 == 4). Returns a boolean.");
+                "Check if all values in xs are numerically equal (4.0 == 4). Returns a boolean."));
     templatize_comparator(env, JANET_FUN_NEQ, "not==", 1, JOP_NUMERIC_EQUAL,
-            "(not== & xs)\n\n"
+            JDOC("(not== & xs)\n\n"
-            "Check if any values in xs are not numerically equal (3.0 not== 4). Returns a boolean.");
+                "Check if any values in xs are not numerically equal (3.0 not== 4). Returns a boolean."));
 
     /* Platform detection */
     janet_def(env, "janet/version", janet_cstringv(JANET_VERSION),
@@ -736,6 +736,9 @@ JanetTable *janet_core_env(void) {
     janet_def(env, "janet/build", janet_cstringv(JANET_BUILD),
             "The build identifier of the running janet program.");
 
+    /* Allow references to the environment */
+    janet_def(env, "_env", ret, "The environment table for the current scope.");
+
     /* Set as gc root */
     janet_gcroot(janet_wrap_table(env));
 
@@ -757,9 +760,6 @@ JanetTable *janet_core_env(void) {
     janet_lib_asm(env);
 #endif
 
-    /* Allow references to the environment */
-    janet_def(env, "_env", ret, "The environment table for the current scope.");
-
     /* Run bootstrap source */
     janet_dobytes(env, janet_gen_core, janet_gen_core_size, "core.janet", NULL);
 

src/core/debug.c

@@ -23,6 +23,7 @@
 #include <janet/janet.h>
 #include "gc.h"
 #include "state.h"
+#include "util.h"
 
 /* Implements functionality to build a debugger from within janet.
  * The repl should also be able to serve as pretty featured debugger
@@ -225,33 +226,44 @@ static Janet cfun_argstack(int32_t argc, Janet *argv) {
 }
 
 static const JanetReg cfuns[] = {
-    {"debug/break", cfun_break,
+    {
-        "(debug/break source byte-offset)\n\n"
+        "debug/break", cfun_break,
+        JDOC("(debug/break source byte-offset)\n\n"
                 "Sets a breakpoint with source a key at a given byte offset. An offset "
                 "of 0 is the first byte in a file. Will throw an error if the breakpoint location "
                 "cannot be found. For example\n\n"
                 "\t(debug/break \"core.janet\" 1000)\n\n"
-        "wil set a breakpoint at the 1000th byte of the file core.janet."},
+                "wil set a breakpoint at the 1000th byte of the file core.janet.")
-    {"debug/unbreak", cfun_unbreak,
+    },
-        "(debug/unbreak source byte-offset)\n\n"
+    {
+        "debug/unbreak", cfun_unbreak,
+        JDOC("(debug/unbreak source byte-offset)\n\n"
                 "Remove a breakpoint with a source key at a given byte offset. An offset "
                 "of 0 is the first byte in a file. Will throw an error if the breakpoint "
-        "cannot be found."},
+                "cannot be found.")
-    {"debug/fbreak", cfun_fbreak,
+    },
-        "(debug/fbreak fun [,pc=0])\n\n"
+    {
+        "debug/fbreak", cfun_fbreak,
+        JDOC("(debug/fbreak fun [,pc=0])\n\n"
                 "Set a breakpoint in a given function. pc is an optional offset, which "
                 "is in bytecode instructions. fun is a function value. Will throw an error "
-        "if the offset is too large or negative."},
+                "if the offset is too large or negative.")
-    {"debug/unfbreak", cfun_unfbreak,
+    },
-        "(debug/unfbreak fun [,pc=0])\n\n"
+    {
-        "Unset a breakpoint set with debug/fbreak."},
+        "debug/unfbreak", cfun_unfbreak,
-    {"debug/arg-stack", cfun_argstack,
+        JDOC("(debug/unfbreak fun [,pc=0])\n\n"
-        "(debug/arg-stack fiber)\n\n"
+                "Unset a breakpoint set with debug/fbreak.")
+    },
+    {
+        "debug/arg-stack", cfun_argstack,
+        JDOC("(debug/arg-stack fiber)\n\n"
                 "Gets all values currently on the fiber's argument stack. Normally, "
                 "this should be empty unless the fiber signals while pushing arguments "
-        "to make a function call. Returns a new array."},
+                "to make a function call. Returns a new array.")
-    {"debug/stack", cfun_stack,
+    },
-        "(debug/stack fib)\n\n"
+    {
+        "debug/stack", cfun_stack,
+        JDOC("(debug/stack fib)\n\n"
                 "Gets information about the stack as an array of tables. Each table "
                 "in the array contains information about a stack frame. The top most, current "
                 "stack frame is the first table in the array, and the bottom most stack frame "
@@ -264,14 +276,15 @@ static const JanetReg cfuns[] = {
                 "\t:pc - integer indicating the location of the program counter\n"
                 "\t:source - string with filename or other identifier for the source code\n"
                 "\t:slots - array of all values in each slot\n"
-        "\t:tail - boolean indicating a tail call"
+                "\t:tail - boolean indicating a tail call")
     },
-    {"debug/lineage", cfun_lineage,
+    {
-        "(debug/lineage fib)\n\n"
+        "debug/lineage", cfun_lineage,
+        JDOC("(debug/lineage fib)\n\n"
                 "Returns an array of all child fibers from a root fiber. This function "
                 "is useful when a fiber signals or errors to an ancestor fiber. Using this function, "
                 "the fiber handling the error can see which fiber raised the signal. This function should "
-        "be used mostly for debugging purposes."
+                "be used mostly for debugging purposes.")
     },
     {NULL, NULL, NULL}
 };

src/core/fiber.c

@@ -24,6 +24,7 @@
 #include "fiber.h"
 #include "state.h"
 #include "gc.h"
+#include "util.h"
 
 static JanetFiber *make_fiber(int32_t capacity) {
     Janet *data;
@@ -373,8 +374,9 @@ static Janet cfun_setmaxstack(int32_t argc, Janet *argv) {
 }
 
 static const JanetReg cfuns[] = {
-    {"fiber/new", cfun_new,
+    {
-        "(fiber/new func [,sigmask])\n\n"
+        "fiber/new", cfun_new,
+        JDOC("(fiber/new func [,sigmask])\n\n"
                 "Create a new fiber with function body func. Can optionally "
                 "take a set of signals to block from the current parent fiber "
                 "when called. The mask is specified as a keyword where each character "
@@ -388,10 +390,11 @@ static const JanetReg cfuns[] = {
                 "\te - block error signals\n"
                 "\tu - block user signals\n"
                 "\ty - block yield signals\n"
-        "\t0-9 - block a specific user signal"
+                "\t0-9 - block a specific user signal")
     },
-    {"fiber/status", cfun_status,
+    {
-        "(fiber/status fib)\n\n"
+        "fiber/status", cfun_status,
+        JDOC("(fiber/status fib)\n\n"
                 "Get the status of a fiber. The status will be one of:\n\n"
                 "\t:dead - the fiber has finished\n"
                 "\t:error - the fiber has errored out\n"
@@ -399,22 +402,25 @@ static const JanetReg cfuns[] = {
                 "\t:pending - the fiber has been yielded\n"
                 "\t:user(0-9) - the fiber is suspended by a user signal\n"
                 "\t:alive - the fiber is currently running and cannot be resumed\n"
-        "\t:new - the fiber has just been created and not yet run"
+                "\t:new - the fiber has just been created and not yet run")
     },
-    {"fiber/current", cfun_current,
+    {
-        "(fiber/current)\n\n"
+        "fiber/current", cfun_current,
-        "Returns the currently running fiber."
+        JDOC("(fiber/current)\n\n"
+                "Returns the currently running fiber.")
     },
-    {"fiber/maxstack", cfun_maxstack,
+    {
-        "(fiber/maxstack fib)\n\n"
+        "fiber/maxstack", cfun_maxstack,
+        JDOC("(fiber/maxstack fib)\n\n"
                 "Gets the maximum stack size in janet values allowed for a fiber. While memory for "
                 "the fiber's stack is not allocated up front, the fiber will not allocated more "
-        "than this amount and will throw a stackoverflow error if more memory is needed. "
+                "than this amount and will throw a stackoverflow error if more memory is needed. ")
     },
-    {"fiber/setmaxstack", cfun_setmaxstack,
+    {
-        "(fiber/setmaxstack fib maxstack)\n\n"
+        "fiber/setmaxstack", cfun_setmaxstack,
+        JDOC("(fiber/setmaxstack fib maxstack)\n\n"
                 "Sets the maximum stack size in janet values for a fiber. By default, the "
-        "maximum stacksize is usually 8192."
+                "maximum stacksize is usually 8192.")
     },
     {NULL, NULL, NULL}
 };

src/core/io.c

@@ -27,6 +27,7 @@
 #include <stdio.h>
 #include <janet/janet.h>
 #include <errno.h>
+#include "util.h"
 
 #define IO_WRITE 1
 #define IO_READ 2
@@ -301,8 +302,9 @@ static Janet janet_io_fseek(int32_t argc, Janet *argv) {
 }
 
 static const JanetReg cfuns[] = {
-    {"file/open", janet_io_fopen,
+    {
-        "(file/open path [,mode])\n\n"
+        "file/open", janet_io_fopen,
+        JDOC("(file/open path [,mode])\n\n"
                 "Open a file. path is files absolute or relative path, and "
                 "mode is a set of flags indicating the mode to open the file in. "
                 "mode is a keyword where each character represents a flag. If the file "
@@ -312,16 +314,18 @@ static const JanetReg cfuns[] = {
                 "\tw - allow witing to the file\n"
                 "\ta - append to the file\n"
                 "\tb - open the file in binary mode (rather than text mode)\n"
-        "\t+ - append to the file instead of overwriting it"
+                "\t+ - append to the file instead of overwriting it")
     },
-    {"file/close", janet_io_fclose,
+    {
-        "(file/close f)\n\n"
+        "file/close", janet_io_fclose,
+        JDOC("(file/close f)\n\n"
                 "Close a file and release all related resources. When you are "
                 "done reading a file, close it to prevent a resource leak and let "
-        "other processes read the file."
+                "other processes read the file.")
     },
-    {"file/read", janet_io_fread,
+    {
-        "(file/read f what [,buf])\n\n"
+        "file/read", janet_io_fread,
+        JDOC("(file/read f what [,buf])\n\n"
                 "Read a number of bytes from a file into a buffer. A buffer can "
                 "be provided as an optional fourth argument. otherwise a new buffer "
                 "is created. 'what' can either be an integer or a keyword. Returns the "
@@ -329,34 +333,38 @@ static const JanetReg cfuns[] = {
                 "Values for 'what':\n\n"
                 "\t:all - read the whole file\n"
                 "\t:line - read up to and including the next newline character\n"
-        "\tn (integer) - read up to n bytes from the file"
+                "\tn (integer) - read up to n bytes from the file")
     },
-    {"file/write", janet_io_fwrite,
+    {
-        "(file/write f bytes)\n\n"
+        "file/write", janet_io_fwrite,
+        JDOC("(file/write f bytes)\n\n"
                 "Writes to a file. 'bytes' must be string, buffer, or symbol. Returns the "
-        "file"
+                "file.")
     },
-    {"file/flush", janet_io_fflush,
+    {
-        "(file/flush f)\n\n"
+        "file/flush", janet_io_fflush,
+        JDOC("(file/flush f)\n\n"
                 "Flush any buffered bytes to the filesystem. In most files, writes are "
-        "buffered for efficiency reasons. Returns the file handle."
+                "buffered for efficiency reasons. Returns the file handle.")
     },
-    {"file/seek", janet_io_fseek,
+    {
-        "(file/seek f [,whence [,n]])\n\n"
+        "file/seek", janet_io_fseek,
+        JDOC("(file/seek f [,whence [,n]])\n\n"
                 "Jump to a relative location in the file. 'whence' must be one of\n\n"
                 "\t:cur - jump relative to the current file location\n"
                 "\t:set - jump relative to the beginning of the file\n"
                 "\t:end - jump relative to the end of the file\n\n"
                 "By default, 'whence' is :cur. Optionally a value n may be passed "
                 "for the relative number of bytes to seek in the file. n may be a real "
-        "number to handle large files of more the 4GB. Returns the file handle."
+                "number to handle large files of more the 4GB. Returns the file handle.")
     },
-    {"file/popen", janet_io_popen,
+    {
-        "(file/popen path [,mode])\n\n"
+        "file/popen", janet_io_popen,
+        JDOC("(file/popen path [,mode])\n\n"
                 "Open a file that is backed by a process. The file must be opened in either "
                 "the :r (read) or the :w (write) mode. In :r mode, the stdout of the "
                 "process can be read from the file. In :w mode, the stdin of the process "
-        "can be written to. Returns the new file."
+                "can be written to. Returns the new file.")
     },
     {NULL, NULL, NULL}
 };
@@ -367,13 +375,13 @@ void janet_lib_io(JanetTable *env) {
     /* stdout */
     janet_def(env, "stdout",
             makef(stdout, IO_APPEND | IO_NOT_CLOSEABLE | IO_SERIALIZABLE),
-            "The standard output file.");
+            JDOC("The standard output file."));
     /* stderr */
     janet_def(env, "stderr",
             makef(stderr, IO_APPEND | IO_NOT_CLOSEABLE | IO_SERIALIZABLE),
-            "The standard error file.");
+            JDOC("The standard error file."));
     /* stdin */
     janet_def(env, "stdin",
             makef(stdin, IO_READ | IO_NOT_CLOSEABLE | IO_SERIALIZABLE),
-            "The standard input file.");
+            JDOC("The standard input file."));
 }

src/core/marsh.c

@@ -26,6 +26,7 @@
 #include "vector.h"
 #include "gc.h"
 #include "fiber.h"
+#include "util.h"
 
 typedef struct {
     jmp_buf err;
@@ -1146,26 +1147,29 @@ static Janet cfun_unmarshal(int32_t argc, Janet *argv) {
 }
 
 static const JanetReg cfuns[] = {
-    {"marshal", cfun_marshal,
+    {
-        "(marshal x [,reverse-lookup [,buffer]])\n\n"
+        "marshal", cfun_marshal,
+        JDOC("(marshal x [,reverse-lookup [,buffer]])\n\n"
                 "Marshal a janet value into a buffer and return the buffer. The buffer "
                 "can the later be unmarshalled to reconstruct the initial value. "
                 "Optionally, one can pass in a reverse lookup table to not marshal "
                 "aliased values that are found in the table. Then a forward"
                 "lookup table can be used to recover the origrinal janet value when "
-        "unmarshaling."
+                "unmarshaling.")
     },
-    {"unmarshal", cfun_unmarshal,
+    {
-        "(unmarshal buffer [,lookup])\n\n"
+        "unmarshal", cfun_unmarshal,
+        JDOC("(unmarshal buffer [,lookup])\n\n"
                 "Unmarshal a janet value from a buffer. An optional lookup table "
                 "can be provided to allow for aliases to be resolved. Returns the value "
-        "unmarshaled from the buffer."
+                "unmarshaled from the buffer.")
     },
-    {"env-lookup", cfun_env_lookup,
+    {
-        "(env-lookup env)\n\n"
+        "env-lookup", cfun_env_lookup,
+        JDOC("(env-lookup env)\n\n"
                 "Creates a forward lookup table for unmarshaling from an environment. "
                 "To create a reverse lookup table, use the invert function to swap keys "
-        "and values in the returned table."
+                "and values in the returned table.")
     },
     {NULL, NULL, NULL}
 };

src/core/math.c

@@ -22,6 +22,7 @@
 
 #include <janet/janet.h>
 #include <math.h>
+#include "util.h"
 
 /* Get a random number */
 Janet janet_rand(int32_t argc, Janet *argv) {
@@ -87,73 +88,90 @@ static Janet janet_not(int32_t argc, Janet *argv) {
 }
 
 static const JanetReg cfuns[] = {
-    {"%", janet_remainder,
+    {
-        "(% dividend divisor)\n\n"
+        "%", janet_remainder,
-        "Returns the remainder of dividend / divisor."
+        JDOC("(% dividend divisor)\n\n"
+                "Returns the remainder of dividend / divisor.")
     },
-    {"not", janet_not,
+    {
-        "(not x)\n\nReturns the boolen inverse of x."
+        "not", janet_not,
+        JDOC("(not x)\n\nReturns the boolen inverse of x.")
     },
-    {"math/random", janet_rand,
+    {
-        "(math/random)\n\n"
+        "math/random", janet_rand,
-        "Returns a uniformly distrbuted random number between 0 and 1."
+        JDOC("(math/random)\n\n"
+                "Returns a uniformly distrbuted random number between 0 and 1.")
     },
-    {"math/seedrandom", janet_srand,
+    {
-        "(math/seedrandom seed)\n\n"
+        "math/seedrandom", janet_srand,
+        JDOC("(math/seedrandom seed)\n\n"
                 "Set the seed for the random number generator. 'seed' should be an "
-        "an integer."
+                "an integer.")
     },
-    {"math/cos", janet_cos,
+    {
-        "(math/cos x)\n\n"
+        "math/cos", janet_cos,
-        "Returns the cosine of x."
+        JDOC("(math/cos x)\n\n"
+                "Returns the cosine of x.")
     },
-    {"math/sin", janet_sin,
+    {
-        "(math/sin x)\n\n"
+        "math/sin", janet_sin,
-        "Returns the sine of x."
+        JDOC("(math/sin x)\n\n"
+                "Returns the sine of x.")
     },
-    {"math/tan", janet_tan,
+    {
-        "(math/tan x)\n\n"
+        "math/tan", janet_tan,
-        "Returns the tangent of x."
+        JDOC("(math/tan x)\n\n"
+                "Returns the tangent of x.")
     },
-    {"math/acos", janet_acos,
+    {
-        "(math/acos x)\n\n"
+        "math/acos", janet_acos,
-        "Returns the arccosine of x."
+        JDOC("(math/acos x)\n\n"
+                "Returns the arccosine of x.")
     },
-    {"math/asin", janet_asin,
+    {
-        "(math/asin x)\n\n"
+        "math/asin", janet_asin,
-        "Returns the arcsine of x."
+        JDOC("(math/asin x)\n\n"
+                "Returns the arcsine of x.")
     },
-    {"math/atan", janet_atan,
+    {
-        "(math/atan x)\n\n"
+        "math/atan", janet_atan,
-        "Returns the arctangent of x."
+        JDOC("(math/atan x)\n\n"
+                "Returns the arctangent of x.")
     },
-    {"math/exp", janet_exp,
+    {
-        "(math/exp x)\n\n"
+        "math/exp", janet_exp,
-        "Returns e to the power of x."
+        JDOC("(math/exp x)\n\n"
+                "Returns e to the power of x.")
     },
-    {"math/log", janet_log,
+    {
-        "(math/log x)\n\n"
+        "math/log", janet_log,
-        "Returns log base 2 of x."
+        JDOC("(math/log x)\n\n"
+                "Returns log base 2 of x.")
     },
-    {"math/log10", janet_log10,
+    {
-        "(math/log10 x)\n\n"
+        "math/log10", janet_log10,
-        "Returns log base 10 of x."
+        JDOC("(math/log10 x)\n\n"
+                "Returns log base 10 of x.")
     },
-    {"math/sqrt", janet_sqrt,
+    {
-        "(math/sqrt x)\n\n"
+        "math/sqrt", janet_sqrt,
-        "Returns the square root of x."
+        JDOC("(math/sqrt x)\n\n"
+                "Returns the square root of x.")
     },
-    {"math/floor", janet_floor,
+    {
-        "(math/floor x)\n\n"
+        "math/floor", janet_floor,
-        "Returns the largest integer value number that is not greater than x."
+        JDOC("(math/floor x)\n\n"
+                "Returns the largest integer value number that is not greater than x.")
     },
-    {"math/ceil", janet_ceil,
+    {
-        "(math/ceil x)\n\n"
+        "math/ceil", janet_ceil,
-        "Returns the smallest integer value number that is not less than x."
+        JDOC("(math/ceil x)\n\n"
+                "Returns the smallest integer value number that is not less than x.")
     },
-    {"math/pow", janet_pow,
+    {
-        "(math/pow a x)\n\n"
+        "math/pow", janet_pow,
-        "Return a to the power of x."
+        JDOC("(math/pow a x)\n\n"
+                "Return a to the power of x.")
     },
     {NULL, NULL, NULL}
 };
@@ -162,9 +180,9 @@ static const JanetReg cfuns[] = {
 void janet_lib_math(JanetTable *env) {
     janet_cfuns(env, NULL, cfuns);
     janet_def(env, "math/pi", janet_wrap_number(3.1415926535897931),
-            "The value pi.");
+            JDOC("The value pi."));
     janet_def(env, "math/e", janet_wrap_number(2.7182818284590451),
-            "The base of the natural log.");
+            JDOC("The base of the natural log."));
     janet_def(env, "math/inf", janet_wrap_number(INFINITY),
-            "The number representing positive infinity");
+            JDOC("The number representing positive infinity"));
 }

src/core/os.c

@@ -23,6 +23,7 @@
 #include <janet/janet.h>
 #include <stdlib.h>
 #include <time.h>
+#include "util.h"
 
 #ifdef JANET_WINDOWS
 #include <Windows.h>
@@ -272,53 +273,63 @@ static Janet os_cwd(int32_t argc, Janet *argv) {
 }
 
 static const JanetReg cfuns[] = {
-    {"os/which", os_which,
+    {
-        "(os/which)\n\n"
+        "os/which", os_which,
+        JDOC("(os/which)\n\n"
                 "Check the current operating system. Returns one of:\n\n"
                 "\t:windows - Microsoft Windows\n"
                 "\t:macos - Apple macos\n"
-        "\t:posix - A POSIX compatible system (default)"
+                "\t:posix - A POSIX compatible system (default)")
     },
-    {"os/execute", os_execute,
+    {
-        "(os/execute program & args)\n\n"
+        "os/execute", os_execute,
+        JDOC("(os/execute program & args)\n\n"
                 "Execute a program on the system and pass it string arguments. Returns "
-        "the exit status of the program."
+                "the exit status of the program.")
     },
-    {"os/shell", os_shell,
+    {
-        "(os/shell str)\n\n"
+        "os/shell", os_shell,
-        "Pass a command string str directly to the system shell."
+        JDOC("(os/shell str)\n\n"
+                "Pass a command string str directly to the system shell.")
     },
-    {"os/exit", os_exit,
+    {
-        "(os/exit x)\n\n"
+        "os/exit", os_exit,
+        JDOC("(os/exit x)\n\n"
                 "Exit from janet with an exit code equal to x. If x is not an integer, "
-        "the exit with status equal the hash of x."
+                "the exit with status equal the hash of x.")
     },
-    {"os/getenv", os_getenv,
+    {
-        "(os/getenv variable)\n\n"
+        "os/getenv", os_getenv,
-        "Get the string value of an environment variable."
+        JDOC("(os/getenv variable)\n\n"
+                "Get the string value of an environment variable.")
     },
-    {"os/setenv", os_setenv,
+    {
-        "(os/setenv variable value)\n\n"
+        "os/setenv", os_setenv,
-        "Set an environment variable."
+        JDOC("(os/setenv variable value)\n\n"
+            "Set an environment variable.")
     },
-    {"os/time", os_time,
+    {
-        "(os/time)\n\n"
+        "os/time", os_time,
+        JDOC("(os/time)\n\n"
             "Get the current time expressed as the number of seconds since "
-        "January 1, 1970, the Unix epoch. Returns a real number."
+            "January 1, 1970, the Unix epoch. Returns a real number.")
     },
-    {"os/clock", os_clock,
+    {
-        "(os/clock)\n\n"
+        "os/clock", os_clock,
+        JDOC("(os/clock)\n\n"
             "Return the number of seconds since some fixed point in time. The clock "
-        "is guaranteed to be non decreased in real time."
+            "is guaranteed to be non decreased in real time.")
     },
-    {"os/sleep", os_sleep,
+    {
-        "(os/sleep nsec)\n\n"
+        "os/sleep", os_sleep,
+        JDOC("(os/sleep nsec)\n\n"
             "Suspend the program for nsec seconds. 'nsec' can be a real number. Returns "
-        "nil."
+            "nil.")
     },
-    {"os/cwd", os_cwd,
+    {
-        "(os/cwd)\n\n"
+        "os/cwd", os_cwd,
-        "Returns the current working directory."
+        JDOC("(os/cwd)\n\n"
+            "Returns the current working directory.")
     },
     {NULL, NULL, NULL}
 };

src/core/parse.c

@@ -21,6 +21,7 @@
 */
 
 #include <janet/janet.h>
+#include "util.h"
 
 /* Check if a character is whitespace */
 static int is_whitespace(uint8_t c) {
@@ -743,64 +744,74 @@ static Janet cfun_state(int32_t argc, Janet *argv) {
 }
 
 static const JanetReg cfuns[] = {
-    {"parser/new", cfun_parser,
+    {
-        "(parser/new)\n\n"
+        "parser/new", cfun_parser,
+        JDOC("(parser/new)\n\n"
                 "Creates and returns a new parser object. Parsers are state machines "
-        "that can receive bytes, and generate a stream of janet values. "
+                "that can receive bytes, and generate a stream of janet values. ")
     },
-    {"parser/has-more", cfun_has_more,
+    {
-        "(parser/has-more parser)\n\n"
+        "parser/has-more", cfun_has_more,
-        "Check if the parser has more values in the value queue."
+        JDOC("(parser/has-more parser)\n\n"
+                "Check if the parser has more values in the value queue.")
     },
-    {"parser/produce", cfun_produce,
+    {
-        "(parser/produce parser)\n\n"
+        "parser/produce", cfun_produce,
+        JDOC("(parser/produce parser)\n\n"
                 "Dequeue the next value in the parse queue. Will return nil if "
                 "no parsed values are in the queue, otherwise will dequeue the "
-        "next value."
+                "next value.")
     },
-    {"parser/consume", cfun_consume,
+    {
-        "(parser/consume parser bytes [, index])\n\n"
+        "parser/consume", cfun_consume,
+        JDOC("(parser/consume parser bytes [, index])\n\n"
                 "Input bytes into the parser and parse them. Will not throw errors "
                 "if there is a parse error. Starts at the byte index given by index. Returns "
-        "the number of bytes read."
+                "the number of bytes read.")
     },
-    {"parser/byte", cfun_byte,
+    {
-        "(parser/byte parser b)\n\n"
+        "parser/byte", cfun_byte,
-        "Input a single byte into the parser byte stream. Returns the parser."
+        JDOC("(parser/byte parser b)\n\n"
+                "Input a single byte into the parser byte stream. Returns the parser.")
     },
-    {"parser/error", cfun_error,
+    {
-        "(parser/error parser)\n\n"
+        "parser/error", cfun_error,
+        JDOC("(parser/error parser)\n\n"
                 "If the parser is in the error state, returns the message asscoiated with "
                 "that error. Otherwise, returns nil. Also flushes the parser state and parser "
                 "queue, so be sure to handle everything in the queue before calling "
-        "parser/error."
+                "parser/error.")
     },
-    {"parser/status", cfun_status,
+    {
-        "(parser/status parser)\n\n"
+        "parser/status", cfun_status,
+        JDOC("(parser/status parser)\n\n"
                 "Gets the current status of the parser state machine. The status will "
                 "be one of:\n\n"
                 "\t:pending - a value is being parsed.\n"
                 "\t:error - a parsing error was encountered.\n"
-        "\t:root - the parser can either read more values or safely terminate."
+                "\t:root - the parser can either read more values or safely terminate.")
     },
-    {"parser/flush", cfun_flush,
+    {
-        "(parser/flush parser)\n\n"
+        "parser/flush", cfun_flush,
+        JDOC("(parser/flush parser)\n\n"
                 "Clears the parser state and parse queue. Can be used to reset the parser "
                 "if an error was encountered. Does not reset the line and column counter, so "
-        "to begin parsing in a new context, create a new parser."
+                "to begin parsing in a new context, create a new parser.")
     },
-    {"parser/state", cfun_state,
+    {
-        "(parser/state parser)\n\n"
+        "parser/state", cfun_state,
+        JDOC("(parser/state parser)\n\n"
                 "Returns a string representation of the internal state of the parser. "
                 "Each byte in the string represents a nested data structure. For example, "
                 "if the parser state is '([\"', then the parser is in the middle of parsing a "
-        "string inside of square brackets inside parens. Can be used to augment a repl prompt."
+                "string inside of square brackets inside parens. Can be used to augment a repl prompt.")
     },
-    {"parser/where", cfun_where,
+    {
-        "(parser/where parser)\n\n"
+        "parser/where", cfun_where,
+        JDOC("(parser/where parser)\n\n"
                 "Returns the current line number and column number of the parser's location "
                 "in the byte stream as a tuple (line, column). Lines and columns are counted from "
-        "1, (the first byte is line1, column 1) and a newline is considered ascii 0x0A."
+                "1, (the first byte is line1, column 1) and a newline is considered ascii 0x0A.")
     },
     {NULL, NULL, NULL}
 };

src/core/string.c

@@ -1042,84 +1042,99 @@ static Janet cfun_pretty(int32_t argc, Janet *argv) {
 }
 
 static const JanetReg cfuns[] = {
-    {"string/slice", cfun_slice,
+    {
-        "(string/slice bytes [,start=0 [,end=(length str)]])\n\n"
+        "string/slice", cfun_slice,
+        JDOC("(string/slice bytes [,start=0 [,end=(length str)]])\n\n"
                 "Returns a substring from a byte sequence. The substring is from "
                 "index start inclusive to index end exclusive. All indexing "
                 "is from 0. 'start' and 'end' can also be negative to indicate indexing "
-        "from the end of the string."
+                "from the end of the string.")
     },
-    {"string/repeat", cfun_repeat,
+    {
-        "(string/repeat bytes n)\n\n"
+        "string/repeat", cfun_repeat,
-        "Returns a string that is n copies of bytes concatenated."
+        JDOC("(string/repeat bytes n)\n\n"
+                "Returns a string that is n copies of bytes concatenated.")
     },
-    {"string/bytes", cfun_bytes,
+    {
-        "(string/bytes str)\n\n"
+        "string/bytes", cfun_bytes,
-        "Returns an array of integers that are the byte values of the string."
+        JDOC("(string/bytes str)\n\n"
+                "Returns an array of integers that are the byte values of the string.")
     },
-    {"string/from-bytes", cfun_frombytes,
+    {
-        "(string/from-bytes byte-array)\n\n"
+        "string/from-bytes", cfun_frombytes,
+        JDOC("(string/from-bytes byte-array)\n\n"
                 "Creates a string from an array of integers with byte values. All integers "
-        "will be coerced to the range of 1 byte 0-255."
+                "will be coerced to the range of 1 byte 0-255.")
     },
-    {"string/ascii-lower", cfun_asciilower,
+    {
-        "(string/ascii-lower str)\n\n"
+        "string/ascii-lower", cfun_asciilower,
+        JDOC("(string/ascii-lower str)\n\n"
                 "Returns a new string where all bytes are replaced with the "
                 "lowercase version of themselves in ascii. Does only a very simple "
-        "case check, meaning no unicode support."
+                "case check, meaning no unicode support.")
     },
-    {"string/ascii-upper", cfun_asciiupper,
+    {
-        "(string/ascii-upper str)\n\n"
+        "string/ascii-upper", cfun_asciiupper,
+        JDOC("(string/ascii-upper str)\n\n"
                 "Returns a new string where all bytes are replaced with the "
                 "uppercase version of themselves in ascii. Does only a very simple "
-        "case check, meaning no unicode support."
+                "case check, meaning no unicode support.")
     },
-    {"string/reverse", cfun_reverse,
+    {
-        "(string/reverse str)\n\n"
+        "string/reverse", cfun_reverse,
-        "Returns a string that is the reversed version of str."
+        JDOC("(string/reverse str)\n\n"
+                "Returns a string that is the reversed version of str.")
     },
-    {"string/find", cfun_find,
+    {
-        "(string/find patt str)\n\n"
+        "string/find", cfun_find,
+        JDOC("(string/find patt str)\n\n"
                 "Searches for the first instance of pattern patt in string "
                 "str. Returns the index of the first character in patt if found, "
-        "otherwise returns nil."
+                "otherwise returns nil.")
     },
-    {"string/find-all", cfun_findall,
+    {
-        "(string/find patt str)\n\n"
+        "string/find-all", cfun_findall,
+        JDOC("(string/find patt str)\n\n"
                 "Searches for all instances of pattern patt in string "
                 "str. Returns an array of all indices of found patterns. Overlapping "
                 "instances of the pattern are not counted, meaning a byte in string "
                 "will only contribute to finding at most on occurrence of pattern. If no "
-        "occurrences are found, will return an empty array."
+                "occurrences are found, will return an empty array.")
     },
-    {"string/replace", cfun_replace,
+    {
-        "(string/replace patt subst str)\n\n"
+        "string/replace", cfun_replace,
+        JDOC("(string/replace patt subst str)\n\n"
                 "Replace the first occurrence of patt with subst in the string str. "
-        "Will return the new string if patt is found, otherwise returns str."
+                "Will return the new string if patt is found, otherwise returns str.")
     },
-    {"string/replace-all", cfun_replaceall,
+    {
-        "(string/replace-all patt subst str)\n\n"
+        "string/replace-all", cfun_replaceall,
+        JDOC("(string/replace-all patt subst str)\n\n"
                 "Replace all instances of patt with subst in the string str. "
-        "Will return the new string if patt is found, otherwise returns str."
+                "Will return the new string if patt is found, otherwise returns str.")
     },
-    {"string/split", cfun_split,
+    {
-        "(string/split delim str)\n\n"
+        "string/split", cfun_split,
+        JDOC("(string/split delim str)\n\n"
                 "Splits a string str with delimiter delim and returns an array of "
                 "substrings. The substrings will not contain the delimiter delim. If delim "
-        "is not found, the returned array will have one element."
+                "is not found, the returned array will have one element.")
     },
-    {"string/check-set", cfun_checkset,
+    {
-        "(string/check-set set str)\n\n"
+        "string/check-set", cfun_checkset,
+        JDOC("(string/check-set set str)\n\n"
                 "Checks if any of the bytes in the string set appear in the string str. "
-        "Returns true if some bytes in set do appear in str, false if no bytes do."
+                "Returns true if some bytes in set do appear in str, false if no bytes do.")
     },
-    {"string/join", cfun_join,
+    {
-        "(string/join parts [,sep])\n\n"
+        "string/join", cfun_join,
+        JDOC("(string/join parts [,sep])\n\n"
                 "Joins an array of strings into one string, optionally separated by "
-        "a separator string sep."
+                "a separator string sep.")
     },
-    {"string/number", cfun_number,
+    {
-        "(string/number x [,format [,maxlen [,precision]]])\n\n"
+        "string/number", cfun_number,
+        JDOC("(string/number x [,format [,maxlen [,precision]]])\n\n"
                 "Formats a number as string. The format parameter indicates how "
                 "to display the number, either as floating point, scientific, or "
                 "whichever representation is shorter. format can be:\n\n"
@@ -1131,12 +1146,13 @@ static const JanetReg cfuns[] = {
                 "\t:F - same as :f\n\n"
                 "The programmer can also specify the max length of the output string "
                 "and the precision (number of places after decimal) in the output number. "
-        "Returns a string representation of x."
+                "Returns a string representation of x.")
     },
-    {"string/pretty", cfun_pretty,
+    {
-        "(string/pretty x [,depth=4 [,buffer=@\"\"]])\n\n"
+        "string/pretty", cfun_pretty,
+        JDOC("(string/pretty x [,depth=4 [,buffer=@\"\"]])\n\n"
                 "Pretty prints a value to a buffer. Optionally allows setting max "
-        "recursion depth, as well as writing to a buffer. Returns the buffer."
+                "recursion depth, as well as writing to a buffer. Returns the buffer.")
     },
     {NULL, NULL, NULL}
 };

src/core/table.c

@@ -232,32 +232,37 @@ static Janet cfun_rawget(int32_t argc, Janet *argv) {
 }
 
 static const JanetReg cfuns[] = {
-    {"table/new", cfun_new,
+    {
-        "(table/new capacity)\n\n"
+        "table/new", cfun_new,
+        JDOC("(table/new capacity)\n\n"
                 "Creates a new empty table with pre-allocated memory "
                 "for capacity entries. This means that if one knows the number of "
                 "entries going to go in a table on creation, extra memory allocation "
-        "can be avoided. Returns the new table."
+                "can be avoided. Returns the new table.")
     },
-    {"table/to-struct", cfun_tostruct,
+    {
-        "(table/to-struct tab)\n\n"
+        "table/to-struct", cfun_tostruct,
+        JDOC("(table/to-struct tab)\n\n"
                 "Convert a table to a struct. Returns a new struct. This function "
-        "does not take into account prototype tables."
+                "does not take into account prototype tables.")
     },
-    {"table/getproto", cfun_getproto,
+    {
-        "(table/getproto tab)\n\n"
+        "table/getproto", cfun_getproto,
+        JDOC("(table/getproto tab)\n\n"
                 "Get the prototype table of a table. Returns nil if a table "
-        "has no prototype, otherwise returns the prototype."
+                "has no prototype, otherwise returns the prototype.")
     },
-    {"table/setproto", cfun_setproto,
+    {
-        "(table/setproto tab proto)\n\n"
+        "table/setproto", cfun_setproto,
-        "Set the prototype of a table. Returns the original table tab."
+        JDOC("(table/setproto tab proto)\n\n"
+                "Set the prototype of a table. Returns the original table tab.")
     },
-    {"table/rawget", cfun_rawget,
+    {
-        "(table/rawget tab key)\n\n"
+        "table/rawget", cfun_rawget,
+        JDOC("(table/rawget tab key)\n\n"
                 "Gets a value from a table without looking at the prototype table. "
                 "If a table tab does not contain t directly, the function will return "
-        "nil without checking the prototype. Returns the value in the table."
+                "nil without checking the prototype. Returns the value in the table.")
     },
     {NULL, NULL, NULL}
 };

src/core/tuple.c

@@ -118,23 +118,26 @@ static Janet cfun_append(int32_t argc, Janet *argv) {
 }
 
 static const JanetReg cfuns[] = {
-    {"tuple/slice", cfun_slice,
+    {
-        "(tuple/slice arrtup [,start=0 [,end=(length arrtup)]])\n\n"
+        "tuple/slice", cfun_slice,
+        JDOC("(tuple/slice arrtup [,start=0 [,end=(length arrtup)]])\n\n"
                 "Take a sub sequence of an array or tuple from index start "
                 "inclusive to index end exclusive. If start or end are not provided, "
                 "they default to 0 and the length of arrtup respectively."
-        "Returns the new tuple."
+                "Returns the new tuple.")
     },
-    {"tuple/append", cfun_append,
+    {
-        "(tuple/append tup & items)\n\n"
+        "tuple/append", cfun_append,
+        JDOC("(tuple/append tup & items)\n\n"
                 "Returns a new tuple that is the result of appending "
-        "each element in items to tup."
+                "each element in items to tup.")
     },
-    {"tuple/prepend", cfun_prepend,
+    {
-        "(tuple/prepend tup & items)\n\n"
+        "tuple/prepend", cfun_prepend,
+        JDOC("(tuple/prepend tup & items)\n\n"
                 "Prepends each element in items to tuple and "
                 "returns a new tuple. Items are prepended such that the "
-        "last element in items is the first element in the new tuple."
+                "last element in items is the first element in the new tuple.")
     },
     {NULL, NULL, NULL}
 };

src/core/util.h

@@ -25,6 +25,13 @@
 
 #include <janet/janet.h>
 
+/* Omit docstrings in some builds */
+#ifdef JANET_NO_BOOTSTRAP
+#define JDOC(x) NULL
+#else
+#define JDOC(x) x
+#endif
+
 /* Utils */
 #define janet_maphash(cap, hash) ((uint32_t)(hash) & (cap - 1))
 extern const char janet_base64[65];

tools/marshal_core.janet

@@ -0,0 +1,23 @@
+#
+# Tool to dump a marshalled version of the janet core to stdout. The
+# image should eventually allow janet to be started from a precompiled
+# image rather than recompiled every time from the embedded source. More
+# work will go into shrinking the image (it isn't currently that large but
+# could be smaller), creating the mechanism to load the image, and modifying
+# the build process to compile janet with a build int image rather than
+# embedded source.
+#
+
+# Get image. This image contains as much of the core library and documentation that
+# can be written to an image (no cfunctions, no abstracts (stdout, stdin, stderr)),
+# everyting else goes. Cfunctions and abstracts will be referenced from a register
+# table which will be generated on janet startup.
+(def image (let [env-pairs (pairs (env-lookup _env))
+                 essential-pairs (filter (fn [[k v]] (or (cfunction? v) (abstract? v))) env-pairs)
+                 lookup (table ;(mapcat identity essential-pairs))
+                 reverse-lookup (invert lookup)]
+             (marshal (table/getproto _env) reverse-lookup)))
+
+# Write image
+(file/write stdout image)
+(file/flush stdout)