From 5f7d7c47801b3b6145e945c9a69c3d891085f593 Mon Sep 17 00:00:00 2001 From: Jef Roosens Date: Sat, 7 May 2022 22:06:17 +0200 Subject: [PATCH] doc: added documentation to all functions --- src/client/client.v | 9 ++++++--- src/client/git.v | 10 +++++----- src/client/logs.v | 5 +++++ src/console/logs/logs.v | 7 +++++++ src/db/git.v | 2 ++ src/db/logs.v | 1 + src/server/logs.v | 7 ++++++- 7 files changed, 32 insertions(+), 9 deletions(-) diff --git a/src/client/client.v b/src/client/client.v index 12c92d3..25224a5 100644 --- a/src/client/client.v +++ b/src/client/client.v @@ -11,6 +11,7 @@ pub: api_key string } +// new creates a new Client instance. pub fn new(address string, api_key string) Client { return Client{ address: address @@ -18,6 +19,8 @@ pub fn new(address string, api_key string) Client { } } +// send_request_raw sends an HTTP request, returning the http.Response object. +// It encodes the params so that they're safe to pass as HTTP query parameters. fn (c &Client) send_request_raw(method Method, url string, params map[string]string, body string) ?http.Response { mut full_url := '$c.address$url' @@ -47,9 +50,8 @@ fn (c &Client) send_request(method Method, url string, params map[string]stri return c.send_request_with_body(method, url, params, '') } -// send_request_with_body 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. +// send_request_with_body calls send_request_raw_response & parses its +// output as a Response object. fn (c &Client) send_request_with_body(method Method, url string, params map[string]string, body string) ?Response { res_text := c.send_request_raw_response(method, url, params, body) ? data := json.decode(Response, res_text) ? @@ -57,6 +59,7 @@ fn (c &Client) send_request_with_body(method Method, url string, params map[s return data } +// send_request_raw_response returns the raw text response for an HTTP request. fn (c &Client) send_request_raw_response(method Method, url string, params map[string]string, body string) ?string { res := c.send_request_raw(method, url, params, body) ? diff --git a/src/client/git.v b/src/client/git.v index 7f4c27a..b09d4c2 100644 --- a/src/client/git.v +++ b/src/client/git.v @@ -4,21 +4,21 @@ import db { GitRepo } import net.http { Method } import response { Response } -// get_repos returns the current list of repos. +// get_git_repos returns the current list of repos. pub fn (c &Client) get_git_repos() ?[]GitRepo { data := c.send_request<[]GitRepo>(Method.get, '/api/repos', {}) ? return data.data } -// get_repo returns the repo for a specific ID. +// get_git_repo returns the repo for a specific ID. pub fn (c &Client) get_git_repo(id int) ?GitRepo { data := c.send_request(Method.get, '/api/repos/$id', {}) ? return data.data } -// add_repo adds a new repo to the server. +// add_git_repo adds a new repo to the server. pub fn (c &Client) add_git_repo(url string, branch string, repo string, arch []string) ?Response { mut params := { 'url': url @@ -35,14 +35,14 @@ pub fn (c &Client) add_git_repo(url string, branch string, repo string, arch []s return data } -// remove_repo removes the repo with the given ID from the server. +// remove_git_repo removes the repo with the given ID from the server. pub fn (c &Client) remove_git_repo(id int) ?Response { data := c.send_request(Method.delete, '/api/repos/$id', {}) ? return data } -// patch_repo sends a PATCH request to the given repo with the params as +// patch_git_repo sends a PATCH request to the given repo with the params as // payload. pub fn (c &Client) patch_git_repo(id int, params map[string]string) ?Response { data := c.send_request(Method.patch, '/api/repos/$id', params) ? diff --git a/src/client/logs.v b/src/client/logs.v index 19575a6..8c53213 100644 --- a/src/client/logs.v +++ b/src/client/logs.v @@ -5,12 +5,14 @@ import net.http { Method } import response { Response } import time +// get_build_logs returns all build logs. pub fn (c &Client) get_build_logs() ?Response<[]BuildLog> { data := c.send_request<[]BuildLog>(Method.get, '/api/logs', {}) ? return data } +// get_build_logs_for_repo returns all build logs for a given repo. pub fn (c &Client) get_build_logs_for_repo(repo_id int) ?Response<[]BuildLog> { params := { 'repo': repo_id.str() @@ -21,18 +23,21 @@ pub fn (c &Client) get_build_logs_for_repo(repo_id int) ?Response<[]BuildLog> { return data } +// get_build_log returns a specific build log. pub fn (c &Client) get_build_log(id int) ?Response { data := c.send_request(Method.get, '/api/logs/$id', {}) ? return data } +// get_build_log_content returns the contents of the build log file. pub fn (c &Client) get_build_log_content(id int) ?string { data := c.send_request_raw_response(Method.get, '/api/logs/$id/content', {}, '') ? return data } +// add_build_log adds a new build log to the server. pub fn (c &Client) add_build_log(repo_id int, start_time time.Time, end_time time.Time, arch string, exit_code int, content string) ?Response { params := { 'repo': repo_id.str() diff --git a/src/console/logs/logs.v b/src/console/logs/logs.v index 14aeddf..e3c7d14 100644 --- a/src/console/logs/logs.v +++ b/src/console/logs/logs.v @@ -10,6 +10,7 @@ struct Config { api_key string [required] } +// cmd returns the cli module that handles the build repos API. pub fn cmd() cli.Command { return cli.Command{ name: 'logs' @@ -64,12 +65,14 @@ pub fn cmd() cli.Command { } } +// print_log_list prints a list of logs. fn print_log_list(logs []db.BuildLog) { for log in logs { println('$log.id\t$log.start_time\t$log.exit_code') } } +// list prints a list of all build logs. fn list(conf Config) ? { c := client.new(conf.address, conf.api_key) logs := c.get_build_logs() ?.data @@ -77,6 +80,7 @@ fn list(conf Config) ? { print_log_list(logs) } +// list prints a list of all build logs for a given repo. fn list_for_repo(conf Config, repo_id int) ? { c := client.new(conf.address, conf.api_key) logs := c.get_build_logs_for_repo(repo_id) ?.data @@ -84,6 +88,7 @@ fn list_for_repo(conf Config, repo_id int) ? { print_log_list(logs) } +// info print the detailed info for a given build log. fn info(conf Config, id int) ? { c := client.new(conf.address, conf.api_key) log := c.get_build_log(id) ?.data @@ -91,6 +96,8 @@ fn info(conf Config, id int) ? { print(log) } +// content outputs the contents of the log file for a given build log to +// stdout. fn content(conf Config, id int) ? { c := client.new(conf.address, conf.api_key) content := c.get_build_log_content(id) ? diff --git a/src/db/git.v b/src/db/git.v index 7aba284..9a475a5 100644 --- a/src/db/git.v +++ b/src/db/git.v @@ -153,6 +153,8 @@ pub fn (db &VieterDb) update_git_repo_archs(repo_id int, archs []GitRepoArch) { } } +// git_repo_exists is a utility function that checks whether a repo with the +// given id exists. pub fn (db &VieterDb) git_repo_exists(repo_id int) bool { db.get_git_repo(repo_id) or { return false } diff --git a/src/db/logs.v b/src/db/logs.v index 05973af..817db78 100644 --- a/src/db/logs.v +++ b/src/db/logs.v @@ -12,6 +12,7 @@ pub: exit_code int [nonull] } +// str returns a string representation. pub fn (bl &BuildLog) str() string { mut parts := [ 'id: $bl.id', diff --git a/src/server/logs.v b/src/server/logs.v index f53464d..b048dc4 100644 --- a/src/server/logs.v +++ b/src/server/logs.v @@ -9,6 +9,8 @@ import time import os import util +// get_logs returns all build logs in the database. A 'repo' query param can +// optionally be added to limit the list of build logs to that repository. ['/api/logs'; get] fn (mut app App) get_logs() web.Result { if !app.is_authorized() { @@ -24,6 +26,7 @@ fn (mut app App) get_logs() web.Result { return app.json(http.Status.ok, new_data_response(logs)) } +// get_single_log returns the build log with the given id. ['/api/logs/:id'; get] fn (mut app App) get_single_log(id int) web.Result { if !app.is_authorized() { @@ -35,8 +38,9 @@ fn (mut app App) get_single_log(id int) web.Result { return app.json(http.Status.ok, new_data_response(log)) } +// get_log_content returns the actual build log file for the given id. ['/api/logs/:id/content'; get] -fn (mut app App) get_log_contents(id int) web.Result { +fn (mut app App) get_log_content(id int) web.Result { if !app.is_authorized() { return app.json(http.Status.unauthorized, new_response('Unauthorized.')) } @@ -58,6 +62,7 @@ fn parse_query_time(query string) ?time.Time { return t } +// post_log adds a new log to the database. ['/api/logs'; post] fn (mut app App) post_log() web.Result { if !app.is_authorized() {