Reformat comments based on JSDoc

kgryte · kgryte · commit a9cf24d43cd7 · 2018-01-11T00:30:01.000-08:00
diff --git a/tools/make/lib/benchmark/javascript.mk b/tools/make/lib/benchmark/javascript.mk
@@ -1,10 +1,23 @@
 
 # TARGETS #
 
-# Run JavaScript benchmarks.
+#/
+# Runs JavaScript benchmarks consecutively.
 #
-# This target runs a list of JavaScript benchmarks in sequential order. Note that we assume the benchmarks can be run using Node.js.
-
+# ## Notes
+#
+# -   This recipe assumes that benchmark files can be run via Node.js.
+# -   This recipe is useful when wanting to glob for JavaScript benchmark files (e.g., run all JavaScript benchmarks for a particular package).
+#
+#
+# @param {string} [BENCHMARKS_FILTER] - filepath pattern (e.g., `.*/utils/group-by/.*`)
+#
+# @example
+# make benchmark-javascript
+#
+# @example
+# make benchmark-javascript BENCHMARKS_FILTER=.*/utils/group-by/.*
+#/
 benchmark-javascript: $(NODE_MODULES)
 	$(QUIET) $(FIND_BENCHMARKS_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \
 		echo ""; \
@@ -16,11 +29,20 @@ benchmark-javascript: $(NODE_MODULES)
 
 .PHONY: benchmark-javascript
 
-
-# Run JavaScript benchmarks.
+#/
+# Runs a specified list of JavaScript benchmarks consecutively.
 #
-# This target runs a specified list of JavaScript benchmarks in sequential order. Note that we assume the benchmarks can be run using Node.js.
-
+# ## Notes
+#
+# -   This recipe assumes that benchmark files can be run via Node.js.
+# -   This recipe is useful when wanting to run a list of JavaScript benchmark files generated by some other command (e.g., a list of changed JavaScript benchmark files obtained via `git diff`).
+#
+#
+# @param {string} FILES - list of JavaScript benchmark file paths
+#
+# @example
+# make benchmark-javascript-files FILES='/foo/benchmark.js /bar/benchmark.js'
+#/
 benchmark-javascript-files: $(NODE_MODULES)
 	$(QUIET) for file in $(FILES); do \
 		echo ""; \
