Reformat comments based on JSDoc

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