Add documentation

go/engine/engine.go

@@ -30,7 +30,7 @@ func NewEngine(st *state.State, rs resource.Resource) Engine {
 
 // Init must be explicitly called before using the Engine instance.
 //
-// It makes sure bootstrapping code has been executed, and that the exposed bytecode is ready for user input.
+// It loads and executes code for the start node.
 func(en *Engine) Init(sym string, ctx context.Context) error {
 	err := en.st.SetInput([]byte{})
 	if err != nil {
@@ -47,16 +47,12 @@ func(en *Engine) Init(sym string, ctx context.Context) error {
 
 // Exec processes user input against the current state of the virtual machine environment.
 //
-// If successfully executed:
+// If successfully executed, output of the last execution is available using the WriteResult call.
-// - output of the last execution is available using the WriteResult(...) call
+// 
-// - Exec(...) may be called again with new input
+// A bool return valus of false indicates that execution should be terminated. Calling Exec again has undefined effects.
-//
-// This implementation is in alpha state. That means that any error emitted may have left the system in an undefined state.
-//
-// TODO: Disambiguate errors as critical and resumable errors.
 //
 // Fails if:
-// - input is objectively invalid (too long etc)
+// - input is formally invalid (too long etc)
 // - no current bytecode is available
 // - input processing against bytcode failed
 func (en *Engine) Exec(input []byte, ctx context.Context) (bool, error) {
@@ -89,6 +85,10 @@ func (en *Engine) Exec(input []byte, ctx context.Context) (bool, error) {
 	}
 
 	en.st.SetCode(code)
+	if len(code) == 0 {
+		log.Printf("runner finished with no remaining code")
+		return false, nil
+	}
 
 	return true, nil
 }

go/resource/render.go

@@ -5,6 +5,7 @@ import (
 	"text/template"
 )
 
+// DefaultRenderTemplate is an adapter to implement the builtin golang text template renderer as resource.RenderTemplate.
 func DefaultRenderTemplate(r Resource, sym string, values map[string]string) (string, error) {
 	v, err := r.GetTemplate(sym)
 	if err != nil {

go/resource/resource.go

@@ -17,8 +17,8 @@ type Resource interface {
 	ShiftMenu() (string, string, error) // Remove and return the first menu item in list.
 	SetMenuBrowse(string, string, bool) error // Set menu browser display details.
 	RenderTemplate(sym string, values map[string]string) (string, error) // Render the given data map using the template of the symbol.
-	RenderMenu() (string, error)
+	RenderMenu() (string, error) // Render the current state of menu
-	FuncFor(sym string) (EntryFunc, error) // Resolve symbol code point for.
+	FuncFor(sym string) (EntryFunc, error) // Resolve symbol content point for.
 }
 
 type MenuResource struct {
@@ -27,6 +27,11 @@ type MenuResource struct {
 	prev [2]string
 }
 
+// SetMenuBrowse defines the how pagination menu options should be displayed.
+//
+// The selector is the expected user input, and the title is the description string.
+//
+// If back is set, the option will be defined for returning to a previous page.
 func(m *MenuResource) SetMenuBrowse(selector string, title string, back bool) error {
 	entry := [2]string{selector, title}
 	if back {
@@ -37,12 +42,16 @@ func(m *MenuResource) SetMenuBrowse(selector string, title string, back bool) er
 	return nil
 }
 
+// PutMenu adds a menu option to the menu rendering.
 func(m *MenuResource) PutMenu(selector string, title string) error {
 	m.menu = append(m.menu, [2]string{selector, title})
 	log.Printf("menu %v", m.menu)
 	return nil
 }
 
+// PutMenu removes and returns the first of remaining menu options.
+//
+// Fails if menu is empty.
 func(m *MenuResource) ShiftMenu() (string, string, error) {
 	if len(m.menu) == 0 {
 		return "", "", fmt.Errorf("menu is empty")
@@ -52,6 +61,9 @@ func(m *MenuResource) ShiftMenu() (string, string, error) {
 	return r[0], r[1], nil
 }
 
+// RenderMenu returns the full current state of the menu as a string.
+//
+// After this has been executed, the state of the menu will be empty.
 func(m *MenuResource) RenderMenu() (string, error) {
 	r := ""
 	for true {