(parser/docs) Add jsdoc annotations and TypeScript type file (#2517)

Adds JSDoc annotations and a .tsconfig that allows TypeScript to be run in it's "allowJS" mode and apply type and sanity checking to JavaScript code also. See Type Checking JavaScript Files.

I've been using TypeScript a lot lately and finding it very beneficial and wanted to get those same benefits here but without converting the whole project to TypeScript. It was rough at the beginning but now that this is finished I think it's about 80%-90% of the benefits without any of the TS compilation pipeline. The big difference in being JSDoc for adding typing information vs inline types with TypeScript.

Should be super helpful for maintainers using an editor with tight TypeScript integration and the improved docs/comments should help everyone else.

- Adds types/index.d.ts to NPM build (should be useful for TypeScript peeps)
- Improves documentation of many functions
- Adds JSDoc annotations to almost all functions
- Adds JSDoc type annotations to variables that can't be inferred
- Refactors a few smaller things to allow the TypeScript compiler to better infer what 
   is happening (and usually also made the code clearer)

Author: joshgoebel

.eslintrc.js

@@ -17,6 +17,10 @@ module.exports = {
         "ecmaVersion": 2018,
         "sourceType": "module"
     },
+    "parser": '@typescript-eslint/parser',
+    "plugins": [
+      "@typescript-eslint"
+    ],
     "rules": {
       "array-callback-return": "error",
       "block-scoped-var": "error",
@@ -27,7 +31,7 @@ module.exports = {
       // for now ignore diff between types of quoting
       "quotes": "off",
       // this is the style we are already using
-      "operator-linebreak": ["error","after", { "overrides": { "?": "after", ":": "after" } }],
+      "operator-linebreak": ["error","before", { "overrides": { "?": "after", ":": "after", "+": "after" } }],
       // sometimes we declare variables with extra spacing
       "indent": ["error", 2, {"VariableDeclarator":2}],
       // seems like a good idea not to use explicit undefined

docs/api.rst

@@ -101,13 +101,13 @@ Applies highlighting to all ``<pre><code>...</code></pre>`` blocks on a page.
 Attaches highlighting to the page load event.
 
 
-``registerLanguage(name, language)``
+``registerLanguage(languageName, languageDefinition)``
 ------------------------------------
 
 Adds new language to the library under the specified name. Used mostly internally.
 
-* ``name``: a string with the name of the language being registered
-* ``language``: a function that returns an object which represents the
+* ``languageName``: a string with the name of the language being registered
+* ``languageDefinition``: a function that returns an object which represents the
   language definition. The function is passed the ``hljs`` object to be able
   to use common regular expressions defined within it.
 

package-lock.json

@@ -21,14 +21,13 @@
     "url": "git://github.com/highlightjs/highlight.js.git"
   },
   "main": "./lib/index.js",
+  "types": "./types/index.d.ts",
   "scripts": {
     "mocha": "mocha",
-
     "build_and_test": "npm run build && npm run test",
     "build": "node ./tools/build.js -t node",
     "build-cdn": "node ./tools/build.js -t cdn",
     "build-browser": "node ./tools/build.js -t browser :common",
-
     "test": "mocha --globals document test",
     "test-markup": "mocha --globals document test/markup",
     "test-detect": "mocha --globals document test/detect",
@@ -38,6 +37,8 @@
     "node": "*"
   },
   "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^2.32.0",
+    "@typescript-eslint/parser": "^2.32.0",
     "clean-css": "^4.2.1",
     "cli-table": "^0.3.1",
     "colors": "^1.1.2",
@@ -62,7 +63,8 @@
     "rollup-plugin-json": "^4.0.0",
     "should": "^13.2.3",
     "terser": "^4.3.9",
-    "tiny-worker": "^2.3.0"
+    "tiny-worker": "^2.3.0",
+    "typescript": "^4.0.0-dev.20200512"
   },
   "dependencies": {}
 }