Merge pull request #1760 from TypeStrong/beta

TypeStrong · Jun 26, 2022 · 56517ef · 56517ef
2 parents 95a7155 + f38ad6f
commit 56517ef
Show file tree

Hide file tree

Showing 304 changed files with 20,642 additions and 11,064 deletions.
diff --git a/.config/.prettierignore b/.config/.prettierignore
@@ -1,13 +1,17 @@
 ../.nyc_output
 ../coverage
 ../dist
+../docs
 **/package-lock.json
 ../src/test/**/specs*.json
 ../src/test/packages/**/*.js
 ../src/test/renderer/specs
 ../src/test/renderer/testProject
+../src/test/utils/options/readers/data/invalid2.json
 ../static/main.js
 ../example/docs/
+**/tmp
+**/.vs
 
 # Turn this back on once supported by Prettier
 ../src/test/converter2/behavior/instantiationExpressions.ts

diff --git a/.config/typedoc.json b/.config/typedoc.json
@@ -6,14 +6,27 @@
         "ConverterComponent",
         "RendererComponent",
         "SORT_STRATEGIES",
-        "_ModelToObject"
+        "_ModelToObject",
+        "EventHooksMomento",
+        "MarkedPlugin"
     ],
     "entryPoints": ["../src"],
     "entryPointStrategy": "Resolve",
     "excludeExternals": true,
+    "excludeInternal": false,
     "excludePrivate": true,
-    "excludeInternal": true,
     "treatWarningsAsErrors": false,
-    "validation": true,
+    "validation": {
+        "notExported": true,
+        "invalidLink": true,
+        "notDocumented": false
+    },
+    "visibilityFilters": {
+        "protected": false,
+        "private": false,
+        "inherited": true,
+        "external": false,
+        "@internal": false
+    },
     "logLevel": "Verbose"
 }
