Add descriptive comments to most Go functions

1 files changed, 14 insertions, 1 deletions

diff --git a/database.go b/database.go
index 5205214..87fa9f4 100644
--- a/database.go
+++ b/database.go
@@ -7,10 +7,23 @@ import (
 	"context"
 
 	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
 )
 
+// TODO: All database handling logic in all request handlers must be revamped.
+// We must ensure that each request has all logic in one transaction (subject
+// to exceptions if appropriate) so they get a consistent view of the database
+// at a single point. A failure to do so may cause things as serious as
+// privilege escalation.
+
+// database serves as the primary database handle for this entire application.
+// Transactions or single reads may be used therefrom. A [pgxpool.Pool] is
+// necessary to safely use pgx concurrently; pgx.Conn, etc. are insufficient.
+var database *pgxpool.Pool
+
 // queryNameDesc is a helper function that executes a query and returns a
-// list of name_desc_t results.
+// list of nameDesc results. The query must return two string arguments, i.e. a
+// name and a description.
 func queryNameDesc(ctx context.Context, query string, args ...any) (result []nameDesc, err error) {
 	var rows pgx.Rows