adding documentation to public APIs

.gitignore

@@ -1,7 +1,7 @@
 *swp
 .DS_Store
 
-build
+.build
 .cipd
 .gclient_entries
 

README.md

@@ -1 +1,15 @@
-# v8go provides an API to v8 Javascript Engine
+# v8go provides an API to V8 JavaScript Engine
+
+V8 version: 7.6.303.31
+
+## Usage
+
+```go
+import "rogchap.com/v8go"
+```
+
+## V8 Dependancy
+In order to make `v8go` usable as a standard Go package, prebuilt static libraries of V8
+are included for Linux and OSX ie. you should not require to build V8 yourself.
+
+V8 requires 64-bit, therfore will not work on 32-bit systems. 

cgo.go

@@ -1,7 +1,5 @@
 package v8go
 
-// #include <stdlib.h>
-//
 // #cgo CXXFLAGS: -fno-rtti -fpic -std=c++14 -I${SRCDIR}/deps/include
 // #cgo LDFLAGS: -pthread -lv8
 // #cgo darwin LDFLAGS: -L${SRCDIR}/deps/darwin-x86_64

context.go

@@ -5,21 +5,49 @@ package v8go
 import "C"
 import (
 	"errors"
+	"fmt"
 	"runtime"
 	"unsafe"
 )
 
+// Context is a global root execution environment that allows separate,
+// unrelated, JavaScript applications to run in a single instance of V8.
 type Context struct {
+	iso *Isolate
 	ptr C.ContextPtr
 }
 
-func NewContext(iso *Isolate) *Context {
-	ctx := &Context{C.NewContext(iso.ptr)}
+// NewContext creates a new JavaScript context for a given isoltate;
+// if isolate is `nil` than a new isolate will be created.
+func NewContext(iso *Isolate) (*Context, error) {
+	if iso == nil {
+		var err error
+		iso, err = NewIsolate()
+		if err != nil {
+			return nil, fmt.Errorf("context: failed to create new Isolate: %v", err)
+		}
+	}
+
+	// TODO: [RC] does the isolate need to track all the contexts created?
+	// any script run against the context should make sure the VM has not been
+	// terninated
+	ctx := &Context{
+		iso: iso,
+		ptr: C.NewContext(iso.ptr),
+	}
 	runtime.SetFinalizer(ctx, (*Context).finalizer)
-	return ctx
+	// TODO: [RC] catch any C++ exceptions and return as error
+	return ctx, nil
+}
+
+// Isolate gets the current context's parent isolate.An  error is returned
+// if the isolate has been terninated.
+func (c *Context) Isolate() (*Isolate, error) {
+	// TODO: [RC] check to see if the isolate has not been terninated
+	return c.iso, nil
 }
 
-// RunScript executes the source JavaScript; origin or filename  provides a
+// RunScript executes the source JavaScript; origin or filename provides a
 // reference for the script and used in the exception stack trace.
 func (c *Context) RunScript(source string, origin string) (*Value, error) {
 	cSource := C.CString(source)

context_test.go

@@ -8,17 +8,17 @@ import (
 
 func TestRunScriptStringer(t *testing.T) {
 	t.Parallel()
-	var iso = v8go.NewIsolate()
-	ctx := v8go.NewContext(iso)
+	ctx, _ := v8go.NewContext(nil)
 	var tests = [...]struct {
 		name   string
 		source string
 		out    string
 	}{
-		{"Addition", "2 + 2", "4"},
-		{"Multiplication", "13 * 2", "26"},
+		{"Addition", `2 + 2`, "4"},
+		{"Multiplication", `13 * 2`, "26"},
 		{"String", `"string"`, "string"},
 		{"Object", `let obj = {}; obj`, "[object Object]"},
+		{"Function", `let fn = function(){}; fn`, "function(){}"},
 	}
 
 	for _, tt := range tests {

deps/build.py

@@ -40,8 +40,8 @@
 linux_use_bundled_binutils=false
 use_custom_libcxx=false
 use_sysroot=false
-is_debug=true
-symbol_level=1
+is_debug=false
+symbol_level=0
 strip_debug_info=true
 is_component_build=false
 v8_monolithic=true
@@ -55,6 +55,7 @@
 v8_extra_library_files=[]
 v8_untrusted_code_mitigations=false
 v8_use_snapshot=true
+target_cpu="x64"
 """
 
 def v8deps():
@@ -76,7 +77,7 @@ def main():
     ninja_path = os.path.join(tools_path, "ninja")
     assert(os.path.exists(ninja_path))
 
-    build_path = os.path.join(deps_path, "build")
+    build_path = os.path.join(deps_path, ".build", os_arch())
 
     env = os.environ.copy()
     args = gn_args.replace('\n', ' ')

isolate.go

@@ -10,17 +10,24 @@ import (
 
 var v8once sync.Once
 
+// An isolate is a JavaScript VM instance with its own heap and
+// garbage collector. Most applications will create one isolate
+// with many V8 contexts for execution.
 type Isolate struct {
 	ptr C.IsolatePtr
 }
 
-func NewIsolate() *Isolate {
+// NewIsolate creates a new V8 isolate. Only one thread may access
+// a given isolate at a time, but different threads may access
+// different isolates simultaneously.
+func NewIsolate() (*Isolate, error) {
 	v8once.Do(func() {
 		C.Init()
 	})
 	iso := &Isolate{C.NewIsolate()}
 	runtime.SetFinalizer(iso, (*Isolate).finalizer)
-	return iso
+	// TODO: [RC] catch any C++ exceptions and return as error
+	return iso, nil
 }
 
 func (i *Isolate) finalizer() {

value.go

@@ -4,10 +4,14 @@ package v8go
 import "C"
 import "runtime"
 
+// Value represents all Javascript values and objects
 type Value struct {
 	ptr C.ValuePtr
 }
 
+// String will return the string representation of the value. Primitive values
+// are returned as-is, objects will return `[object Object]` and functions will
+// print their definition.
 func (v *Value) String() string {
 	return C.GoString(C.ValueToString(v.ptr))
 }