Repository: nodejs/node
Pull request: build: add more information to Makefile help

This PR adds more information to the Makefile by adding more help details to more targets:

<details>
<summary><code>make help</code> output</summary>

```
For more targets and info see the comments in the Makefile.

all             Build node in out/Release/node (Default).
bench-addons-build Build required addons for benchmark before running it.
binary          Build release binary tarballs.
build-addons    Build addons for Node.js.
build-ci        Build everything (CI).
build-js-native-api-tests Build JS Native-API tests.
build-node-api-tests Build Node-API tests.
cctest          Run the C++ tests using the built `cctest` executable.
clean           Remove build artifacts.
clear-stalled   Clear any stalled processes.
corepack-update Update Corepack to the latest version.
coverage-build-js Build JavaScript coverage files.
coverage-build  Build coverage files.
coverage-clean  Remove coverage artifacts.
coverage-report-js Report JavaScript coverage results.
coverage-run-js Run JavaScript tests with coverage.
coverage-test   Run the tests and generate a coverage report.
coverage        Run the tests and generate a coverage report.
distclean       Remove all build and test artifacts.
doc             Build Node.js, and then build the documentation with the new binary.
docclean        Remove the generated documentation.
docopen         Open the documentation in a web browser.
docserve        Serve the documentation on localhost:8000.
format-cpp-build Build 'clang-format' tooling for C++ code formatting.
format-cpp-clean Remove 'clang-format' tooling for C++ code formatting.
format-cpp      Format C++ diff from $CLANG_FORMAT_START to current changes.
format-md       Format the markdown documents maintained by us in the codebase.
gen-openssl     Generate platform dependent openssl files (requires docker).
help            Print help for targets with comments.
install         Install node into $PREFIX (default=/usr/local).
jstest          Run addon tests and JS tests.
lint-addon-docs Lint the addon documentation.
lint-clean      Remove linting artifacts.
lint-cpp        Lint the C++ code with cpplint.py and checkimports.py.
lint-js-fix     Lint and fix the JavaScript code with eslint.
lint-md         Lint the markdown documents maintained by us in the codebase.
lint-py-build   Build resources needed to lint python files.
lint-py         Lint the Python code with ruff.
lint-yaml-build Build resources needed to lint YAML files.
lint-yaml       Lint the YAML files with yamllint.
lint            Run JS, C++, MD and doc linters.
list-gtests     List all available C++ gtests.
pkg             Build the macOS installer for releases.
release-only    Prepare Node.js for release.
run-ci          Build and run all tests (CI).
tar-headers     Build the node header tarball.
tar             Create a source tarball.
test-addons-clean Remove addon testing artifacts.
test-addons     Run addon tests.
test-all-suites Run all test suites.
test-all-valgrind Run all tests using valgrind.
test-all        Run default tests with both Debug and Release builds.
test-build-js-native-api Build JS Native-API tests.
test-build-node-api Build Node-API tests.
test-build      Build all tests.
test-ci-js      Build and test JavaScript with building anything else.
test-ci-native  Build and test addons without building anything else.
test-ci         Build and test everything (CI).
test-cov        Run coverage tests.
test-debug      Run tests on a debug build.
test-doc-ci     Build, lint, and verify the docs (CI).
test-doc        Build, lint, and verify the docs.
test-hash-seed  Verifu that the hash seed used by V8 for hashing is random.
test-internet   Run internet tests.
test-js-native-api-clean Remove JS Native-API testing artifacts.
test-js-native-api Run JS Native-API tests.
test-known-issues Run tests for known issues.
test-node-api-clean Remove Node-API testing artifacts.
test-node-api   Run Node-API tests.
test-npm-publish Test the `npm publish` command.
test-npm        Run the npm test suite on deps/npm.
test-only       Run default tests, without linters or building the docs.
test-tick-processor Run tick processor tests.
test-v8-all     Run the entire V8 test suite, including intl, benchmarks, and updates.
test-v8-benchmarks Run the v8 test suite, benchmarks.
test-v8-intl    Run the v8 test suite, intl tests.
test-v8-updates Run the v8 test suite, updates.
test-v8         Run the V8 test suite on deps/v8.
test-valgrind   Run tests using valgrind.
test-with-async-hooks Run tests with async hooks.
test-wpt-report Run the Web Platform Tests and generate a report.
test-wpt        Run the Web Platform Tests.
test            Run default tests, linters, and build docs.
testclean       Remove test artifacts.
tooltest        Test the various tools.
uninstall       Uninstall node from $PREFIX (default=/usr/local).
v8              Build deps/v8.
```

