Update source docs

kgryte · kgryte · commit e12b754987ca · 2018-04-26T10:15:50.000-07:00
diff --git a/tools/make/lib/examples/markdown_javascript.mk b/tools/make/lib/examples/markdown_javascript.mk
@@ -42,10 +42,22 @@ REMARK_RUN_JAVASCRIPT_EXAMPLES_FLAGS ?= \
 
 # RULES #
 
-# Run examples.
+#/
+# Runs JavaScript examples found in Markdown files in sequential order.
 #
-# This target runs JavaScript examples in Markdown files in sequential order.
-
+# ## Notes
+#
+# -   This rule is useful when wanting to glob for Markdown files (e.g., run all JavaScript examples found in Markdown files for a particular package).
+#
+#
+# @param {string} [MARKDOWN_FILTER] - file path pattern (e.g., `.*/math/base/special/abs/.*`)
+#
+# @example
+# make markdown-examples-javascript
+#
+# @example
+# make markdown-examples-javascript MARKDOWN_FILTER=.*/strided/common/.*
+#/
 markdown-examples-javascript: $(NODE_MODULES)
 	$(QUIET) $(FIND_MARKDOWN_CMD) | grep '^[\/]\|^[a-zA-Z]:[/\]' | grep 'README.md' | grep -v '/_tools/' | grep -v '/stdlib/tools/' | while read -r file; do \
 		echo ""; \
@@ -59,11 +71,19 @@ markdown-examples-javascript: $(NODE_MODULES)
 
 .PHONY: markdown-examples-javascript
 
-
-# Run examples.
+#/
+# Runs JavaScript examples found in a specified list of Markdown files in sequential order.
 #
-# This target runs JavaScript examples from a specified list of Markdown files in sequential order.
-
+# ## Notes
+#
+# -   This rule is useful when wanting to run JavaScript examples found in a list of Markdown files generated by some other command (e.g., a list of changed Markdown files obtained via `git diff`).
+#
+#
+# @param {string} FILES - list of Markdown file paths
+#
+# @example
+# make markdown-examples-javascript-files FILES='/foo/README.md /bar/README.md'
+#/
 markdown-examples-javascript-files: $(NODE_MODULES)
 	$(QUIET) for file in $(FILES); do \
 		echo ""; \
