From f9f440500efd10aad30f13bd78f3aac2cc15f276 Mon Sep 17 00:00:00 2001
From: Jef Roosens <roosensjef@gmail.com>
Date: Sat, 30 Apr 2022 20:22:03 +0200
Subject: [PATCH] docs: added comment string to each function

---
 src/build/build.v                | 9 +++++++++
 src/cron/daemon/daemon.v         | 6 ++++++
 src/cron/expression/expression.v | 5 +++++
 src/docker/docker.v              | 4 ++++
 src/git/cli.v                    | 6 ++++++
 src/git/client.v                 | 3 +++
 src/package/package.v            | 1 +
 src/repo/sync.v                  | 4 +++-
 src/server/auth.v                | 1 +
 src/server/git.v                 | 5 +++++
 src/server/routes.v              | 4 ++++
 src/web/parse.v                  | 2 ++
 12 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/src/build/build.v b/src/build/build.v
index 5f54564..2365fef 100644
--- a/src/build/build.v
+++ b/src/build/build.v
@@ -10,6 +10,11 @@ const container_build_dir = '/build'
 
 const build_image_repo = 'vieter-build'
 
+// create_build_image creates a builder image given some base image which can
+// then be used to build & package Arch images. It mostly just updates the
+// system, install some necessary packages & creates a non-root user to run
+// makepkg with. The base image should be some Linux distribution that uses
+// Pacman as its package manager.
 pub fn create_build_image(base_image string) ?string {
 	commands := [
 		// Update repos & install required packages
@@ -67,6 +72,9 @@ pub fn create_build_image(base_image string) ?string {
 	return image.id
 }
 
+// build_repo builds, packages & publishes a given Arch package based on the
+// provided GitRepo. The base image ID should be of an image previously created
+// by create_build_image.
 pub fn build_repo(address string, api_key string, base_image_id string, repo &git.GitRepo) ? {
 	build_arch := os.uname().machine
 
@@ -113,6 +121,7 @@ pub fn build_repo(address string, api_key string, base_image_id string, repo &gi
 	docker.remove_container(id) ?
 }
 
+// build builds every Git repo in the server's list.
 fn build(conf Config) ? {
 	build_arch := os.uname().machine
 
diff --git a/src/cron/daemon/daemon.v b/src/cron/daemon/daemon.v
index 09ccc3e..4b22522 100644
--- a/src/cron/daemon/daemon.v
+++ b/src/cron/daemon/daemon.v
@@ -16,6 +16,7 @@ pub:
 	timestamp time.Time
 }
 
+// Overloaded operator for comparing ScheduledBuild objects
 fn (r1 ScheduledBuild) < (r2 ScheduledBuild) bool {
 	return r1.timestamp < r2.timestamp
 }
@@ -147,6 +148,8 @@ fn (mut d Daemon) schedule_build(repo_id string, repo git.GitRepo) ? {
 	})
 }
 
+// renew_repos requests the newest list of Git repos from the server & replaces
+// the old one.
 fn (mut d Daemon) renew_repos() ? {
 	d.linfo('Renewing repos...')
 	mut new_repos := git.get_repos(d.address, d.api_key) ?
@@ -189,6 +192,7 @@ fn (mut d Daemon) renew_queue() ? {
 	}
 }
 
+// rebuild_base_image recreates the builder image.
 fn (mut d Daemon) rebuild_base_image() ? {
 	d.linfo('Rebuilding builder image....')
 
@@ -196,6 +200,8 @@ fn (mut d Daemon) rebuild_base_image() ? {
 	d.image_build_timestamp = time.now().add_seconds(60 * d.image_rebuild_frequency)
 }
 
+// clean_old_base_images tries to remove any old but still present builder
+// images.
 fn (mut d Daemon) clean_old_base_images() {
 	mut i := 0
 
diff --git a/src/cron/expression/expression.v b/src/cron/expression/expression.v
index 652870d..124337f 100644
--- a/src/cron/expression/expression.v
+++ b/src/cron/expression/expression.v
@@ -65,6 +65,7 @@ pub fn (ce &CronExpression) next(ref time.Time) ?time.Time {
 	if minute_index == ce.minutes.len && hour_index < ce.hours.len {
 		hour_index += 1
 	}
+
 	if hour_index == ce.hours.len && day_index < ce.days.len {
 		day_index += 1
 	}
@@ -197,6 +198,8 @@ fn parse_range(s string, min int, max int, mut bitv []bool) ? {
 	}
 }
 
+// bitv_to_ints converts a bit vector into an array containing the
+// corresponding values.
 fn bitv_to_ints(bitv []bool, min int) []int {
 	mut out := []int{}
 
@@ -209,6 +212,8 @@ fn bitv_to_ints(bitv []bool, min int) []int {
 	return out
 }
 
+// parse_part parses a given part of a cron expression & returns the
+// corresponding array of ints.
 fn parse_part(s string, min int, max int) ?[]int {
 	mut bitv := []bool{len: max - min + 1, init: false}
 
diff --git a/src/docker/docker.v b/src/docker/docker.v
index 07ceb8e..5deef83 100644
--- a/src/docker/docker.v
+++ b/src/docker/docker.v
@@ -9,6 +9,8 @@ const socket = '/var/run/docker.sock'
 
 const buf_len = 1024
 
+// send writes a request to the Docker socket, waits for a response & returns
+// it.
 fn send(req &string) ?http.Response {
 	// Open a connection to the socket
 	mut s := unix.connect_stream(docker.socket) or {
@@ -72,12 +74,14 @@ fn send(req &string) ?http.Response {
 	return http.parse_response(res.bytestr())
 }
 
+// request_with_body sends a request to the Docker socket with the given body.
 fn request_with_body(method string, url urllib.URL, content_type string, body string) ?http.Response {
 	req := '$method $url.request_uri() HTTP/1.1\nHost: localhost\nContent-Type: $content_type\nContent-Length: $body.len\n\n$body\n\n'
 
 	return send(req)
 }
 
+// request sends a request to the Docker socket with an empty body.
 fn request(method string, url urllib.URL) ?http.Response {
 	req := '$method $url.request_uri() HTTP/1.1\nHost: localhost\n\n'
 
diff --git a/src/git/cli.v b/src/git/cli.v
index 463f1ba..53527d5 100644
--- a/src/git/cli.v
+++ b/src/git/cli.v
@@ -96,6 +96,8 @@ pub fn cmd() cli.Command {
 	}
 }
 
+// get_repo_id_by_prefix tries to find the repo with the given prefix in its
+// ID. If multiple or none are found, an error is raised.
 fn get_repo_id_by_prefix(conf Config, id_prefix string) ?string {
 	repos := get_repos(conf.address, conf.api_key) ?
 
@@ -118,6 +120,7 @@ fn get_repo_id_by_prefix(conf Config, id_prefix string) ?string {
 	return res[0]
 }
 
+// list prints out a list of all repositories.
 fn list(conf Config) ? {
 	repos := get_repos(conf.address, conf.api_key) ?
 
@@ -126,12 +129,14 @@ fn list(conf Config) ? {
 	}
 }
 
+// add adds a new repository to the server's list.
 fn add(conf Config, url string, branch string, repo string, arch []string) ? {
 	res := add_repo(conf.address, conf.api_key, url, branch, repo, arch) ?
 
 	println(res.message)
 }
 
+// remove removes a repository from the server's list.
 fn remove(conf Config, id_prefix string) ? {
 	id := get_repo_id_by_prefix(conf, id_prefix) ?
 	res := remove_repo(conf.address, conf.api_key, id) ?
@@ -139,6 +144,7 @@ fn remove(conf Config, id_prefix string) ? {
 	println(res.message)
 }
 
+// patch patches a given repository with the provided params.
 fn patch(conf Config, id_prefix string, params map[string]string) ? {
 	id := get_repo_id_by_prefix(conf, id_prefix) ?
 	res := patch_repo(conf.address, conf.api_key, id, params) ?
diff --git a/src/git/client.v b/src/git/client.v
index e4a39ac..a43c9ca 100644
--- a/src/git/client.v
+++ b/src/git/client.v
@@ -4,6 +4,9 @@ import json
 import response { Response }
 import net.http
 
+// send_request<T> is a convenience method for sending requests to the repos
+// API. It mostly does string manipulation to create a query string containing
+// the provided params.
 fn send_request<T>(method http.Method, address string, url string, api_key string, params map[string]string) ?Response<T> {
 	mut full_url := '$address$url'
 
diff --git a/src/package/package.v b/src/package/package.v
index a6be636..a1042b5 100644
--- a/src/package/package.v
+++ b/src/package/package.v
@@ -175,6 +175,7 @@ pub fn read_pkg_archive(pkg_path string) ?Pkg {
 	}
 }
 
+// format_entry returns a string properly formatted to be added to a desc file.
 fn format_entry(key string, value string) string {
 	return '\n%$key%\n$value\n'
 }
diff --git a/src/repo/sync.v b/src/repo/sync.v
index 12756b7..9c5e7ed 100644
--- a/src/repo/sync.v
+++ b/src/repo/sync.v
@@ -2,6 +2,8 @@ module repo
 
 import os
 
+// archive_add_entry writes a file to an archive, given its path & inner path
+// inside the archive.
 fn archive_add_entry(archive &C.archive, entry &C.archive_entry, file_path &string, inner_path &string) {
 	st := C.stat{}
 
@@ -29,7 +31,7 @@ fn archive_add_entry(archive &C.archive, entry &C.archive_entry, file_path &stri
 	}
 }
 
-// Re-generate the repo archive files
+// sync regenerates the repository archive files.
 fn (r &RepoGroupManager) sync(repo string, arch string) ? {
 	subrepo_path := os.join_path(r.repos_dir, repo, arch)
 
diff --git a/src/server/auth.v b/src/server/auth.v
index 8bc9d55..7c8a676 100644
--- a/src/server/auth.v
+++ b/src/server/auth.v
@@ -2,6 +2,7 @@ module server
 
 import net.http
 
+// is_authorized checks whether the provided API key is correct.
 fn (mut app App) is_authorized() bool {
 	x_header := app.req.header.get_custom('X-Api-Key', http.HeaderQueryConfig{ exact: true }) or {
 		return false
diff --git a/src/server/git.v b/src/server/git.v
index a9d6f50..0cba17c 100644
--- a/src/server/git.v
+++ b/src/server/git.v
@@ -8,6 +8,7 @@ import response { new_data_response, new_response }
 
 const repos_file = 'repos.json'
 
+// get_repos returns the current list of repos.
 ['/api/repos'; get]
 fn (mut app App) get_repos() web.Result {
 	if !app.is_authorized() {
@@ -25,6 +26,7 @@ fn (mut app App) get_repos() web.Result {
 	return app.json(http.Status.ok, new_data_response(repos))
 }
 
+// get_single_repo returns the information for a single repo.
 ['/api/repos/:id'; get]
 fn (mut app App) get_single_repo(id string) web.Result {
 	if !app.is_authorized() {
@@ -48,6 +50,7 @@ fn (mut app App) get_single_repo(id string) web.Result {
 	return app.json(http.Status.ok, new_data_response(repo))
 }
 
+// post_repo creates a new repo from the provided query string.
 ['/api/repos'; post]
 fn (mut app App) post_repo() web.Result {
 	if !app.is_authorized() {
@@ -86,6 +89,7 @@ fn (mut app App) post_repo() web.Result {
 	return app.json(http.Status.ok, new_response('Repo added successfully.'))
 }
 
+// delete_repo removes a given repo from the server's list.
 ['/api/repos/:id'; delete]
 fn (mut app App) delete_repo(id string) web.Result {
 	if !app.is_authorized() {
@@ -113,6 +117,7 @@ fn (mut app App) delete_repo(id string) web.Result {
 	return app.json(http.Status.ok, new_response('Repo removed successfully.'))
 }
 
+// patch_repo updates a repo's data with the given query params.
 ['/api/repos/:id'; patch]
 fn (mut app App) patch_repo(id string) web.Result {
 	if !app.is_authorized() {
diff --git a/src/server/routes.v b/src/server/routes.v
index 4f6c4f0..f27afb4 100644
--- a/src/server/routes.v
+++ b/src/server/routes.v
@@ -16,6 +16,9 @@ pub fn (mut app App) healthcheck() web.Result {
 	return app.json(http.Status.ok, new_response('Healthy.'))
 }
 
+// get_repo_file handles all Pacman-related routes. It returns both the
+// repository's archives, but also package archives or the contents of a
+// package's desc file.
 ['/:repo/:arch/:filename'; get; head]
 fn (mut app App) get_repo_file(repo string, arch string, filename string) web.Result {
 	mut full_path := ''
@@ -54,6 +57,7 @@ fn (mut app App) get_repo_file(repo string, arch string, filename string) web.Re
 	return app.file(full_path)
 }
 
+// put_package handles publishing a package to a repository.
 ['/:repo/publish'; post]
 fn (mut app App) put_package(repo string) web.Result {
 	if !app.is_authorized() {
diff --git a/src/web/parse.v b/src/web/parse.v
index 2eeef5e..a095f0c 100644
--- a/src/web/parse.v
+++ b/src/web/parse.v
@@ -47,6 +47,7 @@ fn parse_attrs(name string, attrs []string) ?([]http.Method, string) {
 	return methods, path.to_lower()
 }
 
+// Extracts query parameters from a URL.
 fn parse_query_from_url(url urllib.URL) map[string]string {
 	mut query := map[string]string{}
 	for v in url.query().data {
@@ -55,6 +56,7 @@ fn parse_query_from_url(url urllib.URL) map[string]string {
 	return query
 }
 
+// Extract form data from an HTTP request.
 fn parse_form_from_request(request http.Request) ?(map[string]string, map[string][]http.FileData) {
 	mut form := map[string]string{}
 	mut files := map[string][]http.FileData{}