commit 0385c3532de24268a336a7704cc8ecee77c1e63a
parent abd45c8bb0d1a36197f7782f8afd05c58aa9ceb6
Author: Daniel Moch <daniel@danielmoch.com>
Date: Sun, 6 Dec 2020 20:16:15 -0500
Add go doc documentation
Diffstat:
3 files changed, 56 insertions(+), 0 deletions(-)
diff --git a/cmd/shrt/main.go b/cmd/shrt/main.go
@@ -1,3 +1,31 @@
+// See LICENSE file for copyright and license details
+
+// shrt is a URL shortener service (much like bit.ly without the
+// trackers) that also handles go-get requests. The latter are a
+// specific GET request query used by the Go programming language
+// toolchain to aid in the downloading of utilities and libraries
+// prior to build and installation.
+//
+// Upon invocation, shrt does one of two things depending
+// on the presence or absence of the init argument. If the init
+// argument is present, a series of questions is asked, the responses
+// are recorded in a configuration file, and the program exits. If
+// the init argument is absent, shrt reads the configuration and
+// database files into memory, binds to the port specified by the
+// -l flag, and begins serving requests.
+//
+// Shortlinks are recorded in the database, and any request path
+// not matching a shortlink is assumed to be a go-get request. This
+// is by design, but can result in specious redirects. Additionally,
+// subdirectory paths are not allowed.
+//
+// Shortlinks generate an HTTP 301 response. Go-get requests generate
+// an HTTP 200 response. If configured, requests to the base path
+// (i.e., "/") generate an HTTP 302 response.
+//
+// In order to add a new shortlink to the database, simply edit the
+// file. After saving, send SIGHUP to a running server process to
+// reload the file.
package main
import (
diff --git a/doc.go b/doc.go
@@ -0,0 +1,4 @@
+// The shrt module implements a simple (perhaps simplistic) URL
+// shortener. It also handles go-get requests. See the cmd/shrt
+// package documentation for a fuller explanation of the server.
+package shrt
diff --git a/shrtfile.go b/shrtfile.go
@@ -7,11 +7,23 @@ import (
"strings"
)
+// The ShrtFile struct contains the data read from a specially-formatted
+// file. The syntax of the file is human readable. Each line
+// represents a key-value pair. The key is everything to the left
+// of the first equals sign, and the value is everything to the
+// right. Whitespace is trimmed from the beginning and end of both
+// keys and values.
type ShrtFile struct {
m map[string]string
path string
}
+// The NewShrtFile function creates a new ShrtFile. The filesystem
+// is checked for the existence of a node at the specified path,
+// and the NewShrtFile returns an error if something is there. This
+// constitutes a weak check, since a file could easily be created
+// before Write() is called, in which case the existing file will
+// be truncated.
func NewShrtFile(path string) (*ShrtFile, error) {
// we fail if the file already exists, so the logic is reversed
// from the usual here
@@ -25,6 +37,9 @@ func NewShrtFile(path string) (*ShrtFile, error) {
return &ShrtFile{m: make(map[string]string), path: path}, nil
}
+// The ReadShrtFile function reads an existing ShrtFile from the
+// filesystem and returns a pointer to a ShrtFile object. See the
+// ShrtFile documentation for the expected file format.
func ReadShrtFile(db string) (*ShrtFile, error) {
var newFile ShrtFile
newFile.m = make(map[string]string)
@@ -47,14 +62,23 @@ func ReadShrtFile(db string) (*ShrtFile, error) {
return &newFile, nil
}
+// The Get method gets the value of the specified key. If the key
+// does not exist, an empty string is returned.
func (s *ShrtFile) Get(key string) string {
return s.m[key]
}
+// The Put method adds a the specified value, associating it with
+// the specified key. The value is overwritten if the key already
+// exists.
func (s *ShrtFile) Put(key, value string) {
s.m[key] = value
}
+// The Write method serializes the contents of the ShrtFile to the
+// file path specified when the ShrtFile was created. If a file
+// already exists at the specified path, it is truncated and
+// overwritten.
func (s *ShrtFile) Write() error {
f, err := os.Create(s.path)
if err != nil {
