Ongoing documentation improvements

docs/DoxygenLayout.xml

@@ -3,7 +3,20 @@
   <!-- Navigation index tabs for HTML output -->
   <navindex>
     <tab type="mainpage" visible="yes" title="Home"/>
+    <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"/>
+      <tab type="user" url="@ref lang_objects" title="Objects"/>
+      <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"/>
+      <tab type="user" url="@ref functionindex" title="Function Index"/>
+    </tab>
     <tab type="usergroup" visible="yes" url="@ref embedding" title="Embedding">
+      <tab type="user" url="@ref embedding" title="Embedding"/>
       <tab type="classlist" visible="yes" title="" intro=""/>
       <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
       <tab type="hierarchy" visible="yes" title="" intro=""/>
@@ -11,11 +24,6 @@
       <tab type="filelist" visible="yes" title="" intro=""/>
       <tab type="globals" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="usergroup" visible="yes" title="Modules">
-      <tab type="user" url="@ref modulelist" title="Module List"/>
-      <tab type="user" url="@ref classindex" title="Class Index"/>
-      <tab type="user" url="@ref functionindex" title="Function Index"/>
-    </tab>
     <!--
     <tab type="pages" visible="no" title="" intro=""/>
     <tab type="modules" visible="yes" title="" intro=""/>

docs/embedding.md

@@ -1,19 +1,60 @@
 ## Kuroko C API Documentation {#embedding}
