feature: jsdoc annotations and generation (#177)

# What
Adds the ability to generate a website with reference documentation based on JSDoc annotations in the Javascript code. Annotations are also added.  This will help you if you use an editor that knows how to parse JSDoc annotations.

**This change adds a workflow that depends on NodeJS** however, normal usage of the gateway will not require NodeJs, nor will any development workflows.  In the future, development workflows will require NodeJs.  Discussion on this topic here: #163

## Usage
To generate the documentation run:
```
make jsdoc
```
It will be located in the `./reference` folder at the root of the project

To generate and view the documentation in a browser, run:
```
make jsdoc-open
```

To remove generated documentation, run:
```
make clean
```

.gitignore

@@ -1,7 +1,58 @@
-# Created by https://www.toptal.com/developers/gitignore/api/intellij
-# Edit at https://www.toptal.com/developers/gitignore?templates=intellij
+# Created by https://www.toptal.com/developers/gitignore/api/intellij+all,node,vim,emacs,macos
+# Edit at https://www.toptal.com/developers/gitignore?templates=intellij+all,node,vim,emacs,macos
 
-### Intellij ###
+### Emacs ###
+# -*- mode: gitignore; -*-
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# Org-mode
+.org-id-locations
+*_archive
+
+# flymake-mode
+*_flymake.*
+
+# eshell files
+/eshell/history
+/eshell/lastdir
+
+# elpa packages
+/elpa/
+
+# reftex files
+*.rel
+
+# AUCTeX auto folder
+/auto/
+
+# cask packages
+.cask/
+dist/
+
+# Flycheck
+flycheck_*.el
+
+# server auth directory
+/server/
+
+# projectiles files
+.projectile
+
+# directory configuration
+.dir-locals.el
+
+# network security
+/network-security.data
+
+
+### Intellij+all ###
 # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
 # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
 
@@ -12,6 +63,9 @@
 .idea/**/dictionaries
 .idea/**/shelf
 
+# AWS User-specific
+.idea/**/aws.xml
+
 # Generated files
 .idea/**/contentModel.xml
 
@@ -53,6 +107,12 @@ cmake-build-*/
 # IntelliJ
 out/
 
+# jsdoc build directory
+reference/
+
+# minio storage
+data/
+
 # mpeltonen/sbt-idea plugin
 .idea_modules/
 
@@ -62,6 +122,9 @@ atlassian-ide-plugin.xml
 # Cursive Clojure plugin
 .idea/replstate.xml
 
+# SonarLint plugin
+.idea/sonarlint/
+
 # Crashlytics plugin (for Android Studio and IntelliJ)
 com_crashlytics_export_strings.xml
 crashlytics.properties
@@ -74,37 +137,209 @@ fabric.properties
 # Android studio 3.1+ serialized cache file
 .idea/caches/build_file_checksums.ser
 
-### Intellij Patch ###
-# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721
+### Intellij+all Patch ###
+# Ignore everything but code style settings and run configurations
+# that are supposed to be shared within teams.
+
+.idea/*
+
+!.idea/codeStyles
+!.idea/runConfigurations
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Node ###
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
 
-*.iml
-modules.xml
-.idea/misc.xml
-*.ipr
+### Node Patch ###
+# Serverless Webpack directories
+.webpack/
 
-# Sonarlint plugin
-# https://plugins.jetbrains.com/plugin/7973-sonarlint
-.idea/**/sonarlint/
+# Optional stylelint cache
 
-# SonarQube Plugin
-# https://plugins.jetbrains.com/plugin/7238-sonarqube-community-plugin
-.idea/**/sonarIssues.xml
+# SvelteKit build / generate output
+.svelte-kit
 
-# Markdown Navigator plugin
-# https://plugins.jetbrains.com/plugin/7896-markdown-navigator-enhanced
-.idea/**/markdown-navigator.xml
-.idea/**/markdown-navigator-enh.xml
-.idea/**/markdown-navigator/
+### Vim ###
+# Swap
+[._]*.s[a-v][a-z]
+!*.svg  # comment out if you don't need vector files
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
 
-# Cache file creation bug
-# See https://youtrack.jetbrains.com/issue/JBR-2257
-.idea/$CACHE_FILE$
+# Session
+Session.vim
+Sessionx.vim
 
-# CodeStream plugin
-# https://plugins.jetbrains.com/plugin/12206-codestream
-.idea/codestream.xml
+# Temporary
+.netrwhist
+# Auto-generated tag files
+tags
+# Persistent undo
+[._]*.un~
 
-# End of https://www.toptal.com/developers/gitignore/api/intellij
+# End of https://www.toptal.com/developers/gitignore/api/intellij+all,node,vim,emacs,macos
 
 # Test data files
 test-settings.*

.tool-versions

@@ -0,0 +1 @@
+nodejs 20.8.0

GNUmakefile

@@ -22,3 +22,30 @@ help:
 .PHONY: test
 test: ## Run all tests
 	$Q $(CURDIR)/test.sh --type oss --unprivileged false --latest-njs false
+
+# Check if the 'open' command exists on the system
+OPEN := $(shell command -v open 2> /dev/null)
+
+# Define the open command based on availability
+ifeq ($(OPEN),)
+	OPEN_COMMAND = xdg-open
+else
+	OPEN_COMMAND = open
+endif
+
+docs_destination_directory = "reference"
+
+.PHONY: docs
+docs:
+	npx jsdoc -c $(CURDIR)/jsdoc/conf.json -d $(CURDIR)/$(docs_destination_directory) || true
+
+.PHONY: jsdoc
+jsdoc: docs ## Build JSDoc output
+
+.PHONY: jsdoc-open
+jsdoc-open: docs
+	$(OPEN_COMMAND) $(CURDIR)/$(docs_destination_directory)/index.html
+
+.PHONY: clean
+clean: ## Clean up build artifacts
+	$Q rm -rf $(CURDIR)/$(docs_destination_directory)

README.md

@@ -68,6 +68,7 @@ deployments/                     contains files used for deployment technologies
 docs/                            contains documentation about the project
 examples/                        contains additional `Dockerfile` examples that extend the base 
                                  configuration
+jsdoc                            JSDoc configuration files
 oss/                             contains files used solely in NGINX OSS configurations
 plus/                            contains files used solely in NGINX Plus configurations
 test/                            contains automated tests for validang that the examples work
@@ -79,9 +80,10 @@ Dockerfile.buildkit.plus         Dockerfile with the same configuration as Docke
                                  with support for hiding secrets using Docker's Buildkit
 Dockerfile.latest-njs            Dockerfile that inherits from the last build of the gateway and
                                  then builds and installs the latest version of njs from source
-Dockerfile.unprivileged  Dockerfiles that inherits from the last build of the gateway and
+Dockerfile.unprivileged          Dockerfiles that inherits from the last build of the gateway and
                                  makes the necessary modifications to allow running the container
                                  as a non root, unprivileged user.
+package.json                     Node.js package file used only for generating JSDoc
 settings.example                 Docker env file example
 standalone_ubuntu_oss_install.sh install script that will install the gateway as a Systemd service
 test.sh                          test launcher