document almost all api functions and minor refactors

src/database/database.v

···
+// **all** interactions with the database should be handled in this module.
 module database
 
 import db.pg
 
-// all interactions with the database should be handled through this struct.
+// DatabaseAccess handles all interactions with the database.
 pub struct DatabaseAccess {
 pub mut:
 	db pg.DB

src/database/like.v

···
 
 import entity { Like, LikeCache }
 
-// returns the net likes of the given post
+// get_net_likes_for_post returns the net likes of the given post.
 pub fn (app &DatabaseAccess) get_net_likes_for_post(post_id int) int {
 	// check cache
 	cache := sql app.db {

src/database/notification.v

···
 
 import entity { Notification }
 
-// get a list of notifications for the given user
+// get_notifications_for gets a list of notifications for the given user.
 pub fn (app &DatabaseAccess) get_notifications_for(user_id int) []Notification {
 	notifications := sql app.db {
 		select from Notification where user_id == user_id
···
 	return notifications
 }
 
-// get the amount of notifications a user has, with a given limit
+// get_notification_count gets the amount of notifications a user has, with a
+// given limit.
 pub fn (app &DatabaseAccess) get_notification_count(user_id int, limit int) int {
 	notifications := sql app.db {
 		select from Notification where user_id == user_id limit limit
···
 	return notifications.len
 }
 
-// send a notification to the given user
+// send_notification_to sends a notification to the given user.
 pub fn (app &DatabaseAccess) send_notification_to(user_id int, summary string, body string) {
 	notification := Notification{
 		user_id: user_id

src/database/post.v

···
 import time
 import entity { Post, Like, LikeCache }
 
-// get a post by its id, returns none if it does not exist
+// get_post_by_id gets a post by its id, returns none if it does not exist.
 pub fn (app &DatabaseAccess) get_post_by_id(id int) ?Post {
 	posts := sql app.db {
 		select from Post where id == id limit 1
···
 	return posts[0]
 }
 
-// get a post by its author and timestamp, returns none if it does not exist
+// get_post_by_author_and_timestamp gets a post by its author and timestamp,
+// returns none if it does not exist
 pub fn (app &DatabaseAccess) get_post_by_author_and_timestamp(author_id int, timestamp time.Time) ?Post {
 	posts := sql app.db {
 		select from Post where author_id == author_id && posted_at == timestamp order by posted_at desc limit 1
···
 	return posts[0]
 }
 
-// get a list of posts given a tag. this performs sql string operations and
-// probably is not very efficient, use sparingly.
+// get_posts_with_tag gets a list of the 10 most recent posts with the given tag.
+// this performs sql  string operations and probably is not very efficient, use
+// sparingly.
 pub fn (app &DatabaseAccess) get_posts_with_tag(tag string, offset int) []Post {
 	posts := sql app.db {
 		select from Post where body like '%#(${tag})%' order by posted_at desc limit 10 offset offset
···
 	return posts
 }
 
-// returns a list of all pinned posts
+// get_pinned_posts returns a list of all pinned posts.
 pub fn (app &DatabaseAccess) get_pinned_posts() []Post {
 	posts := sql app.db {
 		select from Post where pinned == true
···
 	return posts
 }
 
-// returns a list of the ten most recent posts.
+// get_recent_posts returns a list of the ten most recent posts.
 pub fn (app &DatabaseAccess) get_recent_posts() []Post {
 	posts := sql app.db {
 		select from Post order by posted_at desc limit 10
···
 	return posts
 }
 
-// returns a list of the ten most liked posts.
+// get_popular_posts returns a list of the ten most liked posts.
 // TODO: make this time-gated (i.e, top ten liked posts of the day)
 pub fn (app &DatabaseAccess) get_popular_posts() []Post {
 	cached_likes := sql app.db {
···
 	return posts
 }
 
-// returns a list of all posts from a user in descending order of date
+// get_posts_from_user returns a list of all posts from a user in descending
+// order by posting date.
 pub fn (app &DatabaseAccess) get_posts_from_user(user_id int) []Post {
 	posts := sql app.db {
 		select from Post where author_id == user_id order by posted_at desc

src/database/user.v

···
 
 import entity { User, Notification, Like, Post }
 
-// creates a new user and returns their struct after creation.
+// new_user creates a new user and returns their struct after creation.
 pub fn (app &DatabaseAccess) new_user(user User) ?User {
 	sql app.db {
 		insert user into User
···
 	return app.get_user_by_name(user.username)
 }
 
-// updates the given user's username, returns true if this succeeded and false
-// otherwise.
+// set_username sets the given user's username, returns true if this succeeded
+// and false otherwise.
 pub fn (app &DatabaseAccess) set_username(user_id int, new_username string) bool {
 	sql app.db {
 		update User set username = new_username where id == user_id
···
 	return true
 }
 
-// updates the given user's password, returns true if this succeeded and false
-// otherwise.
+// set_password sets the given user's password, returns true if this succeeded
+// and false otherwise.
 pub fn (app &DatabaseAccess) set_password(user_id int, hashed_new_password string) bool {
 	sql app.db {
 		update User set password = hashed_new_password where id == user_id
···
 	return true
 }
 
-// updates the given user's nickname, returns true if this succeeded and false
-// otherwise.
+// set_nickname sets the given user's nickname, returns true if this succeeded
+// and false otherwise.
 pub fn (app &DatabaseAccess) set_nickname(user_id int, new_nickname ?string) bool {
 	sql app.db {
 		update User set nickname = new_nickname where id == user_id
···
 	return true
 }
 
-// updates the given user's muted status, returns true if this succeeded and
-// false otherwise.
+// set_muted sets the given user's muted status, returns true if this succeeded
+// and false otherwise.
 pub fn (app &DatabaseAccess) set_muted(user_id int, muted bool) bool {
 	sql app.db {
 		update User set muted = muted where id == user_id
···
 	return true
 }
 
-// updates the given user's theme url, returns true if this succeeded and false
-// otherwise.
+// set_theme sets the given user's theme url, returns true if this succeeded and
+// false otherwise.
 pub fn (app &DatabaseAccess) set_theme(user_id int, theme ?string) bool {
 	sql app.db {
 		update User set theme = theme where id == user_id
···
 	return true
 }
 
-// updates the given user's pronouns, returns true if this succeeded and false
-// otherwise.
+// set_pronouns sets the given user's pronouns, returns true if this succeeded
+// and false otherwise.
 pub fn (app &DatabaseAccess) set_pronouns(user_id int, pronouns string) bool {
 	sql app.db {
 		update User set pronouns = pronouns where id == user_id
···
 	return true
 }
 
-// updates the given user's bio, returns true if this succeeded and false
+// set_bio sets the given user's bio, returns true if this succeeded and false
 // otherwise.
 pub fn (app &DatabaseAccess) set_bio(user_id int, bio string) bool {
 	sql app.db {
···
 	return true
 }
 
-// get a user by their username, returns none if the user was not found.
+// get_user_by_name gets a user by their username, returns none if the user was
+// not found.
 pub fn (app &DatabaseAccess) get_user_by_name(username string) ?User {
 	users := sql app.db {
 		select from User where username == username
···
 	return users[0]
 }
 
-// get a user by their id, returns none if the user was not found.
+// get_user_by_id gets a user by their id, returns none if the user was not
+// found.
 pub fn (app &DatabaseAccess) get_user_by_id(id int) ?User {
 	users := sql app.db {
 		select from User where id == id
···
 	return users[0]
 }
 
-// returns all users
+// get_users returns all users.
 pub fn (app &DatabaseAccess) get_users() []User {
 	users := sql app.db {
 		select from User
···
 	return users
 }
 
-// returns true if a user likes the given post
+// does_user_like_post returns true if a user likes the given post.
 pub fn (app &DatabaseAccess) does_user_like_post(user_id int, post_id int) bool {
 	likes := sql app.db {
 		select from Like where user_id == user_id && post_id == post_id
···
 	return likes.first().is_like
 }
 
-// returns true if a user dislikes the given post
+// does_user_dislike_post returns true if a user dislikes the given post.
 pub fn (app &DatabaseAccess) does_user_dislike_post(user_id int, post_id int) bool {
 	likes := sql app.db {
 		select from Like where user_id == user_id && post_id == post_id
···
 	return !likes.first().is_like
 }
 
-// returns true if a user likes or dislikes the given post
+// does_user_like_or_dislike_post returns true if a user likes *or* dislikes the
+// given post.
 pub fn (app &DatabaseAccess) does_user_like_or_dislike_post(user_id int, post_id int) bool {
 	likes := sql app.db {
 		select from Like where user_id == user_id && post_id == post_id

src/entity/likes.v

···
 module entity
 
-// stores like information for posts
+// Like stores like information for a post.
 pub struct Like {
 pub mut:
 	id      int @[primary; sql: serial]
···
 	is_like bool
 }
 
-// Stores total likes per post
+// LikeCache stores the total likes for a post.
 pub struct LikeCache {
 pub mut:
 	id      int @[primary; sql: serial]

src/entity/site.v

···
 module entity
 
+// Site stores mutable site-wide config and data.
 pub struct Site {
 pub mut:
 	id   int @[primary; sql: serial]

src/entity/user.v

···
 	muted bool
 	admin bool
 
-	theme ?string
+	theme string
 
 	bio      string
 	pronouns string
···
 	created_at time.Time = time.now()
 }
 
+// get_name returns the user's nickname if it is not none, if so then their
+// username is returned.
 @[inline]
 pub fn (user User) get_name() string {
 	return user.nickname or { user.username }
 }
 
-@[inline]
-pub fn (user User) get_theme() string {
-	return user.theme or { '' }
-}
-
+// to_str_without_sensitive_data returns the stringified data for the user with
+// their password and salt censored.
 @[inline]
 pub fn (user User) to_str_without_sensitive_data() string {
 	return user.str()

src/main.v

···
 import os
 import webapp { App, Context, StringValidator }
 
-fn init_db(db pg.DB) ! {
-	sql db {
-		create table entity.Site
-		create table entity.User
-		create table entity.Post
-		create table entity.Like
-		create table entity.LikeCache
-		create table entity.Notification
-	}!
-}
-
 fn main() {
 	config := webapp.load_config_from(os.args[1])
 
···
 	app.mount_static_folder_at(app.config.static_path, '/static')!
 
 	println('-> initializing database...')
-	init_db(db)!
+	sql db {
+		create table entity.Site
+		create table entity.User
+		create table entity.Post
+		create table entity.Like
+		create table entity.LikeCache
+		create table entity.Notification
+	}!
 	println('<- done')
 
 	// make the website config, if it does not exist

src/templates/partial/header.html

···
 
 	@include 'assets/style.html'
 
-	@if ctx.is_logged_in() && user.theme != none
-	<link rel="stylesheet" href="@user.get_theme()">
+	@if ctx.is_logged_in() && user.theme != ''
+	<link rel="stylesheet" href="@user.theme">
 	@else if app.config.instance.default_theme != ''
 	<link rel="stylesheet" href="@app.config.instance.default_theme">
 	@endif

src/templates/settings.html

···
 
 <form action="/api/user/set_theme" method="post">
 	<label for="url">theme:</label>
-	<input type="url" name="url" id="url" value="@{user.theme or { '' }}">
+	<input type="url" name="url" id="url" value="@user.theme">
 	<input type="submit" value="save">
 </form>
 @end

src/webapp/app.v

···
 	}
 }
 
-// get a user by their token, returns none if the user was not found.
+// get_user_by_token returns a user by their token, returns none if the user was
+// not found.
 pub fn (app &App) get_user_by_token(ctx &Context, token string) ?User {
 	user_token := app.auth.find_token(token, ctx.ip()) or {
 		eprintln('no such user corresponding to token')
···
 	return app.get_user_by_id(user_token.user_id)
 }
 
-// returns the current logged in user, or none if the user is not logged in.
+// whoami returns the current logged in user, or none if the user is not logged
+// in.
 pub fn (app &App) whoami(mut ctx Context) ?User {
 	token := ctx.get_cookie('token') or { return none }.trim_space()
 	if token == '' {
···
 	}
 }
 
-// get a user representing an unknown user
+// get_unknown_user returns a user representing an unknown user
 pub fn (app &App) get_unknown_user() User {
 	return User{
 		username: 'unknown'
 	}
 }
 
-// get a post representing an unknown post
+// get_unknown_post returns a post representing an unknown post
 pub fn (app &App) get_unknown_post() Post {
 	return Post{
 		title: 'unknown'
 	}
 }
 
-// returns true if the user is logged in as the provided user id.
+// logged_in_as returns true if the user is logged in as the provided user id.
 pub fn (app &App) logged_in_as(mut ctx Context, id int) bool {
 	if !ctx.is_logged_in() {
 		return false
···
 	return app.whoami(mut ctx) or { return false }.id == id
 }
 
-// get the site's message of the day.
+// get_motd returns the site's message of the day.
 @[inline]
 pub fn (app &App) get_motd() string {
 	site := app.get_or_create_site_config()
 	return site.motd
 }
 
-// get the notification count for a given user, formatted for usage on the
-// frontend.
+// get_notification_count_for_frontend returns the notification count for a
+// given user, formatted for usage on the frontend.
 pub fn (app &App) get_notification_count_for_frontend(user_id int, limit int) string {
 	count := app.get_notification_count(user_id, limit)
 	if count == 0 {
···
 	}
 }
 
-// processes a post's body to send notifications for mentions or replies.
+// process_post_mentions parses a post's body to send notifications for mentions
+// or replies.
 pub fn (app &App) process_post_mentions(post &Post) {
 	author := app.get_user_by_id(post.author_id) or {
 		eprintln('process_post_mentioned called on a post with a non-existent author: ${post}')

src/webapp/config.v

···
 
 import emmathemartian.maple
 
+// Config stores constant site-wide configuration data.
 pub struct Config {
 pub mut:
 	dev_mode    bool

src/webapp/validation.v

···
 
 import regex
 
-// handles validation of user-input fields
+// StringValidator handles validation of user-input fields.
 pub struct StringValidator {
 pub:
 	min_len int
···
 	pattern regex.RE
 }
 
+// validate validates a given string and returns true if it succeeded and false
+// otherwise.
 @[inline]
 pub fn (validator StringValidator) validate(str string) bool {
 	return str.len > validator.min_len && str.len < validator.max_len
 		&& validator.pattern.matches_string(str)
 }
 
+// StringValidator.new creates a new StringValidator with the given min, max,
+// and pattern.
 pub fn StringValidator.new(min int, max int, pattern string) StringValidator {
 	mut re := regex.new()
 	re.compile_opt(pattern) or { panic(err) }