+
+This documentation covers using Kuroko 1.1 as a scripting language in a host C application and assumes a relatively recent Linux or similarly POSIX-y build environment.
+
+We'll also assume you've already installed Kuroko from a package that includes source headers, such as [the PPA](https://launchpad.net/~k-lange/+archive/ubuntu/kuroko/).
+
 ### Getting Started {#getting-started}
 
-
 ```c
-#include <stdio.h>
 #include <kuroko/kuroko.h>
 #include <kuroko/vm.h>
 
 int main(int argc, char *argv[]) {
     krk_initVM(0);
     krk_startModule("__main__");
-    krk_interpret("import kuroko\nprint('Kuroko',kuroko.version)\n", 1, "<stdin>","<stdin>");
+    krk_interpret("print('hello, world')", "<stdin>");
     krk_freeVM();
     return 0;
 }
 ```
 
+Let's start by looking at the example code above.
+
+#### Headers
+
+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
+
+Our first task in integrating Kuroko into an embedded application is to set up the VM, which we do with `krk_initVM()`. This function takes one paramater representing the initial _global and thread flags_, which control debugging features for tracing. In our example code, we do not need to use to use any debug features so we pass `0`.
+
+Valid flags to pass to `krk_initVM()` include:
+
+- `KRK_THREAD_ENABLE_TRACING`  
+Prints instruction traces during execution.
+- `KRK_THREAD_ENABLE_DISASSEMBLY`  
+Prints function bytecode disassembly whenever the compiler is called.
+- `KRK_THREAD_ENABLE_SCAN_TRACING`  
+Prints token stream data whenever the compiler is called. (Not recommended.)
+- `KRK_GLOBAL_ENABLE_STRESS_GC`  
+Causes the garbage collector to be called on every allocation (from the main thread).
+- `KRK_GLOBAL_CLEAN_OUTPUT`  
+Disables automatic printing of uncaught exception tracebacks. Use `krk_dumpTraceback()` to print a traceback from the exception in the current thread to `stderr`.
+
+@bsnote{Be careful when using `KRK_GLOBAL_CLEAN_OUTPUT` when threading is available; uncaught exceptions from threads will not be automatically printed and are trickier to catch from C code.}
+
+#### Starting a Module
+
+All Kuroko code runs in the context of a _module_. When we run code directly using `krk_interpret()`, such as when providing a REPL or calling snippets, or by using `krk_runfile()` to execute the contents of a file, we need to establish our own module first. `krk_startModule()` creates a module context and gives it a name. We use the name `__main__` as a convention for directly executed code, distinguishing it from imported code.
+
+#### Calling the Interpreter
+
+We pass C strings containg Kuroko code to `krk_interpret()` to be run by the interpreter. The second argument to `krk_interpret()` provides a filename for the source of the code, or representative string to show in tracebacks for code that did not come from a file.
 

docs/lang_compiler.md

@@ -0,0 +1,3 @@
+# %Compiler Overview {#lang_compiler}
+
+@bsnote{TODO}

docs/lang_expressions.md

@@ -0,0 +1,3 @@
+# Expressions {#lang_expressions}
+
+@bsnote{TODO}

docs/lang_intro.md

@@ -0,0 +1,12 @@
+# Language Overview {#lang_intro}
+
+Kuroko is a dynamic, bytecode-compiled, embeddable, modular programming language with a familar, indentation driven syntax.
+
+This reference documentation details the syntax and operation of the language's compiler and bytecode interpreters. The reference is divided into the following sections:
+
+- @ref lang_compiler describes the processing of parsing Kuroko source files and how they are compiled to bytecode.
+- @ref lang_objects describes the object model used by the virtual machine and how values are represented in memory and accessed by code.
+- @ref lang_expressions provides detailed explanations of the syntax and execution of logical expressions.
+- @ref lang_statements provides detailed explanations of the syntax and execution of branching statements and other key language contructs.
+
+Much of the structure and verbiage in this guide is based on the language reference manuals for Python and Lua.

docs/lang_objects.md

@@ -0,0 +1,3 @@
+# Object Model {#lang_objects}
+
+@bsnote{TODO}

docs/lang_statements.md

@@ -0,0 +1,3 @@
+# Statements {#lang_statements}
+
+@bsnote{TODO}

src/vm.h

@@ -282,7 +282,7 @@ extern void krk_freeVM(void);
 /**
  * @brief Reset the current thread's stack state to the top level.
  *
- * In a repl, this can be called before or after each iteration to clean up any
+ * In a repl, this should be called before or after each iteration to clean up any
  * remnant stack entries from an uncaught exception. It should not be called
  * during normal execution by C extensions. Values on the stack may be lost
  * to garbage collection after a call to @c krk_resetStack .
@@ -297,8 +297,8 @@ extern void krk_resetStack(void);
  *
  * @param src      Source code to compile and run.
  * @param fromFile Path to the source file, or a representative string like "<stdin>".
- * @return When newScope is non-zero, an object representing the globals of the new scope;
- *         otherwise, the returned result of the execution of this code. If an uncaught
+ * @return The value of the executed code, which is either the value of an explicit 'return'
+ *         statement, or the last expression value from an executed statement.  If an uncaught
  *         exception occurred, this will be @c None and @c krk_currentThread.flags should
  *         indicate @c KRK_THREAD_HAS_EXCEPTION and @c krk_currentThread.currentException
  *         should contain the raised exception value.
@@ -503,10 +503,10 @@ extern KrkClass * krk_getType(KrkValue value);
  * a subtype of @p type. As this chains through the inheritence tree, the
  * more deeply subclassed @p obj is, the longer it may take to determine
  * if it is a subtype of @p type. All types should eventually be subtypes
- * of the @c object type, so this condition should not be checked. For
+ * of the @ref object type, so this condition should not be checked. For
  * some types, convenience macros are available. If you need to check if
- * @p obj is a specific type, exclusive of subtypes, compare @c krk_getType
- * instead of using this function.
+ * @p obj is a specific type, exclusive of subtypes, look at
+ * @c krk_getType() instead of using this function.
  *
  * @param obj Value to examine.
  * @param type Class object to test for membership of.
@@ -522,7 +522,7 @@ extern int krk_isInstanceOf(KrkValue obj, KrkClass * type);
  * If @p name is not a valid method, the binding fails.
  * If @p name is a valid method, the method will be retrieved and
  * bound to the instance on the top of the stack, replacing it
- * with a @c BoundMethod object.
+ * with a @ref BoundMethod object.
  *
  * @param _class Class object to resolve methods from.
  * @param name   String object with the name of the method to resolve.
@@ -624,7 +624,7 @@ extern void krk_finalizeClass(KrkClass * _class);
  * @brief If there is an active exception, print a traceback to @c stderr
  *
  * This function is exposed as a convenience for repl developers. Normally,
- * the VM will call @c krk_dumpTraceback itself if an exception is unhandled and no
+ * the VM will call @c krk_dumpTraceback() itself if an exception is unhandled and no
  * exit trigger is current set. The traceback is obtained from the exception
  * object. If the exception object does not have a traceback, only the
  * exception itself will be printed. The traceback printer will attempt to
@@ -655,23 +655,25 @@ extern KrkValue krk_dirObject(int argc, KrkValue argv[], int hasKw);
 /**
  * @brief Load a module from a file with a specified name.
  *
- * This is generally called by the import mechanisms to load a single module.
+ * This is generally called by the import mechanisms to load a single module and
+ * will establish a module context internally to load the new module into, return
+ * a KrkValue representing that module context through the @p moduleOut parameter.
  *
  * @param path      Dotted path of the module, used for file lookup.
  * @param moduleOut Receives a value with the module object.
  * @param runAs     Name to attach to @c \__name__ for this module, different from @p path
- * @return 1 if the module was loaded, 0 if an @c ImportError occurred.
+ * @return 1 if the module was loaded, 0 if an @ref ImportError occurred.
  */
 extern int krk_loadModule(KrkString * path, KrkValue * moduleOut, KrkString * runAs);
 
 /**
  * @brief Load a module by a dotted name.
  *
- * Given a package identifier, attempt to the load module
- * into the module table.
+ * Given a package identifier, attempt to the load module into the module table.
+ * This is a thin wrapper around `krk_importModule()`.
  *
  * @param name String object of the dot-separated package path to import.
- * @return 1 if the module was loaded, 0 if an @c ImportError occurred.
+ * @return 1 if the module was loaded, 0 if an @ref ImportError occurred.
  */
 extern int krk_doRecursiveModuleLoad(KrkString * name);
 
@@ -679,7 +681,13 @@ extern int krk_doRecursiveModuleLoad(KrkString * name);
  * @brief Load the dotted name @p name with the final element as @p runAs
  *
  * If @p name was imported previously with a name different from @p runAs,
- * it will be imported again with the new name.
+ * it will be imported again with the new name; this may result in
+ * unexpected behaviour. Generally, @p runAs is used to specify that the
+ * module should be run as `__main__`.
+ *
+ * @param name Dotted path name of a module.
+ * @param runAs Alternative name to attach to @c \__name__ for the module.
+ * @return 1 on success, 0 on failure.
  */
 extern int krk_importModule(KrkString * name, KrkString * runAs);
 
@@ -696,6 +704,21 @@ extern int krk_importModule(KrkString * name, KrkString * runAs);
  */
 extern int krk_isFalsey(KrkValue value);
 
+/**
+ * @brief Obtain a property of an object by name.
+ * @memberof KrkValue
+ *
+ * This is a convenience function that works in essentially the
+ * same way as the OP_GET_PROPERTY instruction.
+ *
+ * @param value Value to examine.
+ * @param name  C-string of the property name to query.
+ * @return The requested property, or None with an @ref AttributeError
+ *         exception set in the current thread if the attribute was
+ *         not found.
+ */
+extern KrkValue krk_valueGetAttribute(KrkValue value, char * name);
+
 /**
  * @brief Concatenate two strings.
  *
@@ -746,4 +769,3 @@ extern KrkValue krk_operator_lt(KrkValue,KrkValue);
 extern KrkValue krk_operator_gt(KrkValue,KrkValue);
 
 
-extern KrkValue krk_valueGetAttribute(KrkValue value, char * name);

test/testExceptionTracebacks.krk.expect

@@ -1,7 +1,7 @@
 Caught a TypeError('A type error')
-  File 'test/testExceptionTracebacks.krk', line 14, in __main__
+  File 'test/testExceptionTracebacks.krk', line 14, in <module>
   File 'test/testExceptionTracebacks.krk', line 4, in doTheThing
 Caught a ValueError('A value error')
-  File 'test/testExceptionTracebacks.krk', line 15, in __main__
+  File 'test/testExceptionTracebacks.krk', line 15, in <module>
   File 'test/testExceptionTracebacks.krk', line 4, in doTheThing
 That's a name error!