Update source docs

kgryte · kgryte · commit e35096f60009 · 2018-04-26T10:05:37.000-07:00
diff --git a/tools/make/lib/examples/javascript.mk b/tools/make/lib/examples/javascript.mk
@@ -18,10 +18,23 @@
 
 # RULES #
 
-# Run examples.
+#/
+# Runs JavaScript examples consecutively.
 #
-# This target runs a list of examples in sequential order. Note that we assume the examples can be run using Node.js.
-
+# ## Notes
+#
+# -   This rule is useful when wanting to glob for JavaScript examples files (e.g., run all JavaScript examples for a particular package).
+# -   This rule **assumes** that examples files can be run using Node.js.
+#
+#
+# @param {string} [EXAMPLES_FILTER] - file path pattern (e.g., `.*/math/base/special/abs/.*`)
+#
+# @example
+# make examples-javascript
+#
+# @example
+# make examples-javascript EXAMPLES_FILTER=.*/strided/common/.*
+#/
 examples-javascript: $(NODE_MODULES)
 	$(QUIET) $(FIND_EXAMPLES_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | while read -r file; do \
 		echo ""; \
@@ -33,11 +46,20 @@ examples-javascript: $(NODE_MODULES)
 
 .PHONY: examples-javascript
 
-
-# Run examples.
+#/
+# Runs a specified list of JavaScript examples consecutively.
 #
-# This target runs a specified list of examples in sequential order. Note that we assume the examples can be run using Node.js.
-
+# ## Notes
+#
+# -   This rule is useful when wanting to run a list of JavaScript examples files generated by some other command (e.g., a list of changed JavaScript examples files obtained via `git diff`).
+# -   This rule **assumes** that examples files can be run using Node.js.
+#
+#
+# @param {string} FILES - list of JavaScript example file paths
+#
+# @example
+# make examples-javascript-files FILES='/foo/example.js /bar/example.js'
+#/
 examples-javascript-files: $(NODE_MODULES)
 	$(QUIET) for file in $(FILES); do \
 		echo ""; \
