From 5f98b659029d3cf3851cbff46d4f2404d920acd2 Mon Sep 17 00:00:00 2001
From: Jef Roosens <roosensjef@gmail.com>
Date: Tue, 13 Apr 2021 22:35:39 +0200
Subject: [PATCH] Added lots of documentation

---
 Makefile  | 30 ++++++++++++++++++++++++------
 README.md | 16 ++++++++++++++++
 2 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index fee2643..6ad1f50 100644
--- a/Makefile
+++ b/Makefile
@@ -1,48 +1,66 @@
 all: debug
 .PHONY: all
 
-# Builds
+# Builds the debug release inside the Alpine container. For build caching, two
+# volumes are used named `fej_build-cache` and `fej_registry-cache`. These
+# images are automatically created for you if they don't exist. If you
+# encounter any strange build errors, you can try removing this volumes to
+# start a completely fresh build.
 debug:
 	@ ./build -m dev -a run build
 .PHONY: debug
 
+# Builds the release version. In contrary to the debug version, this build
+# doesn't use volumes for caching, as this would require the build to happen
+# during runtime instead of during the building of the image. Instead, it uses
+# the new `--mount` feature from Buildkit. This does mean that only very recent
+# Docker engines can build the release version (in my case, at the time of
+# writing this, 20.10.5).
 release:
 	@ ./build -m rel
 .PHONY: release
 
+# This builds the release version, and pushes all relevant tags to my Docker
+# Hub repository, namely chewingbever/fej
 push:
 	@ ./build -m rel -a push
 .PHONY: push
 
-# Run
+# This builds the debug release, and runs it detached. The reason we detach the
+# container is because Rocket has a tendency to ignore ctlr-c when inside a
+# container, which gets annoying really fast.
 run:
 	@ ./build -m dev -a run
 .PHONY: run
 
+# As a workaround, we just have a stop command that stops the container.
 stop:
 	@ docker stop -t 2 fej
 .PHONY: stop
 
+# This attaches to the running container, essentially giving the same result as
+# just running `cargo run` locally.
 logs:
 	@ docker logs -f fej
 .PHONY: logs
 
-
-# Testing
+# Builds the debug version, and runs the tests (but doesn't detach).
 test:
 	@ ./build -m dev -a run -l -- test --no-fail-fast
 .PHONY: test
 
+# Runs the cargo code formatter on your code.
 format:
 	@ cargo fmt
 .PHONY: format
 
+# Lints your code. This also gets run in the pre-commit hook, basically
+# preventing you from committing badly-formatted code.
 lint:
 	@ cargo fmt -- --check
 .PHONY: lint
 
-
-# Documentation
+# This builds the documentation for the project, excluding the documentation.
 docs:
 	@ cargo doc --no-deps
 .PHONY: docs
diff --git a/README.md b/README.md
index 3f8e6f4..1961201 100644
--- a/README.md
+++ b/README.md
@@ -24,3 +24,19 @@ Every module has a `routes` function that returns its route macros.
 ## Roadmap
 
 See [roadmap.md](roadmap.md).
+
+## Development
+
+The entire toolchain runs on Alpine inside Docker. This makes building easier,
+and (hopefully) eliminates any system-specific bugs.
+
+A [Makefile wrapper](Makefile) is provided for ease of use. Do check it out, as
+all the commands are documented for your understanding ;)
+
+There's also the `build` script. This script does all the "heavy" lifting. It
+chooses which Dockerfile to build according to the given arguments, and
+generates tags for the images (useful when pushing releases). The Makefile is
+really just a wrapper around this build script, allowing you to write
+`make test` instead of `./build -m dev -a run test`.
+
+tl;dr run `make run` to run your build, and `make test` to run the tests.