Write some docs on binding C functions

docs/DoxygenLayout.xml

@@ -3,6 +3,7 @@
   <!-- Navigation index tabs for HTML output -->
   <navindex>
     <tab type="mainpage" visible="yes" title="Home"/>
+    <!-- Temporarily removed until it actually gets written.
     <tab type="usergroup" visible="yes" url="@ref lang_intro" title="Language">
       <tab type="user" url="@ref lang_intro" title="Language"/>
       <tab type="user" url="@ref lang_compiler" title="Compilation"/>
@@ -10,6 +11,7 @@
       <tab type="user" url="@ref lang_expressions" title="Expressions"/>
       <tab type="user" url="@ref lang_statements" title="Statements"/>
     </tab>
+    -->
     <tab type="usergroup" visible="yes" url="@ref modulelist" title="Modules">
       <tab type="user" url="@ref modulelist" title="Module List"/>
       <tab type="user" url="@ref classindex" title="Class Index"/>

docs/c_functions.md

@@ -1,3 +1,67 @@
 ## Binding C Functions {#c_functions}
 
+Whether you're embedding Kuroko in an application or writing an extension module, binding a C function is something you'll want to do.
 
+### The Easy Way
+
+```c
+#include <kuroko/kuroko.h>
+#include <kuroko/vm.h>
+#include <kuroko/util.h>
+
+KRK_FUNC(myfunction,{
+    FUNCTION_TAKES_EXACTLY(1);
+    CHECK_ARG(0,int,krk_integer_type,myarg);
+    return INTEGER_VAL(myarg*myarg);
+})
+
+int main(int argc, char *argv[]) {
+    krk_initVM(0);
+    BIND_FUNC(vm.builtins, myfunction);
+    krk_startModule("__main__");
+    krk_interpret("print(myfunction(42))","<stdin>");
+    krk_freeVM();
+    return 0;
+}
+```
+
+This demo uses the utility macros provided in `<kuroko/util.h>` to easily create a function with argument checking and bind it to the builtin namespace.
+
+`KRK_FUNC()` takes care of the function signature, function naming, and default return value of `None`.
+
+`FUNCTION_TAKES_EXACTLY()` provides simple argument count validation. `FUNCTION_TAKES_AT_LEAST()` and `FUNCTION_TAKES_AT_MOST()` are also available.
+
+`CHECK_ARG()` validates the type of arguments passed to the function and unboxes them to C types.
+
+`INTEGER_VAL()` converts a C integer to a Kuroko `int` value.
+
+`BIND_FUNC()` binds the function to a namespace table.
+
+### The Hard Way
+
+While the macros above provide a convenient way to bind functions, they are just wrappers around lower-level functionality of the API.
+
+```c
+#include <kuroko/kuroko.h>
+#include <kuroko/vm.h>
+
+static KrkValue myfunction(int argc, KrkValue argv[], int hasKw) {
+    int myarg;
+
+    if (argc != 1) return krk_runtimeError(vm.exceptions->argumentError, "myfunction() expects exactly 1 argument, %d given", argc);
+    if (!IS_INTEGER(argv[0])) return krk_runtimeError(vm.exceptions->typeError, "expected int, not '%s'", krk_typeName(argv[0]));
+
+    myarg = AS_INTEGER(argv[0]);
+
+    return INTEGER_VAL(myarg*myarg);
+}
+
+int main(int argc, char *argv[]) {
+    krk_initVM(0);
+    krk_defineNative(&vm.builtins->fields, "myfunction", myfunction);
+    krk_startModule("__main__");
+    krk_interpret("print(myfunction(42))", "<stdin>");
+    krk_freeVM();
+    return 0;
+}
+```

docs/doxy.css

@@ -45,6 +45,8 @@
 }
 .header {
   margin-top: 1em;
+  margin-left: 1rem;
+  margin-right: 1rem;
 }
 .header a { text-decoration: none; }
 .header a:hover { text-decoration: underline; }
@@ -53,10 +55,11 @@
   font-size: small;
 }
 .header>.headertitle {
-  font-size: 25px;
+  font-size: 26px;
   font-weight: bold;
 }
 .contents {
+  margin: 1rem;
   margin-bottom: 2rem;
 }
 .contents a { text-decoration: none; }
@@ -69,6 +72,12 @@
 .contents h2 {
   font-size: 26px;
 }
+.contents h3 {
+  font-size: 22px;
+}
+.contents h4 {
+  font-size: 18px;
+}
 .contents a {
   scroll-margin-top: 4rem;
 }
@@ -264,11 +273,11 @@ div.memdoc {
   white-space: pre-wrap;
 }
 .fragment {
-  margin: 1rem;
   background-color: #1f1f1f;
   padding: 0.5rem;
   border-radius: 5px;
   color: #e6e6e6;
+  margin-bottom: 0.5rem;
 }
 .fragment a {
   color: inherit;

docs/embedding.md

@@ -27,8 +27,6 @@ Kuroko's public API is exposed primarily through the `<kuroko/kuroko.h>` header.
 
 `<kuroko/vm.h>` provides internal functions for finer control over how the VM operates.
 
-@bsnote{warning,Headers are in the process of being reorganized and the above statements are not necessarily true _yet_.}
-
 Other headers provide convenience functions and macros for building C extensions.
 
 #### Initializing the VM

docs/index.md

@@ -3,5 +3,3 @@
 Take a look at the @ref modulelist or learn how to embed Kuroko with the @ref embedding.
 
 You can also find a complete list of all classes provided by the standard library in the @ref classindex and all functions in the @ref functionindex.
-
-@bsnote{This documentation is a work-in-progress.}

src/kuroko/vm.h

@@ -622,8 +622,8 @@ extern KrkValue krk_set_of(int argc, KrkValue argv[], int hasKw);
  * Calls the callable @p argCount stack entries down from the top
  * of the stack, passing @p argCount arguments. Resumes execution
  * of the VM for managed calls until they are completed. Pops
- * @p argCount items from the stack and returns the result of
- * the call.
+ * all arguments and the callable from the stack and returns the
+ * return value of the call.
  *
  * @param argCount Arguments to collect from the stack.
  * @return The return value of the function.