</details>

Changed files:
filename: Makefile
patch: @@ -109,7 +109,7 @@ available-node = \
 # BUILDTYPE=Debug builds both release and debug builds. If you want to compile
 # just the debug build, run `make -C out BUILDTYPE=Debug` instead.
 ifeq ($(BUILDTYPE),Release)
-all: $(NODE_EXE) ## Default target, builds node in out/Release/node.
+all: $(NODE_EXE) ## Build node in out/Release/node (Default).
 else
 all: $(NODE_EXE) $(NODE_G_EXE)
 endif
@@ -191,11 +191,11 @@ config.gypi: configure configure.py src/node_version.h
 	fi
 
 .PHONY: install
-install: all ## Installs node into $PREFIX (default=/usr/local).
+install: all ## Install node into $PREFIX (default=/usr/local).
 	$(PYTHON) tools/install.py $@ --dest-dir '$(DESTDIR)' --prefix '$(PREFIX)'
 
 .PHONY: uninstall
-uninstall: ## Uninstalls node from $PREFIX (default=/usr/local).
+uninstall: ## Uninstall node from $PREFIX (default=/usr/local).
 	$(PYTHON) tools/install.py $@ --dest-dir '$(DESTDIR)' --prefix '$(PREFIX)'
 
 .PHONY: clean
@@ -213,14 +213,14 @@ clean: ## Remove build artifacts.
 
 .PHONY: testclean
 .NOTPARALLEL: testclean
-testclean:
+testclean: ## Remove test artifacts.
 # Next one is legacy remove this at some point
 	$(RM) -r test/tmp*
 	$(RM) -r test/.tmp*
 
 .PHONY: distclean
 .NOTPARALLEL: distclean
-distclean:
+distclean: ## Remove all build and test artifacts.
 	$(RM) -r out
 	$(RM) config.gypi icu_config.gypi
 	$(RM) config.mk
@@ -237,7 +237,7 @@ check: test
 .NOTPARALLEL: coverage-clean
 # Remove files generated by running coverage, put the non-instrumented lib back
 # in place
-coverage-clean:
+coverage-clean: ## Remove coverage artifacts.
 	$(RM) -r node_modules
 	$(RM) -r gcovr
 	$(RM) -r coverage/tmp
@@ -254,20 +254,20 @@ coverage-clean:
 coverage: coverage-test ## Run the tests and generate a coverage report.
 
 .PHONY: coverage-build
-coverage-build: all
+coverage-build: all ## Build coverage files.
 	-$(MAKE) coverage-build-js
 	if [ ! -d gcovr ]; then $(PYTHON) -m pip install -t gcovr gcovr==7.2; fi
 	$(MAKE)
 
 .PHONY: coverage-build-js
-coverage-build-js:
+coverage-build-js: ## Build JavaScript coverage files.
 	mkdir -p node_modules
 	if [ ! -d node_modules/c8 ]; then \
 		$(NODE) ./deps/npm install c8 --no-save --no-package-lock;\
 	fi
 
 .PHONY: coverage-test
-coverage-test: coverage-build
+coverage-test: coverage-build ## Run the tests and generate a coverage report.
 	@if [ -d "out/Release/obj.target" ]; then \
 		$(FIND) out/$(BUILDTYPE)/obj.target -name "*.gcda" -type f -exec $(RM) {}; \
 	fi
@@ -288,18 +288,18 @@ coverage-test: coverage-build
 		| sed 's/<[^>]*>//g'| sed 's/ //g'
 
 .PHONY: coverage-report-js
-coverage-report-js:
+coverage-report-js: ## Report JavaScript coverage results.
 	-$(MAKE) coverage-build-js
 	$(NODE) ./node_modules/.bin/c8 report
 
 .PHONY: cctest
-# Runs the C++ tests using the built `cctest` executable.
-cctest: all
+
+cctest: all ## Run the C++ tests using the built `cctest` executable.
 	@out/$(BUILDTYPE)/$@ --gtest_filter=$(GTEST_FILTER)
 	$(NODE) ./test/embedding/test-embedding.js
 
 .PHONY: list-gtests
-list-gtests:
+list-gtests: ## List all available C++ gtests.
 ifeq (,$(wildcard out/$(BUILDTYPE)/cctest))
 	$(error Please run 'make cctest' first)
 endif