diff --git a/.eslintrc b/.eslintrc
@@ -17,6 +17,7 @@
     "ignorePatterns": [
         "src/test/renderer/specs",
         "dist",
+        "docs",
         "coverage",
         "static/main.js",
         "src/lib/output/themes/default/assets",
@@ -37,6 +38,9 @@
     "rules": {
         "@typescript-eslint/no-floating-promises": 1,
 
+        // This one is just annoying since it complains at incomplete code
+        "no-empty": 0,
+
         // This rule is factually incorrect. Interfaces which extend some type alias can be used to introduce
         // new type names. This is useful particularly when dealing with mixins.
         "@typescript-eslint/no-empty-interface": 0,
@@ -45,15 +49,28 @@
         "@typescript-eslint/ban-types": 0,
         "@typescript-eslint/no-explicit-any": 0,
 
+        // Really annoying, doesn't provide any value.
+        "@typescript-eslint/no-empty-function": 0,
+
         // Declaration merging with a namespace is a necessary tool when working with enums.
         "@typescript-eslint/no-namespace": 0,
 
         // Reported by TypeScript
         "@typescript-eslint/no-unused-vars": 0,
 
+        "no-console": 1,
+
         // Feel free to turn one of these back on and submit a PR!
         "@typescript-eslint/no-non-null-assertion": 0,
-        "@typescript-eslint/explicit-module-boundary-types": 0
+        "@typescript-eslint/explicit-module-boundary-types": 0,
+
+        "no-restricted-syntax": [
+            "warn",
+            {
+                "selector": "ImportDeclaration[source.value=/.*perf$/]",
+                "message": "Benchmark calls must be removed before committing."
+            }
+        ]
     },
     "overrides": [
         {

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -5,9 +5,7 @@ jobs:
         runs-on: ubuntu-latest
         strategy:
             matrix:
-                # ESLint doesn't support Node 12.10 anymore. Test on the oldest available
-                # node that our tools support.
-                node: ["12.22", "12", "14", "16"]
+                node: ["14.14", "14", "16", "18"]
         name: Node ${{ matrix.node }}
         steps:
             - name: Checkout repository
@@ -29,7 +27,7 @@ jobs:
                   # For other test runs, skip so we don't have to go build the regression screenshots.
                   SKIP_VISUAL_TEST: true
             - name: Lint
-              run: npm run lint
+              run: npm run lint -- --max-warnings 0
             - name: Circular dependency check
               uses: gerrit0/circular-dependency-check@v1
               with:

diff --git a/.github/workflows/visual-regression.yml b/.github/workflows/visual-regression.yml
@@ -28,4 +28,9 @@ jobs:
                   npm run build
                   node dist/test/capture-screenshots.js
             - name: Test
-              run: npx reg-suit run --test
+              run: npx reg-suit run -c .config/regconfig.json --test
+            - name: Upload Results
+              uses: actions/upload-artifact@v3
+              with:
+                  name: visual-regression
+                  path: dist/tmp/.reg
diff --git a/.gitignore b/.gitignore
@@ -13,6 +13,7 @@ yarn-error.log
 **/node_modules/
 /coverage/
 /dist/
+/docs
 
 typedoc*.tgz
 tmp

diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -4,6 +4,22 @@
     // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
     "version": "0.2.0",
     "configurations": [
+        {
+            "args": [
+                "--timeout",
+                "0",
+                "--config",
+                "${workspaceFolder}/.config/mocha.fast.json",
+                "-g",
+                "1734"
+            ],
+            "internalConsoleOptions": "openOnSessionStart",
+            "name": "Debug Tests",
+            "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
+            "request": "launch",
+            "skipFiles": ["<node_internals>/**"],
+            "type": "pwa-node"
+        },
         {
             "name": "Attach",
             "port": 9229,

diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -10,5 +10,6 @@
     "prettier.configPath": ".config/.prettierrc.json",
     "prettier.ignorePath": ".config/.prettierignore",
     "eslint.workingDirectories": [".", "./example"],
-    "mochaExplorer.configFile": ".config/mocha.test-explorer.json"
+    "mochaExplorer.configFile": ".config/mocha.test-explorer.json",
+    "cSpell.words": ["cname", "tsbuildinfo", "tsdoc"]
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,91 @@
 # Unreleased
 
+### Breaking Changes
+
+-   Node 12 is no longer officially supported as it has gone end of life as of 2022-04-30. It might still work, but may stop working at any time.
+-   Dropped support for TypeScript before 4.6.
+-   `{@link}` tags in comments will now be resolved as declaration references similar to TSDoc's declaration references.
+    For most cases, this will just work. See [the documentation](https://typedoc.org/guides/link-resolution/) for details on how link resolution works.
+-   TypeDoc will now produce warnings for bracketed links (`[[ target ]]`). Use `{@link target}` instead. The `{@link}` syntax will be recognized by [TypeScript 4.3](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-3.html#editor-support-for-link-tags) and later and used to provide better intellisense. TypeDoc version 0.24.0 will remove support for `[[ target ]]` style links.
+-   `extends` in typedoc.json is now resolved using NodeJS module resolution, so a local path must begin with `./`.
+-   In the JSON output for `DeclarationReflection`s, `getSignature` is no longer a one-tuple.
+-   In the JSON output for `DeclarationReflection`s, `setSignature` is no longer a one-tuple.
+-   In the JSON output for `DeclarationReflection`s, `typeParameter` has been renamed to `typeParameters`
+-   The `searchGroupBoosts` option must now be given the rendered group name rather than reflection kind names, and can be given custom group names.
+-   `@inheritDoc` now follows the behavior specified by TSDoc when copying comments with a reference.
+-   The `gaSite` option has been removed since Google Analytics now infers the site automatically, updated Google Analytics script to latest version, #1846.
+-   Comments on export declarations will only overrides comments for references and namespaces, #1901.
+-   The deprecated `listInvalidSymbolLinks` option has been removed. Use `validation.invalidLink` instead.
+-   The deprecated `true` and `false` values have been removed from `--emit`, to migrate replace `true` with `"both"` and `false` with `"docs"` (the default).
+-   Links are no longer be resolved against a global list of all symbols. See [the documentation](https://typedoc.org/guides/link-resolution/) for details on link resolution.
+-   The `validation.invalidLink` option is now on by default.
+-   `reflection.decorates`, `reflection.decorators`, and their corresponding interfaces have been removed as no code in TypeDoc used them.
+-   The shape of the `Comment` class has changed significantly to support multiple tag kinds.
+-   Listeners to `Converter.EVENT_CREATE_TYPE_PARAMETER` and `Converter.EVENT_CREATE_DECLARATION` will now never be passed a `ts.Node` as their third argument.
+-   Constant variables which are interpreted as functions will no longer have the `ReflectionFlag.Const` flag set.
+-   `reflection.defaultValue` is no longer set for enum members. The same information is available on `reflection.type` with more precision.
+-   Removed deprecated `removeReaderByName`, `addDeclarations` and `removeDeclarationByName` methods on `Options`.
+-   Removed `ProjectReflection.directory`, it was unused by TypeDoc and not properly tested.
+-   Removed `ProjectReflection.files`, this was an internal cache that should not have been exposed, and shouldn't have existed in the first place, since removing it made TypeDoc faster.
+-   Removed `ReflectionGroup.kind` since groups can now be created with the `@group` tag.
+-   Removed `ReflectionKind.Event`, the `@event` tag is now an alias for `@group Events`. Note: This changes the value of `ReflectionKind.Reference` from `16777216` to `8388608`.
+-   Themes are now set on the document element rather than on body, #1706.
+
+### Features
+
+-   TypeDoc now supports the `@group` tag to group reflections in a page. If no `@group` tag is specified, reflections will be grouped according to their kind, #1652.
+-   TypeDoc will now search for `typedoc.js(on)` in the `.config` folder in the current working directory.
+-   Entry point strategies `Resolve` and `Expand` may now specify globs, #1926.
+-   `typedoc.json` now supports comments like `tsconfig.json`.
+-   TypeDoc will now read the `blockTags`, `inlineTags`, and `modifierTags` out of `tsdoc.json` in the same directory as `tsconfig.json` if it exists.
+    It is recommended to add `"extends": ["typedoc/tsdoc.json"]`, which defines TypeDoc specific tags to your `tsdoc.json` if you create one.
+-   If an exported symbol has multiple declarations, TypeDoc will now check all appropriate declarations for comments, and warn if more than one declaration contains a comment, #1855.
+-   Improved support for JSDoc style `@example` tags. If the tag content does not include a code block, TypeDoc now follows VSCode's behavior of treating the entire block as a code block, #135.
+-   TypeDoc will now render members marked with `@deprecated` with a line through their name, #1381.
+-   Added new `commentStyle` option which can be used to control what comments TypeDoc will parse.
+
+    | Value | Behavior                               |
+    | ----- | -------------------------------------- |
+    | JSDoc | Use block comments starting with `/**` |
+    | Block | Use all block comments                 |
+    | Line  | Use `//` comments                      |
+    | All   | Use both block and line comments       |
+
+-   TypeDoc will now warn if part of a comment will be overwritten due to use of `@inheritDoc` instead of silently dropping part of the comment.
+-   Added support for inline `@inheritDoc` tags, #1480.
+-   It is now possible to link directly to a specific overload, #1326.
+-   The JSON output will now include URLs to the file on the remote repository if possible.
+-   Added a new `visibilityFilters` option which controls the available filters on a page.
+-   TypeDoc will now try to place block elements on a new line in HTML output, resulting in less overwhelming diffs when rebuilding docs, #1923.
+-   Added `blockTags`, `inlineTags`, `modifierTags` to control which tags TypeDoc will allow when parsing comments.
+    If a tag not in in one of these options is encountered, TypeDoc will produce a warning and use context clues to determine how to parse the tag.
+
+### Bug Fixes
+
+-   Fixed off by one error in warnings for types referenced but not included in the documentation.
+-   TypeDoc will no longer render a `Type Parameters` heading if there are no type parameters in some cases.
+-   Improved source location detection for constructors.
+-   Improved comment discovery on destructured exported functions, #1770.
+-   Links which refer to members within a reference reflection will now correctly resolve to the referenced reflection's member, #1770.
+-   Correctly detect optional parameters in JavaScript projects using JSDoc, #1804.
+-   Fixed identical anchor links for reflections with the same name, #1845.
+-   TypeDoc will now automatically inherit documentation from classes `implements` by other interfaces/classes.
+-   Fixed `@inheritDoc` on accessors, #1927.
+-   JS exports defined as `exports.foo = ...` will now be converted as variables rather than properties.
+-   `searchCategoryBoosts` are now correctly computed for all categories, #1960.
+-   The `excludeNotDocumented` option will no longer hide a module if it has a documentation comment, #1948.
+-   Prevent `--excludeNotDocumented` from hiding properties of type literals (`a` in `function fn(p: { a: string })`), #1752.
+-   Allow `cts` and `mts` extensions in packages resolution mode, #1952.
+-   Corrected schema generation for https://typedoc.org/schema.json
+
+### Thanks!
+
+-   @aqumus
+-   @fb55
+-   @futurGH
+-   @Shane4368
+-   @shmax
+
 ## v0.22.18 (2022-06-25)
 
 ### Features
@@ -864,7 +950,7 @@
 -   Missing comments on variable functions, closes #1421
 -   Resolve type parameters in concrete subclasses
 -   Use entryPoints to search for readme
--   Only create extra programs when dealing with solution style tsconfigs
+-   Only create extra programs when dealing with solution style tsconfig.json files
 -   A typo in description of DefaultTheme.getMapping (#1416)
 -   Correct handling of arrays in generic constraints, closes #1408
 -   Type converters threw on older TS versions

diff --git a/README.md b/README.md
@@ -79,23 +79,17 @@ For a complete list of the command line arguments run `typedoc --help` or visit
     Specifies the location the documentation should be written to. Defaults to `./docs`
 -   `--json <path/to/output.json>`<br>
     Specifies the location and file name a json file describing the project is
-    written to. When specified no documentation will be generated.
+    written to. When specified no documentation will be generated unless `--out` is also
+    specified.
 -   `--options`<br>
     Specify a json option file that should be loaded. If not specified TypeDoc
     will look for 'typedoc.json' in the current directory.
 -   `--tsconfig <path/to/tsconfig.json>`<br>
     Specify a typescript config file that should be loaded. If not
     specified TypeDoc will look for 'tsconfig.json' in the current directory.
-
-#### Source file handling
-
 -   `--exclude <pattern>`<br>
     Exclude files by the given pattern when a path is provided as source.
     Supports standard minimatch patterns.
--   `--excludeNotDocumented`<br>
-    Only document items which have a doc comment. This option is useful, if you
-    want to document only small part of your symbols and do not show the
-    remaining ones in the documentation.
 
 #### Theming
 
@@ -109,8 +103,6 @@ For a complete list of the command line arguments run `typedoc --help` or visit
 
 #### Miscellaneous
 
--   `--listInvalidSymbolLinks`<br>
-    Display the list of links that don't point to actual code symbols.
 -   `--version`<br>
     Display the version number of TypeDoc.
 -   `--help`<br>
@@ -123,9 +115,3 @@ You can find TypeDoc on GitHub; feel free to open an issue or create a pull requ
 https://github.com/TypeStrong/typedoc
 
 For more information, read the [contribution guide](https://github.com/TypeStrong/typedoc/blob/master/.github/CONTRIBUTING.md).
-
-## License
-
-Copyright (c) 2015 [Sebastian Lenz](https://typedoc.org).<br>
-Copyright (c) 2016-2021 [TypeDoc Contributors](https://github.com/TypeStrong/typedoc/graphs/contributors).<br>
-Licensed under the Apache License 2.0.
diff --git a/example/typedoc.json b/example/typedoc.json
@@ -9,6 +9,6 @@
         "Model": 1.2
     },
     "searchGroupBoosts": {
-        "Class": 1.5
+        "Classes": 1.5
     }
 }
diff --git a/internal-docs/custom-themes.md b/internal-docs/custom-themes.md
@@ -26,9 +26,9 @@ class MyThemeContext extends DefaultThemeRenderContext {
     // to destructure the context object to only grab what they care about.
     override analytics = () => {
         // Reusing existing option rather than declaring our own for brevity
-        if (!this.options.isSet("gaSite")) return;
+        if (!this.options.isSet("gaId")) return;
 
-        const site = this.options.getValue("gaSite");
+        const site = this.options.getValue("gaId");
 
         const script = `
 (function() {