From cf22b103877d59e663a7b00e424d0e530bba795c Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Thu, 28 Nov 2024 15:43:32 -0500
Subject: [PATCH] Add a PHONY help target

- Add comments for users-guide* targets
- Comment tags target
- Add comment for checks
- Comment doctesting and ghcid
- Add help-banner target
- Add comments to all, lib and exe targets
- Add full stops to the help comments
- Manual fix-whitespace
---
 Makefile | 50 +++++++++++++++++++++++++++++++-------------------
 1 file changed, 31 insertions(+), 19 deletions(-)

diff --git a/Makefile b/Makefile
index a3e4a873e28..70e150edebb 100644
--- a/Makefile
+++ b/Makefile
@@ -12,55 +12,55 @@ DOCTEST := cabal doctest --allow-newer=False
 # default rules
 
 .PHONY: all
-all : exe lib
+all: help-banner exe lib ## Build the Cabal libraries and cabal-install executables.
 
 .PHONY: lib
-lib :
+lib: ## Builds the Cabal libraries.
 	$(CABALBUILD) Cabal:libs
 
 .PHONY: exe
-exe :
+exe: ## Builds the cabal-install executables.
 	$(CABALBUILD) cabal-install:exes
 
 .PHONY: init
-init: ## Set up git hooks and ignored revisions
+init: ## Set up git hooks and ignored revisions.
 	@git config core.hooksPath .githooks
 	## TODO
 
 .PHONY: style
-style: ## Run the code styler
+style: ## Run the code styler.
 	@fourmolu -q -i Cabal Cabal-syntax cabal-install cabal-validate
 
 .PHONY: style-modified
-style-modified: ## Run the code styler on modified files
+style-modified: ## Run the code styler on modified files.
 	@git ls-files --modified Cabal Cabal-syntax cabal-install cabal-validate \
 		| grep '.hs$$' | xargs -P $(PROCS) -I {} fourmolu -q -i {}
 
 .PHONY: style-commit
-style-commit: ## Run the code styler on the previous commit
+style-commit: ## Run the code styler on the previous commit.
 	@git diff --name-only HEAD $(COMMIT) Cabal Cabal-syntax cabal-install cabal-validate \
 		| grep '.hs$$' | xargs -P $(PROCS) -I {} fourmolu -q -i {}
 
 .PHONY: whitespace
-whitespace: ## Run fix-whitespace in check mode
+whitespace: ## Run fix-whitespace in check mode.
 	fix-whitespace --check --verbose
 
 .PHONY: fix-whitespace
-fix-whitespace: ## Run fix-whitespace in fix mode
+fix-whitespace: ## Run fix-whitespace in fix mode.
 	fix-whitespace --verbose
 
 .PHONY: lint
-lint: ## Run HLint
+lint: ## Run HLint.
 	hlint -j .
 
 .PHONY: lint-json
-lint-json: ## Run HLint in JSON mode
+lint-json: ## Run HLint in JSON mode.
 	hlint -j --json -- .
 
 # local checks
 
 .PHONY: checks
-checks: whitespace users-guide-typos markdown-typos style lint-json
+checks: whitespace users-guide-typos markdown-typos style lint-json  ## Run all local checks; whitespace, typos, style, and lint.
 
 # source generation: SPDX
 
@@ -116,15 +116,15 @@ analyse-imports :
 # ghcid
 
 .PHONY: ghcid-lib
-ghcid-lib :
+ghcid-lib: ## Run ghcid for the Cabal library.
 	ghcid -c 'cabal repl Cabal'
 
 .PHONY: ghcid-cli
-ghcid-cli :
+ghcid-cli: ## Run ghcid for the cabal-install executable.
 	ghcid -c 'cabal repl cabal-install'
 
 .PHONY: doctest
-doctest :
+doctest: ## Run doctests.
 	cd Cabal-syntax && $(DOCTEST)
 	cd Cabal-described && $(DOCTEST)
 	cd Cabal && $(DOCTEST)
@@ -137,7 +137,7 @@ doctest-cli :
 	doctest -D__DOCTEST__ --fast cabal-install/src cabal-install-solver/src cabal-install-solver/src-assertion
 
 .PHONY: doctest-install
-doctest-install:
+doctest-install: ## Install doctest tool needed for running doctests.
 	cabal install doctest --overwrite-policy=always --ignore-project --flag cabal-doctest
 
 # tests
@@ -234,7 +234,7 @@ validate-via-docker-old:
 
 # tags
 .PHONY : tags
-tags :
+tags: ## Generate editor tags, vim ctags and emacs etags.
 	hasktags -b Cabal-syntax/src Cabal/src Cabal-described/src cabal-install/src cabal-testsuite/src
 
 # bootstrapping
@@ -256,11 +256,11 @@ bootstrap-jsons: $(BOOTSTRAP_GHC_VERSIONS:%=bootstrap-json-%)
 ##############################################################################
 
 .PHONY: users-guide
-users-guide:
+users-guide: ## Build the users guide.
 	$(MAKE) -C doc users-guide
 
 .PHONY: users-guide-requirements
-users-guide-requirements:
+users-guide-requirements: ## Install the requirements for building the users guide.
 	$(MAKE) -C doc users-guide-requirements
 
 ifeq ($(shell uname), Darwin)
@@ -269,6 +269,18 @@ else
 PROCS := $(shell nproc)
 endif
 
+PHONY: help
+help: ## Show the commented targets.
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+	sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+PHONY: help-banner
+help-banner: ## Show the help banner.
+	@echo "===================================================================="
+	@echo "§ all                  make with no arguments also shows this banner"
+	@echo "§ help                 make help will list targets with descriptions"
+	@echo "===================================================================="
+
 .PHONY: typos-install
 typos-install: ## Install typos-cli for typos target using cargo
 	cargo install typos-cli