commit 73419a01ec55ff3eda57c62312d388fe6cffd19d
from: Omar Polo <op@omarpolo.com>
date: Sun Dec 31 13:46:22 2023 UTC

sqlite3: add some documentation

commit - 19e3939cb58be9fc3d590cfe91946c3455a3a6c7
commit + 73419a01ec55ff3eda57c62312d388fe6cffd19d
blob - aae128f2e8a2b83ee5bd1d155da99fd91113fff8
blob + ad6ee451cdf8a0ac43f202053ee12228ca1be30e
--- sqlite3/sqlite3.ha
+++ sqlite3/sqlite3.ha
@@ -95,6 +95,7 @@ export fn open(filename: const str, flags: int...) (co
 
 @symbol("sqlite3_close_v2") fn libsqlite3_close_v2(sqlite3: *opaque) int;
 
+// Closes a database connection.
 export fn close(conn: conn) (void | error) = {
 	let ret = libsqlite3_close_v2(conn: *opaque);
 	if (ret != sqlite_ok) {
@@ -110,6 +111,13 @@ export fn close(conn: conn) (void | error) = {
 	tail: nullable *opaque,
 ) int;
 
+// Prepares a statement that would run the given SQL.  Parameters in
+// the query can be specified using ?, ?NNN, :VVV, @VVV or $VVV (with
+// NNN being a integer literal and VVV an alphanumeric identifier) and
+// later set with [[bind]].  The statement can then ran with [[step]].
+// A statement can be reused by calling [[reset]] (and optionally
+// [[clear_bindings]] too).  Once a statement is no longer needed it
+// should be destroyed with [[finalize]].
 export fn prepare(conn: conn, sql: const str) (statement | error) = {
 	let s = c::fromstr(sql);
 	defer free(s);
@@ -156,6 +164,7 @@ fn bind_parameter_index(stmt: statement, col: (str | i
 	val: int,
 ) int;
 
+// Binds an integer value to the parameter given by name or index.
 export fn bind_int(stmt: statement, col: (str | int), v: int) (void | error) = {
 	let n = bind_parameter_index(stmt, col)?;
 	let ret = libsqlite3_bind_int(stmt: *opaque, n, v);
@@ -169,6 +178,7 @@ export fn bind_int(stmt: statement, col: (str | int), 
 	col: int,
 ) int;
 
+// Binds a NULL value to the parameter given by name or index.
 export fn bind_null(stmt: statement, col: (str | int)) (void | error) = {
 	let n = bind_parameter_index(stmt, col)?;
 	let ret = libsqlite3_bind_null(stmt: *opaque, n);
@@ -187,6 +197,7 @@ fn freecstr(s: *opaque) void = free(s: *c::char);
 	freefn: *fn(*opaque) void
 ) int;
 
+// Binds a text value to the parameter given by name or index.
 export fn bind_text(stmt: statement, col: (str | int), v: str) (void | error) = {
 	let n = bind_parameter_index(stmt, col)?;
 
@@ -199,6 +210,7 @@ export fn bind_text(stmt: statement, col: (str | int),
 	};
 };
 
+// Binds a value to the parameter given by name or index.
 export fn bind(
 	stmt: statement,
 	col: (str | int),
@@ -213,6 +225,10 @@ export fn bind(
 
 @symbol("sqlite3_step") fn libsqlite3_step(stmt: *opaque) int;
 
+// Runs the statement.  This function may need to be called more than
+// one time to evaluate a statement.  A return value of false means
+// that the statement was completely executed, true that it should be
+// called again, otherwise an error is returned.
 export fn step(stmt: statement) (bool | error) = {
 	let ret = libsqlite3_step(stmt: *opaque);
 	switch (ret) {
@@ -227,6 +243,8 @@ export fn step(stmt: statement) (bool | error) = {
 	col: int,
 ) *const c::char;
 
+// Extracts the value of a column as a string.  A NULL value is turned
+// into the empty string "".
 export fn column_text(stmt: statement, col: int) const str = {
 	let s = libsqlite3_column_text(stmt: *opaque, col);
 	if (s == null) {
@@ -240,12 +258,14 @@ export fn column_text(stmt: statement, col: int) const
 	col: int,
 ) int;
 
+// Extracts the values of a column as an integer.
 export fn column_int(stmt: statement, col: int) int = {
 	return libsqlite3_column_int(stmt: *opaque, col);
 };
 
 @symbol("sqlite3_finalize") fn libsqlite3_finalize(stmt: *opaque) int;
 
+// Deallocates a statement.
 export fn finalize(stmt: statement) (void | error) = {
 	let ret = libsqlite3_finalize(stmt: *opaque);
 	if (ret != sqlite_ok) {
@@ -255,6 +275,8 @@ export fn finalize(stmt: statement) (void | error) = {
 
 @symbol("sqlite3_reset") fn libsqlite3_reset(stmt: *opaque) int;
 
+// Resets a statement so that it can be run again.  It doesn't clear
+// the bindings, for that use [[clear_bindings]] too.
 export fn reset(stmt: statement) (void | error) = {
 	let ret = libsqlite3_reset(stmt: *opaque);
 	if (ret != sqlite_ok) {
@@ -264,6 +286,7 @@ export fn reset(stmt: statement) (void | error) = {
 
 @symbol("sqlite3_clear_bindings") fn libsqlite3_clear_bindings(stmt: *opaque) int;
 
+// Clears the bindings associated with a statement.
 export fn clear_bindings(stmt: statement) (void | error) = {
 	let ret = libsqlite3_clear_bindings(stmt: *opaque);
 	if (ret != sqlite_ok) {
@@ -271,6 +294,7 @@ export fn clear_bindings(stmt: statement) (void | erro
 	};
 };
 
+// Helper that runs a statement until it has been fully processed.
 export fn runstmt(stmt: statement) (void | error) = {
 	for (step(stmt)?) {
 		continue;