@@ -309,32 +309,32 @@ endif
 # Related CI job: node-test-commit-v8-linux
 # Rebuilds deps/v8 as a git tree, pulls its third-party dependencies, and
 # builds it.
-v8:
+v8: ## Build deps/v8.
 	export PATH="$(NO_BIN_OVERRIDE_PATH)" && \
 		tools/make-v8.sh $(V8_ARCH).$(BUILDTYPE_LOWER) $(V8_BUILD_OPTIONS)
 
 .PHONY: jstest
-jstest: build-addons build-js-native-api-tests build-node-api-tests ## Runs addon tests and JS tests
+jstest: build-addons build-js-native-api-tests build-node-api-tests ## Run addon tests and JS tests.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) \
 		$(TEST_CI_ARGS) \
 		--skip-tests=$(CI_SKIP_TESTS) \
 		$(JS_SUITES) \
 		$(NATIVE_SUITES)
 
 .PHONY: tooltest
-tooltest:
+tooltest: ## Test the various tools.
 	@$(PYTHON) -m unittest discover -s ./test/tools
 
 .PHONY: coverage-run-js
-coverage-run-js:
+coverage-run-js: ## Run JavaScript tests with coverage.
 	$(RM) -r coverage/tmp
 	-NODE_V8_COVERAGE=coverage/tmp CI_SKIP_TESTS=$(COV_SKIP_TESTS) \
 					TEST_CI_ARGS="$(TEST_CI_ARGS) --type=coverage" $(MAKE) jstest
 	$(MAKE) coverage-report-js
 
 .PHONY: test
 # This does not run tests of third-party libraries inside deps.
-test: all ## Runs default tests, linters, and builds docs.
+test: all ## Run default tests, linters, and build docs.
 	$(MAKE) -s tooltest
 	$(MAKE) -s test-doc
 	$(MAKE) -s build-addons
@@ -344,7 +344,7 @@ test: all ## Runs default tests, linters, and builds docs.
 	$(MAKE) -s jstest
 
 .PHONY: test-only
-test-only: all  ## For a quick test, does not run linter or build docs.
+test-only: all  ## Run default tests, without linters or building the docs.
 	$(MAKE) build-addons
 	$(MAKE) build-js-native-api-tests
 	$(MAKE) build-node-api-tests
@@ -354,15 +354,15 @@ test-only: all  ## For a quick test, does not run linter or build docs.
 
 # Used by `make coverage-test`
 .PHONY: test-cov
-test-cov: all
+test-cov: all ## Run coverage tests.
 	$(MAKE) build-addons
 	$(MAKE) build-js-native-api-tests
 	$(MAKE) build-node-api-tests
 	$(MAKE) cctest
 	CI_SKIP_TESTS=$(COV_SKIP_TESTS) $(MAKE) jstest
 
 .PHONY: test-valgrind
-test-valgrind: all
+test-valgrind: all ## Run tests using valgrind.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) --valgrind sequential parallel message
 
 .PHONY: test-check-deopts
@@ -442,7 +442,7 @@ test/addons/.buildstamp: $(ADDONS_PREREQS) \
 # .buildstamp is out of date and need a rebuild.
 # Just goes to show that recursive make really is harmful...
 # TODO(bnoordhuis) Force rebuild after gyp update.
