All our projects contain a lengthy Makefile, to automate installation, build, test, and deployment. Most of the target names are standardized (make install, make deploy), but some deserve explanation (make run-dev, make restart-api). The more we add fine-grained make targets, the more we need to describe what they do in text form. In our projects, we usually write this doc in the README file:

But when using the CLI, we prefer self-documenting tools. Wouldn’t it better if we could just type make, and get a list of available commands, together with their desciption?

It turns out it’s quite easy to do. First, document each target using a comment placed after the target name, and starting with ##, as follows:

install: 
	@echo "Installing Node dependencies"
	@npm install

install-dev: install 
	@./node_modules/.bin/selenium-standalone install
	@cp -n ./config/development.js-dist ./config/development.js | true

run-frontend-dev: webpack.PID 

webpack.PID:
	@./node_modules/.bin/babel-node ./node_modules/.bin/webpack-dev-server 
		--content-base=build 
		--devtool=cheap-module-inline-source-map 
		--hot 
		--inline 
		--progress 
		& echo "$$!" > w