Use @HELP decorator for help messages

Makefile

@@ -47,36 +47,46 @@ TFORMAT := short
 
 export PATH:=$(GOBIN):$(PATH)
 
-env:  ## Print Go env variables.
+env: # @HELP Print Go env variables.
+env:
 	go env
 
-deps: $(GOMAJOR)  ## List available module dependency updates.
+deps: # @HELP List available module dependency updates.
+deps: $(GOMAJOR)
 	gomajor list
 
-tparse: $(TPARSE)  ## Run all tests and outputs a coverage report using tparse.
+tparse: # @HELP Run all tests and output a coverage report using tparse.
+tparse: $(TPARSE)
 	@go test -count=1 -json -cover $(TEST_PACKAGES) | tparse -follow -all -notests
 
-test: $(GOTESTSUM)  ## Run all tests and outputs a summary using gotestsum.
+test: # @HELP Run all tests and output a summary using gotestsum.
+test: $(GOTESTSUM)
 	@gotestsum --format=$(TFORMAT) $(TEST_PACKAGES)
 
-test-race: $(GOTESTSUM)  ## Run all tests with the race detector.
+test-race: # @HELP Run all tests with the race detector.
+test-race: $(GOTESTSUM)
 	@gotestsum --format=$(TFORMAT) $(TEST_PACKAGES) -- -race
 
-list-tested-packages:  ## Print a list of packages being tested.
+list-tested-packages: # @HELP Print a list of packages being tested.
+list-tested-packages:
 	$(foreach PACKAGE,$(TEST_PACKAGES),@echo $(PACKAGE)$(NEWLINE))
 
-list-ignored-packages:  ## Print a list of packages ignored in testing.
+list-ignored-packages: # @HELP Print a list of packages ignored in testing.
+list-ignored-packages:
 	$(foreach PACKAGE,$(TEST_IGNORED_PACKAGES),@echo $(PACKAGE)$(NEWLINE))
 
+lint: # @HELP Lint the project Go files with golangci-lint.
 lint: OUT_FORMAT ?= colored-line-number
 lint: LINT_FLAGS ?= --timeout=5m --fix
-lint: $(GOLANGCI_LINT)  ## Lint the project Go files with golangci-lint.
+lint: $(GOLANGCI_LINT)
 	golangci-lint run --out-format $(OUT_FORMAT) $(LINT_FLAGS)
 
-gen-goa: $(GOA)  ## Generate Goa assets.
+gen-goa: # @HELP Generate Goa assets.
+gen-goa: $(GOA)
 	goa gen github.com/artefactual-sdps/enduro/internal/api/design -o internal/api
 
-gen-dashboard-client:  ## Generate Dashboard web client from OpenAPI spec.
+gen-dashboard-client: # @HELP Generate the Dashboard web client from the OpenAPI spec.
+gen-dashboard-client:
 	@rm -rf $(CURDIR)/dashboard/src/openapi-generator
 	@docker container run --rm --user $(shell id -u):$(shell id -g) --volume $(CURDIR):/local openapitools/openapi-generator-cli:v6.1.0 \
 		generate \
@@ -88,7 +98,8 @@ gen-dashboard-client:  ## Generate Dashboard web client from OpenAPI spec.
 			-p "supportsES6=true"
 	@echo "@@@@ Please, review all warnings generated by openapi-generator-cli above!"
 
-gen-mock: $(MOCKGEN)  ## Generate mocks.
+gen-mock: # @HELP Generate mocks.
+gen-mock: $(MOCKGEN)
 	mockgen -typed -destination=./internal/package_/fake/mock_package_.go -package=fake github.com/artefactual-sdps/enduro/internal/package_ Service
 	mockgen -typed -destination=./internal/storage/fake/mock_storage.go -package=fake github.com/artefactual-sdps/enduro/internal/storage Service
 	mockgen -typed -destination=./internal/storage/persistence/fake/mock_persistence.go -package=fake github.com/artefactual-sdps/enduro/internal/storage/persistence Storage
@@ -97,17 +108,25 @@ gen-mock: $(MOCKGEN)  ## Generate mocks.
 	mockgen -typed -destination=./internal/api/auth/fake/mock_ticket_store.go -package=fake github.com/artefactual-sdps/enduro/internal/api/auth TicketStore
 	mockgen -typed -destination=./internal/persistence/fake/mock_persistence.go -package=fake github.com/artefactual-sdps/enduro/internal/persistence Service
 
-gen-ent: $(ENT)  ## Generate Ent assets.
+gen-ent: # @HELP Generate Ent assets.
+gen-ent: $(ENT)
 	ent generate ./internal/persistence/ent/schema \
 		--feature sql/versioned-migration \
 		--target=./internal/persistence/ent/db
 	ent generate ./internal/storage/persistence/ent/schema \
 		--feature sql/versioned-migration \
 		--target=./internal/storage/persistence/ent/db
 
-tilt-trigger-internal:  ## Restart enduro-internal and wait until ready.
+tilt-trigger-internal: # @HELP Restart enduro-internal and wait until ready.
+tilt-trigger-internal:
 	@tilt trigger enduro-internal
 	@tilt wait --for=condition=Ready uiresource/enduro-internal
 
-help:  ## Show this help.
-	@grep -hE '^[A-Za-z0-9_ \-]*?:.*##.*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+help: # @HELP Print this message.
+help:
+	echo "TARGETS:"
+	grep -E '^.*: *# *@HELP' Makefile             \
+	    | awk '                                   \
+	        BEGIN {FS = ": *# *@HELP"};           \
+	        { printf "  %-30s %s\n", $$1, $$2 };  \
+	    '

internal/api/middleware.go

@@ -16,13 +16,13 @@ func recoverMiddleware(logger logr.Logger) func(http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			defer func() {
 				if rec := recover(); rec != nil {
-					// Don't recover if the request is aborted, otherwise the
-					// request can't detect the error.
+					// Don't recover if the request is aborted, as this would
+					// prevent the client from detecting the error.
 					if rec == http.ErrAbortHandler {
 						panic(rec)
 					}
 
-					// Prepare error message and log it.
+					// Prepare the error message and log it.
 					b := strings.Builder{}
 					switch x := rec.(type) {
 					case string: