Add doc comments for public types

inspector.go

@@ -7,6 +7,8 @@ import (
 	"unicode/utf16"
 )
 
+// Represents the level of console output from JavaScript. E.g., `console.log`,
+// `console.error`, etc.
 type MessageErrorLevel uint8
 
 const (
@@ -18,15 +20,30 @@ const (
 	ErrorLevelAll = ErrorLevelLog | ErrorLevelDebug | ErrorLevelInfo | ErrorLevelError | ErrorLevelWarning
 )
 
+// An Inspector in v8 provides access to internals of the engine, such as
+// console output
+//
+// To receive console output, you need to first create an [InspectorClient]
+// which will handle the interaction for a specific [Context].
+//
+// After a Context is created, you need to register it with the Inspector using
+// [Inspector.ContextCreated], and cleanup using [Inspector.ContextDestroyed].
+//
+// See also: https://v8.github.io/api/head/classv8__inspector_1_1V8Inspector.html
 type Inspector struct {
 	ptr C.InspectorPtr
 }
 
+// An InspectorClient is the bridge from the [Inspector] to your code.
 type InspectorClient struct {
 	ptr          C.InspectorClientPtr
 	clientHandle cgo.Handle
 }
 
+// ConsoleAPIMessage contains the information from v8 from console function
+// calls.
+//
+// V8 also provides a stack trace, which isn't yet supported here.
 type ConsoleAPIMessage struct {
 	contextGroupId int
 	ErrorLevel     MessageErrorLevel
@@ -37,35 +54,42 @@ type ConsoleAPIMessage struct {
 	// stackTrace StackTrace
 }
 
+// A ConsoleAPIMessageHandler will receive JavaScript `console` API calls.
 type ConsoleAPIMessageHandler interface {
 	ConsoleAPIMessage(message ConsoleAPIMessage)
 }
 
-type ConsoleAPIMessageHandlerFunc func(msg ConsoleAPIMessage)
-
-func (f ConsoleAPIMessageHandlerFunc) ConsoleAPIMessage(msg ConsoleAPIMessage) {
-	f(msg)
-}
-
+// NewInspector creates an [Inspector] for a specific [Isolate] iso
+// communicating with the [InspectorClient] client.
+//
+// Before disposing the iso, be sure to dispose the inspector using
+// [Inspector.Dispose]
 func NewInspector(iso *Isolate, client *InspectorClient) *Inspector {
 	ptr := C.CreateInspector(iso.ptr, client.ptr)
 	return &Inspector{
 		ptr: ptr,
 	}
 }
 
+// Dispose the [Inspector]. Call this before disposing the [Isolate] and the
+// [InspectorClient] that this is connected to.
 func (i *Inspector) Dispose() {
 	C.DeleteInspector(i.ptr)
 }
 
+// ContextCreated tells the inspector that a new [Context] has been created.
+// This must be called before the [InspectorClient] can be used.
 func (i *Inspector) ContextCreated(ctx *Context) {
 	C.InspectorContextCreated(i.ptr, ctx.ptr)
 }
 
+// ContextDestroyed must be called before a [Context] is closed.
 func (i *Inspector) ContextDestroyed(ctx *Context) {
 	C.InspectorContextDestroyed(i.ptr, ctx.ptr)
 }
 
+// Create a new [InspectorClient] passing a handler that will receive the
+// callbacks from v8.
 func NewInspectorClient(handler ConsoleAPIMessageHandler) *InspectorClient {
 	clientHandle := cgo.NewHandle(handler)
 	ptr := C.NewInspectorClient(C.uintptr_t(clientHandle))
@@ -75,7 +99,10 @@ func NewInspectorClient(handler ConsoleAPIMessageHandler) *InspectorClient {
 	}
 }
 
+// Dispose frees up resources taken up by the [InspectorClient]. Be sure to call
+// this after calling [Inspector.Dispose]
 func (c *InspectorClient) Dispose() {
+	c.clientHandle.Delete()
 	C.DeleteInspectorClient(c.ptr)
 }
 
@@ -93,7 +120,6 @@ func stringViewToString(d C.StringViewData) string {
 	}
 }
 
-//
 //export goHandleConsoleAPIMessageCallback
 func goHandleConsoleAPIMessageCallback(
 	callbackRef C.uintptr_t,
@@ -104,16 +130,16 @@ func goHandleConsoleAPIMessageCallback(
 	lineNumber C.uint,
 	columnNumber C.uint,
 ) {
-	// Convert data to Go data
 	handle := cgo.Handle(callbackRef)
 	if client, ok := handle.Value().(ConsoleAPIMessageHandler); ok {
 		// TODO, Stack trace
 		client.ConsoleAPIMessage(ConsoleAPIMessage{
-			ErrorLevel:   MessageErrorLevel(errorLevel),
-			Message:      stringViewToString(message),
-			Url:          stringViewToString(url),
-			LineNumber:   uint(lineNumber),
-			ColumnNumber: uint(columnNumber),
+			contextGroupId: int(contextGroupId),
+			ErrorLevel:     MessageErrorLevel(errorLevel),
+			Message:        stringViewToString(message),
+			Url:            stringViewToString(url),
+			LineNumber:     uint(lineNumber),
+			ColumnNumber:   uint(columnNumber),
 		})
 	}
 }