From ccac3032ababd1478059998278d0cdca1f5a5832 Mon Sep 17 00:00:00 2001
From: Nuno Cruces <ncruces@users.noreply.github.com>
Date: Thu, 9 Feb 2023 16:40:48 +0000
Subject: [PATCH] Documentation.

---
 conn.go           | 31 ++++++++++++++++++++++++++-----
 error.go          | 27 ++++++++++++++++++++++-----
 tests/dir_test.go |  2 +-
 3 files changed, 49 insertions(+), 11 deletions(-)

diff --git a/conn.go b/conn.go
index b2f547d..6b838b8 100644
--- a/conn.go
+++ b/conn.go
@@ -4,6 +4,9 @@ import (
 	"context"
 )
 
+// Conn is a database connection handle.
+//
+// https://www.sqlite.org/c3ref/sqlite3.html
 type Conn struct {
 	ctx    context.Context
 	api    sqliteAPI
@@ -11,10 +14,14 @@ type Conn struct {
 	handle uint32
 }
 
+// Open calls [OpenFlags] with [OPEN_READWRITE] and [OPEN_CREATE].
 func Open(filename string) (conn *Conn, err error) {
 	return OpenFlags(filename, OPEN_READWRITE|OPEN_CREATE)
 }
 
+// OpenFlags opens an SQLite database file as specified by the filename argument.
+//
+// https://www.sqlite.org/c3ref/open.html
 func OpenFlags(filename string, flags OpenFlag) (conn *Conn, err error) {
 	ctx := context.Background()
 	module, err := sqlite3.instantiateModule(ctx)
@@ -46,6 +53,12 @@ func OpenFlags(filename string, flags OpenFlag) (conn *Conn, err error) {
 	return c, nil
 }
 
+// Close closes a database connection.
+// If the database connection is associated with unfinalized prepared statements,
+// open blob handles, and/or unfinished backup objects,
+// Close will leave the database connection open and return [BUSY].
+//
+// https://www.sqlite.org/c3ref/close.html
 func (c *Conn) Close() error {
 	r, err := c.api.close.Call(c.ctx, uint64(c.handle))
 	if err != nil {
@@ -58,6 +71,10 @@ func (c *Conn) Close() error {
 	return c.mem.mod.Close(c.ctx)
 }
 
+// Exec is a convenience function that allows an application to run
+// multiple statements of SQL without having to use a lot of code.
+//
+// https://www.sqlite.org/c3ref/exec.html
 func (c *Conn) Exec(sql string) error {
 	sqlPtr := c.newString(sql)
 	defer c.free(sqlPtr)
@@ -69,10 +86,17 @@ func (c *Conn) Exec(sql string) error {
 	return c.error(r[0])
 }
 
+// Prepare calls [PrepareFlags] with no flags.
 func (c *Conn) Prepare(sql string) (stmt *Stmt, tail string, err error) {
 	return c.PrepareFlags(sql, 0)
 }
 
+// PrepareFlags compiles the first statement in sql;
+// tail is left pointing to what remains uncompiled.
+// If the input text contains no SQL (if the input is an empty string or a comment),
+// both stmt and err will be nil
+//
+// https://www.sqlite.org/c3ref/exec.html
 func (c *Conn) PrepareFlags(sql string, flags PrepareFlag) (stmt *Stmt, tail string, err error) {
 	sqlPtr := c.newString(sql)
 	stmtPtr := c.new(ptrlen)
@@ -107,12 +131,9 @@ func (c *Conn) error(rc uint64) error {
 		return nil
 	}
 
-	err := Error{
-		Code:         ErrorCode(rc),
-		ExtendedCode: ExtendedErrorCode(rc),
-	}
+	err := Error{code: rc}
 
-	if err.Code == NOMEM || err.ExtendedCode == IOERR_NOMEM {
+	if err.Code() == NOMEM || err.ExtendedCode() == IOERR_NOMEM {
 		panic(oomErr)
 	}
 
diff --git a/error.go b/error.go
index 61fc68f..47585f9 100644
--- a/error.go
+++ b/error.go
@@ -6,13 +6,30 @@ import (
 	"strings"
 )
 
+// Error wraps an SQLite Error Code.
+//
+// https://www.sqlite.org/c3ref/errcode.html
 type Error struct {
-	Code         ErrorCode
-	ExtendedCode ExtendedErrorCode
-	str          string
-	msg          string
+	code uint64
+	str  string
+	msg  string
 }
 
+// Code returns the primary error code for this error.
+//
+// https://www.sqlite.org/rescode.html
+func (e *Error) Code() ErrorCode {
+	return ErrorCode(e.code)
+}
+
+// ExtendedCode returns the extended error code for this error.
+//
+// https://www.sqlite.org/rescode.html
+func (e *Error) ExtendedCode() ExtendedErrorCode {
+	return ExtendedErrorCode(e.code)
+}
+
+// Error implements the error interface.
 func (e *Error) Error() string {
 	var b strings.Builder
 	b.WriteString("sqlite3: ")
@@ -20,7 +37,7 @@ func (e *Error) Error() string {
 	if e.str != "" {
 		b.WriteString(e.str)
 	} else {
-		b.WriteString(strconv.Itoa(int(e.Code)))
+		b.WriteString(strconv.Itoa(int(e.code)))
 	}
 
 	if e.msg != "" {
diff --git a/tests/dir_test.go b/tests/dir_test.go
index 10ba8d3..35e7b07 100644
--- a/tests/dir_test.go
+++ b/tests/dir_test.go
@@ -17,7 +17,7 @@ func TestDir(t *testing.T) {
 	if !errors.As(err, &serr) {
 		t.Fatal("want sqlite3.Error")
 	}
-	if serr.Code != sqlite3.CANTOPEN {
+	if serr.Code() != sqlite3.CANTOPEN {
 		t.Error("want sqlite3.CANTOPEN")
 	}
 	if got := err.Error(); got != "sqlite3: unable to open database file" {