From 059c05a53feef65c89497c1832dd6129638a5346 Mon Sep 17 00:00:00 2001
From: Mike Bland <mbland@acm.org>
Date: Wed, 27 Dec 2023 10:44:16 -0500
Subject: [PATCH] Add orig/jsdoc.sh, update README.md

Added a "Background" section explaining how the module came to be.
---
 README.md     | 42 +++++++++++++++++++++++++++++---------
 orig/jsdoc.sh | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 88 insertions(+), 10 deletions(-)
 create mode 100755 orig/jsdoc.sh

diff --git a/README.md b/README.md
index 80b9219..be8eeac 100644
--- a/README.md
+++ b/README.md
@@ -38,22 +38,25 @@ would use `jsdoc` on its own.
 
 The `jsdoc` command will:
 
-- silently write new output into an existing directory, and
-- not show where the generated `index.html` entrypoint resides.
+1. silently write new output into an existing directory, and
+2. not show where the generated `index.html` entrypoint resides.
+
+While admittedly minor annoyances, they're still annoyances:
+
+1. It can be surprising to change the structure of your project, run `jsdoc`,
+   and have stale files and directories laying around. This can make it
+   inconvenient to find where the newly generated documentation actually is.
+
+2. Seeing the path to the new `index.html` helps make sure things end up where
+   you expect. This is especially useful when the JavaScript code is embedded in
+   a larger, possibly multilanguage repository. It also makes it far more
+   convenient to copy the path and open it in a browser.
 
 `jsdoc` doesn't have any command line options to deal with either of these
 issues. Not even `--verbose` nor `--debug` will show the path to `index.html`.
 
 This wrapper resolves both of those minor annoyances.
 
-- Regarding the first, it can be surprising to change the structure of your
-  project, run `jsdoc`, and have stale files and directories laying around.
-
-- Regarding the second, it's really handy to print the path to `index.html`. It
-  helps make sure things end up where you expect, and makes it convenient to
-  copy and open in a browser. This is especially useful when the JavaScript code
-  is embedded in a larger, possibly multilanguage repository.
-
 ## Examples
 
 ### This project
@@ -109,9 +112,28 @@ $ pnpm jsdoc
 ../../../build/jsdoc/tomcat-servlet-testing-example-frontend/0.0.0/index.html
 ```
 
+## Background
+
+I developed this while experimenting with JSDoc on
+[mbland/tomcat-servlet-testing-example][]. I was surprised and frustrated that
+the CLI was silent when it came to reporting where it emitted its output.
+
+My first version of the wrapper was a short [Bash][] script, which is available
+here as [orig/jsdoc.sh](./orig/jsdoc.sh). It was short and to the point, and
+used variations of `sed` and `find` that I'd somehow never used before. (In
+fact, that's the main reason why I'm keeping it around, for reference.)
+
+It helped me move forward and was a great proof of concept, but was nowhere near
+as robust as the [Node.js][] version in this package. It also wasn't natively
+portable to Windows. So I decided to dig in and make it so, using it as a
+Node.js, JSDoc, and [npm packaging][] exercise as well.
+
 [JSDoc]: https://jsdoc.app/
 [cli]: https://github.com/jsdoc/jsdoc
 [coveralls-jsdw]: https://coveralls.io/github/mbland/jsdoc-cli-wrapper?branch=main
 [pnpm]: https://pnpm.io/
 [mbland/tomcat-servlet-testing-example]: https://github.com/mbland/tomcat-servlet-testing-example
 [Gradle]: https://gradle.org/
+[Bash]: https://www.gnu.org/software/bash/
+[Node.js]: https://nodejs.org/
+[npm packaging]: https://docs.npmjs.com/packages-and-modules
diff --git a/orig/jsdoc.sh b/orig/jsdoc.sh
new file mode 100755
index 0000000..15756de
--- /dev/null
+++ b/orig/jsdoc.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+#
+# jsdoc wrapper used by the "jsdoc" package.json script
+#
+# Removes the existing destination directory if it exists, runs JSDoc, and emits
+# the relative path to the generated index.html file.
+#
+# Prompts the user to install JSDoc if not present. It's not a package.json
+# devDependency because it seems that many folks browse JSDoc in their IDE
+# without needing to generate the HTML version.
+
+if ! command -v jsdoc > /dev/null; then
+  echo \"Run 'pnpm add -g jsdoc' to install JSDoc: https://jsdoc.app\"
+  exit 1
+fi
+
+ARGS=()
+DESTINATION=""
+
+# Discover the output directory, since JSDoc doesn't have a setting to emit it.
+while [[ "$#" -ne 0 ]]; do
+  curArg="$1"
+  shift
+  ARGS+=("$curArg")
+
+  case "$curArg" in
+  -c|--configure)
+    if [[ -z "$DESTINATION" ]]; then
+      # All bets are off if the destination property contains an escaped '"' or
+      # there's more than one "destination" property defined.
+      DESTINATION="$(sed -ne 's/.*"destination": *"\([^"]*\)".*/\1/p' < "$1")"
+    fi
+    ARGS+=("$1")
+    shift
+    ;;
+  -d|--destination)
+    DESTINATION="$1"
+    ARGS+=("$1")
+    shift
+    ;;
+  *)
+    ;;
+  esac
+done
+
+# "out" is the JSDoc default directory.
+DESTINATION="${DESTINATION:-out}"
+rm -rf "$DESTINATION"
+
+if jsdoc "${ARGS[@]}"; then
+  exec find "$DESTINATION" -name index.html -print -quit
+fi