-build-addons: | $(NODE_EXE) test/addons/.buildstamp
+build-addons: | $(NODE_EXE) test/addons/.buildstamp ## Build addons for Node.js.
 
 JS_NATIVE_API_BINDING_GYPS := \
 	$(filter-out test/js-native-api/??_*/binding.gyp, \
@@ -466,7 +466,7 @@ test/js-native-api/.buildstamp: $(ADDONS_PREREQS) \
 # .buildstamp is out of date and need a rebuild.
 # Just goes to show that recursive make really is harmful...
 # TODO(bnoordhuis) Force rebuild after gyp or node-gyp update.
-build-js-native-api-tests: | $(NODE_EXE) test/js-native-api/.buildstamp
+build-js-native-api-tests: | $(NODE_EXE) test/js-native-api/.buildstamp ## Build JS Native-API tests.
 
 NODE_API_BINDING_GYPS := \
 	$(filter-out test/node-api/??_*/binding.gyp, \
@@ -490,7 +490,7 @@ test/node-api/.buildstamp: $(ADDONS_PREREQS) \
 # .buildstamp is out of date and need a rebuild.
 # Just goes to show that recursive make really is harmful...
 # TODO(bnoordhuis) Force rebuild after gyp or node-gyp update.
-build-node-api-tests: | $(NODE_EXE) test/node-api/.buildstamp
+build-node-api-tests: | $(NODE_EXE) test/node-api/.buildstamp ## Build Node-API tests.
 
 BENCHMARK_NAPI_BINDING_GYPS := $(wildcard benchmark/napi/*/binding.gyp)
 
@@ -504,7 +504,7 @@ benchmark/napi/.buildstamp: $(ADDONS_PREREQS) \
 	@$(call run_build_addons,"$$PWD/benchmark/napi",$@)
 
 .PHONY: clear-stalled
-clear-stalled:
+clear-stalled: ## Clear any stalled processes.
 	$(info Clean up any leftover processes but don't error if found.)
 	ps awwx | grep Release/node | grep -v grep | cat
 	@PS_OUT=`ps awwx | grep Release/node | grep -v grep | awk '{print $$1}'`; \
@@ -513,20 +513,20 @@ clear-stalled:
 	fi
 
 .PHONY: test-build
-test-build: | all build-addons build-js-native-api-tests build-node-api-tests
+test-build: | all build-addons build-js-native-api-tests build-node-api-tests ## Build all tests.
 
 .PHONY: test-build-js-native-api
-test-build-js-native-api: all build-js-native-api-tests
+test-build-js-native-api: all build-js-native-api-tests ## Build JS Native-API tests.
 
 .PHONY: test-build-node-api
-test-build-node-api: all build-node-api-tests
+test-build-node-api: all build-node-api-tests ## Build Node-API tests.
 
 .PHONY: test-all
 test-all: test-build ## Run default tests with both Debug and Release builds.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=debug,release
 
 .PHONY: test-all-valgrind
-test-all-valgrind: test-build
+test-all-valgrind: test-build ## Run all tests using valgrind.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=debug,release --valgrind
 
 .PHONY: test-all-suites
@@ -545,9 +545,9 @@ else
 endif
 
 .PHONY: test-ci-native
-# Build and test addons without building anything else
+
 # Related CI job: node-test-commit-arm-fanned
-test-ci-native: LOGLEVEL := info
+test-ci-native: LOGLEVEL := info ## Build and test addons without building anything else.
 test-ci-native: | benchmark/napi/.buildstamp test/addons/.buildstamp test/js-native-api/.buildstamp test/node-api/.buildstamp
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) -p tap --logfile test.tap \
 		--mode=$(BUILDTYPE_LOWER) --flaky-tests=$(FLAKY_TESTS) \
@@ -556,7 +556,7 @@ test-ci-native: | benchmark/napi/.buildstamp test/addons/.buildstamp test/js-nat
 .PHONY: test-ci-js
 # This target should not use a native compiler at all
 # Related CI job: node-test-commit-arm-fanned
-test-ci-js: | clear-stalled
+test-ci-js: | clear-stalled ## Build and test JavaScript with building anything else.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) -p tap --logfile test.tap \
 		--mode=$(BUILDTYPE_LOWER) --flaky-tests=$(FLAKY_TESTS) \
 		--skip-tests=$(CI_SKIP_TESTS) \
@@ -570,7 +570,7 @@ test-ci-js: | clear-stalled
 
 .PHONY: test-ci
 # Related CI jobs: most CI tests, excluding node-test-commit-arm-fanned
-test-ci: LOGLEVEL := info
+test-ci: LOGLEVEL := info ## Build and test everything (CI).
 test-ci: | clear-stalled bench-addons-build build-addons build-js-native-api-tests build-node-api-tests doc-only
 	out/Release/cctest --gtest_output=xml:out/junit/cctest.xml
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) -p tap --logfile test.tap \
@@ -587,7 +587,7 @@ test-ci: | clear-stalled bench-addons-build build-addons build-js-native-api-tes
 .PHONY: build-ci
 # Prepare the build for running the tests.
 # Related CI jobs: most CI tests, excluding node-test-commit-arm-fanned
-build-ci:
+build-ci: ## Build everything (CI).
 	$(PYTHON) ./configure --verbose $(CONFIG_FLAGS)
 	$(MAKE)
 
@@ -601,53 +601,52 @@ build-ci:
 #
 # Using -j1 as the sub target in `test-ci` already have internal parallelism.
 # Refs: https://github.com/nodejs/node/pull/23733
-run-ci: build-ci
+run-ci: build-ci ## Build and run all tests (CI).
 	$(MAKE) test-ci -j1
 
 .PHONY: test-release
 .PHONY: test-debug
-test-debug: BUILDTYPE_LOWER=debug
-test-release test-debug: test-build
+test-debug: BUILDTYPE_LOWER=debug ## Run tests on a debug build.
+test-release test-debug: test-build ## Run tests on a release or debug build.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER)
 
 .PHONY: test-wpt
-test-wpt: all
+test-wpt: all ## Run the Web Platform Tests.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) wpt
 
 .PHONY: test-wpt-report
-test-wpt-report:
+test-wpt-report: ## Run the Web Platform Tests and generate a report.
 	$(RM) -r out/wpt
 	mkdir -p out/wpt
 	-WPT_REPORT=1 $(PYTHON) tools/test.py --shell $(NODE) $(PARALLEL_ARGS) wpt
 	$(NODE) "$$PWD/tools/merge-wpt-reports.mjs"
 
 .PHONY: test-internet
-test-internet: all
+test-internet: all ## Run internet tests.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) internet
 
 .PHONY: test-tick-processor
-test-tick-processor: all
+test-tick-processor: all ## Run tick processor tests.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) tick-processor
 
 .PHONY: test-hash-seed
-# Verifies the hash seed used by V8 for hashing is random.
-test-hash-seed: all
+test-hash-seed: all ## Verifu that the hash seed used by V8 for hashing is random.
 	$(NODE) test/pummel/test-hash-seed.js
 
 .PHONY: test-doc
-test-doc: doc-only lint-md ## Builds, lints, and verifies the docs.
+test-doc: doc-only lint-md ## Build, lint, and verify the docs.
 	@if [ "$(shell $(node_use_openssl))" != "true" ]; then \
 		echo "Skipping test-doc (no crypto)"; \
 	else \
 		$(PYTHON) tools/test.py $(PARALLEL_ARGS) doctool; \
 	fi
 
 .PHONY: test-doc-ci
-test-doc-ci: doc-only
+test-doc-ci: doc-only ## Build, lint, and verify the docs (CI).
 	$(PYTHON) tools/test.py --shell $(NODE) $(TEST_CI_ARGS) $(PARALLEL_ARGS) doctool
 
 .PHONY: test-known-issues
-test-known-issues: all
+test-known-issues: all ## Run tests for known issues.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) known_issues
 
 # Related CI job: node-test-npm
@@ -656,36 +655,36 @@ test-npm: $(NODE_EXE) ## Run the npm test suite on deps/npm.
 	$(NODE) tools/test-npm-package --install --logfile=test-npm.tap deps/npm test
 
 .PHONY: test-npm-publish
-test-npm-publish: $(NODE_EXE)
+test-npm-publish: $(NODE_EXE) ## Test the `npm publish` command.
 	npm_package_config_publishtest=true $(NODE) deps/npm/test/run.js
 
 .PHONY: test-js-native-api
-test-js-native-api: test-build-js-native-api
+test-js-native-api: test-build-js-native-api ## Run JS Native-API tests.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) js-native-api
 
 .PHONY: test-js-native-api-clean
 .NOTPARALLEL: test-js-native-api-clean
-test-js-native-api-clean:
+test-js-native-api-clean: ## Remove JS Native-API testing artifacts.
 	$(RM) -r test/js-native-api/*/build
 	$(RM) test/js-native-api/.buildstamp
 
 .PHONY: test-node-api
-test-node-api: test-build-node-api
+test-node-api: test-build-node-api ## Run Node-API tests.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) node-api
 
 .PHONY: test-node-api-clean
 .NOTPARALLEL: test-node-api-clean
-test-node-api-clean:
+test-node-api-clean: ## Remove Node-API testing artifacts.
 	$(RM) -r test/node-api/*/build
 	$(RM) test/node-api/.buildstamp
 
 .PHONY: test-addons
-test-addons: test-build test-js-native-api test-node-api
+test-addons: test-build test-js-native-api test-node-api ## Run addon tests.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) addons
 
 .PHONY: test-addons-clean
 .NOTPARALLEL: test-addons-clean
-test-addons-clean:
+test-addons-clean: ## Remove addon testing artifacts.
 	$(RM) -r "$(ADDONS_HEADERS_DIR)"
 	$(RM) -r test/addons/??_*/
 	$(RM) -r test/addons/*/build
@@ -694,7 +693,7 @@ test-addons-clean:
 	$(MAKE) test-node-api-clean
 
 .PHONY: test-with-async-hooks
-test-with-async-hooks:
+test-with-async-hooks: ## Run tests with async hooks.
 	$(MAKE) build-addons
 	$(MAKE) build-js-native-api-tests
 	$(MAKE) build-node-api-tests
@@ -711,7 +710,7 @@ test-with-async-hooks:
 .PHONY: test-v8-updates
 ifneq ("","$(wildcard deps/v8/tools/run-tests.py)")
 # Related CI job: node-test-commit-v8-linux
-test-v8: v8  ## Runs the V8 test suite on deps/v8.
+test-v8: v8  ## Run the V8 test suite on deps/v8.
 	export PATH="$(NO_BIN_OVERRIDE_PATH)" && \
 		$(PYTHON) deps/v8/tools/run-tests.py --gn --arch=$(V8_ARCH) $(V8_TEST_OPTIONS) \
 				mjsunit cctest debugger inspector message preparser \
@@ -720,24 +719,24 @@ test-v8: v8  ## Runs the V8 test suite on deps/v8.
 	$(info Testing hash seed)
 	$(MAKE) test-hash-seed
 
-test-v8-intl: v8
+test-v8-intl: v8 ## Run the v8 test suite, intl tests.
 	export PATH="$(NO_BIN_OVERRIDE_PATH)" && \
 		$(PYTHON) deps/v8/tools/run-tests.py --gn --arch=$(V8_ARCH) \
 				intl \
 				$(TAP_V8_INTL)
 	$(call convert_to_junit,$(TAP_V8_INTL_JSON))
 
-test-v8-benchmarks: v8
+test-v8-benchmarks: v8 ## Run the v8 test suite, benchmarks.
 	export PATH="$(NO_BIN_OVERRIDE_PATH)" && \
 		$(PYTHON) deps/v8/tools/run-tests.py --gn --arch=$(V8_ARCH) \
 				benchmarks \
 				$(TAP_V8_BENCHMARKS)
 	$(call convert_to_junit,$(TAP_V8_BENCHMARKS_JSON))
 
-test-v8-updates:
+test-v8-updates: ## Run the v8 test suite, updates.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) v8-updates
 
-test-v8-all: test-v8 test-v8-intl test-v8-benchmarks test-v8-updates
+test-v8-all: test-v8 test-v8-intl test-v8-benchmarks test-v8-updates ## Run the entire V8 test suite, including intl, benchmarks, and updates.
 # runs all v8 tests
 else
 test-v8 test-v8-intl test-v8-benchmarks test-v8-all:
@@ -761,15 +760,15 @@ tools/doc/node_modules: tools/doc/package.json
 
 .PHONY: doc-only
 doc-only: tools/doc/node_modules \
-	$(apidoc_dirs) $(apiassets)  ## Builds the docs with the local or the global Node.js binary.
+	$(apidoc_dirs) $(apiassets) ## Build the docs with the local or the global Node.js binary.
 	@if [ "$(shell $(node_use_openssl))" != "true" ]; then \
 		echo "Skipping doc-only (no crypto)"; \
 	else \
 		$(MAKE) out/doc/api/all.html out/doc/api/all.json out/doc/api/stability; \
 	fi
 
 .PHONY: doc
-doc: $(NODE_EXE) doc-only
+doc: $(NODE_EXE) doc-only ## Build Node.js, and then build the documentation with the new binary.
 
 out/doc:
 	mkdir -p $@
@@ -841,16 +840,16 @@ out/doc/api/stability: out/doc/api/all.json tools/doc/stability.mjs | out/doc/ap
 	fi
 
 .PHONY: docopen
-docopen: out/doc/api/all.html
+docopen: out/doc/api/all.html ## Open the documentation in a web browser.
 	@$(PYTHON) -mwebbrowser file://$(abspath $<)
 
 .PHONY: docserve
-docserve: $(apidocs_html) $(apiassets)
+docserve: $(apidocs_html) $(apiassets) ## Serve the documentation on localhost:8000.
 	@$(PYTHON) -m http.server 8000 --bind 127.0.0.1 --directory out/doc/api
 
 .PHONY: docclean
 .NOTPARALLEL: docclean
-docclean:
+docclean: ## Remove the generated documentation.
 	$(RM) -r out/doc
 	$(RM) "$(VERSIONS_DATA)"
 
@@ -1032,7 +1031,7 @@ endif
 endif
 
 .PHONY: release-only
-release-only: check-xz
+release-only: check-xz ## Prepare Node.js for release.
 	@if [ "$(DISTTYPE)" = "release" ] && `grep -q REPLACEME doc/api/*.md`; then \
 		echo 'Please update REPLACEME tags in the following doc/api/*.md files (See doc/contributing/releases.md):\n' ; \
 		REPLACEMES="$(shell grep -l REPLACEME doc/api/*.md)" ; \
@@ -1151,11 +1150,10 @@ endif
 	sh tools/osx-notarize.sh $(FULLVERSION)
 
 .PHONY: pkg
-# Builds the macOS installer for releases.
-pkg: $(PKG)
+pkg: $(PKG) ## Build the macOS installer for releases.
 
 .PHONY: corepack-update
-corepack-update:
+corepack-update: ## Update Corepack to the latest version.
 	mkdir -p /tmp/node-corepack
 	curl -qLo /tmp/node-corepack/package.tgz "$$($(call available-node,$(NPM) view corepack dist.tarball))"
 
@@ -1328,9 +1326,8 @@ endif
 bench bench-all: bench-addons-build
 	$(warning Please use benchmark/run.js or benchmark/compare.js to run the benchmarks.)
 
-# Build required addons for benchmark before running it.
 .PHONY: bench-addons-build
-bench-addons-build: | $(NODE_EXE) benchmark/napi/.buildstamp
+bench-addons-build: | $(NODE_EXE) benchmark/napi/.buildstamp ## Build required addons for benchmark before running it.
 
 .PHONY: bench-addons-clean
 .NOTPARALLEL: bench-addons-clean
@@ -1371,13 +1368,11 @@ tools/.mdlintstamp: $(LINT_MD_FILES)
 	@touch $@
 
 .PHONY: lint-md
-# Lints the markdown documents maintained by us in the codebase.
-lint-md: lint-js-doc | tools/.mdlintstamp
+lint-md: lint-js-doc | tools/.mdlintstamp ## Lint the markdown documents maintained by us in the codebase.
 
 run-format-md = tools/lint-md/lint-md.mjs --format $(LINT_MD_FILES)
 .PHONY: format-md
-# Formats the markdown documents maintained by us in the codebase.
-format-md:
+format-md: ## Format the markdown documents maintained by us in the codebase.
 	@$(call available-node,$(run-format-md))
 
 
@@ -1392,15 +1387,14 @@ tools/eslint/node_modules/eslint/bin/eslint.js: tools/eslint/package-lock.json
 	-cd tools/eslint && $(call available-node,$(run-npm-ci))
 
 .PHONY: lint-js-fix
-lint-js-fix: tools/eslint/node_modules/eslint/bin/eslint.js
+lint-js-fix: tools/eslint/node_modules/eslint/bin/eslint.js ## Lint and fix the JavaScript code with eslint./eslint/bin/eslint.js
 	@$(call available-node,$(run-lint-js-fix))
 
 .PHONY: lint-js
 .PHONY: lint-js-doc
 # Note that on the CI `lint-js-ci` is run instead.
-# Lints the JavaScript code with eslint.
 lint-js-doc: LINT_JS_TARGETS=doc
-lint-js lint-js-doc: tools/eslint/node_modules/eslint/bin/eslint.js
+lint-js lint-js-doc: tools/eslint/node_modules/eslint/bin/eslint.js ## Lint the JavaScript code with eslint./eslint/bin/eslint.js
 	@if [ "$(shell $(node_use_openssl))" != "true" ]; then \
 		echo "Skipping $@ (no crypto)"; \
 	else \
@@ -1475,12 +1469,12 @@ FORMAT_CPP_FILES += $(wildcard \
 ADDON_DOC_LINT_FLAGS=-whitespace/ending_newline,-build/header_guard
 
 .PHONY: format-cpp-build
-format-cpp-build:
+format-cpp-build: ## Build 'clang-format' tooling for C++ code formatting.
 	cd tools/clang-format && $(call available-node,$(run-npm-ci))
 
 .PHONY: format-cpp-clean
 .NOTPARALLEL: format-cpp-clean
-format-cpp-clean:
+format-cpp-clean: ## Remove 'clang-format' tooling for C++ code formatting.
 	$(RM) -r tools/clang-format/node_modules
 
 CLANG_FORMAT_START ?= HEAD
@@ -1491,7 +1485,7 @@ CLANG_FORMAT_START ?= HEAD
 #  $ CLANG_FORMAT_START=`git rev-parse HEAD~1` make format-cpp
 # To format diff between main and current branch head (main...HEAD):
 #  $ CLANG_FORMAT_START=main make format-cpp
-format-cpp: ## Format C++ diff from $CLANG_FORMAT_START to current changes
+format-cpp: ## Format C++ diff from $CLANG_FORMAT_START to current changes.
 ifneq ("","$(wildcard tools/clang-format/node_modules/)")
 	$(info Formatting C++ diff from $(CLANG_FORMAT_START)..)
 	@$(PYTHON) tools/clang-format/node_modules/.bin/git-clang-format \
@@ -1510,8 +1504,7 @@ else
 CPPLINT_QUIET = --quiet
 endif
 .PHONY: lint-cpp
-# Lints the C++ code with cpplint.py and checkimports.py.
-lint-cpp: tools/.cpplintstamp
+lint-cpp: tools/.cpplintstamp ## Lint the C++ code with cpplint.py and checkimports.py.
 
 tools/.cpplintstamp: $(LINT_CPP_FILES)
 	$(info Running C++ linter...)
@@ -1520,7 +1513,7 @@ tools/.cpplintstamp: $(LINT_CPP_FILES)
 	@touch $@
 
 .PHONY: lint-addon-docs
-lint-addon-docs: tools/.doclintstamp
+lint-addon-docs: tools/.doclintstamp ## Lint the addon documentation.
 
 tools/.doclintstamp: test/addons/.docbuildstamp
 	$(info Running C++ linter on addon docs...)
@@ -1534,7 +1527,7 @@ cpplint: lint-cpp
 .PHONY: lint-py-build
 # python -m pip install ruff
 # Try with '--system' if it fails without; the system may have set '--user'
-lint-py-build:
+lint-py-build: ## Build resources needed to lint python files.
 	$(info Pip installing ruff on $(shell $(PYTHON) --version)...)
 	$(PYTHON) -m pip install --upgrade --target tools/pip/site-packages ruff==0.6.5 || \
 		$(PYTHON) -m pip install --upgrade --system --target tools/pip/site-packages ruff==0.6.5
@@ -1559,14 +1552,13 @@ endif
 .PHONY: lint-yaml-build
 # python -m pip install yamllint
 # Try with '--system' if it fails without; the system may have set '--user'
-lint-yaml-build:
+lint-yaml-build: ## Build resources needed to lint YAML files.
 	$(info Pip installing yamllint on $(shell $(PYTHON) --version)...)
 	$(PYTHON) -m pip install --upgrade -t tools/pip/site-packages yamllint || \
 		$(PYTHON) -m pip install --upgrade --system -t tools/pip/site-packages yamllint
 
 .PHONY: lint-yaml
-# Lints the YAML files with yamllint.
-lint-yaml:
+lint-yaml: ## Lint the YAML files with yamllint.
 	@if [ -d "tools/pip/site-packages/yamllint" ]; then \
 			$(info Running YAML linter...) \
 			PYTHONPATH=tools/pip $(PYTHON) -m yamllint .; \
@@ -1605,7 +1597,7 @@ lint lint-ci:
 endif
 
 .PHONY: lint-clean
-lint-clean:
+lint-clean: ## Remove linting artifacts.
 	$(RM) tools/.*lintstamp
 	$(RM) .eslintcache
 	$(RM) -r tools/eslint/node_modules
@@ -1619,7 +1611,7 @@ DOCKER_COMMAND ?= docker run -it -v $(PWD):/node
 IS_IN_WORKTREE = $(shell grep '^gitdir: ' $(PWD)/.git 2>/dev/null)
 GIT_WORKTREE_COMMON = $(shell git rev-parse --git-common-dir)
 DOCKER_COMMAND += $(if $(IS_IN_WORKTREE), -v $(GIT_WORKTREE_COMMON):$(GIT_WORKTREE_COMMON))
-gen-openssl: ## Generate platform dependent openssl files (requires docker)
+gen-openssl: ## Generate platform dependent openssl files (requires docker).
 	docker build -t node-openssl-builder deps/openssl/config/
 	$(DOCKER_COMMAND) node-openssl-builder make -C deps/openssl/config
 else