Merge remote-tracking branch 'origin/master' into beta

.editorconfig

@@ -12,3 +12,6 @@ trim_trailing_whitespace = true
 
 [package.json]
 indent_size = 2
+
+[src/test/converter2/issues/gh2631/crlf.md]
+end_of_line = crlf

.gitattributes

@@ -1,5 +1,6 @@
 # Disable core.autocrlf's line ending conversion behavior to prevent test failures on Windows
 * text=auto eol=lf
+src/test/converter2/issues/gh2631/crlf.md text=auto eol=crlf
 
 *.png binary
 *.psd binary

.github/workflows/ci.yml

@@ -5,7 +5,7 @@ jobs:
         runs-on: ubuntu-latest
         strategy:
             matrix:
-                node: ["18", "20", "22"]
+                node: ["18", "20", "22.4.1"]
         name: Node ${{ matrix.node }}
         steps:
             - name: Checkout repository
@@ -35,7 +35,7 @@ jobs:
             - name: Set up Node
               uses: actions/setup-node@v4
               with:
-                  node-version: 22
+                  node-version: 22.4.1
             - name: Install
               run: npm ci
             - name: Build

CHANGELOG.md

@@ -21,6 +21,42 @@ TODO:
 
 # Unreleased
 
+## v0.26.5 (2024-07-21)
+
+### Features
+
+-   TypeDoc now exposes array option defaults under `OptionDefaults`, #2640.
+
+### Bug Fixes
+
+-   Constructor parameters which share a name with a property on a parent class will no longer inherit the comment on the parent class, #2636.
+-   Packages mode will now attempt to use the comment declared in the comment class for inherited members, #2622.
+-   TypeDoc no longer crashes when `@document` includes an empty file, #2638.
+-   API: Event listeners added later with the same priority will be called later, #2643.
+
+### Thanks!
+
+-   @bladerunner2020
+
+## v0.26.4 (2024-07-10)
+
+### Bug Fixes
+
+-   The page navigation sidebar no longer incorrectly includes re-exports if the same member is exported with multiple names #2625.
+-   Page navigation now ensures the current page is visible when the page is first loaded, #2626.
+-   If a relative linked image is referenced multiple times, TypeDoc will no longer sometimes produce invalid links to the image #2627.
+-   `@link` tags will now be validated in referenced markdown documents, #2629.
+-   `@link` tags are now resolved in project documents, #2629.
+-   HTML/JSON output generated by TypeDoc now contains a trailing newline, #2632.
+-   TypeDoc now correctly handles markdown documents with CRLF line endings, #2628.
+-   `@hidden` is now properly applied when placed in a function implementation comment, #2634.
+-   Comments on re-exports are now rendered.
+
+### Thanks!
+
+-   @bukowa
+-   @garrett-hopper
+
 ## v0.26.3 (2024-06-28)
 
 ### Features

internal-docs/plugins.md

@@ -2,13 +2,14 @@
 title: Plugins
 children:
     - ./components-and-events.md
+    - ./third-party-symbols.md
 ---
 
 # Writing a TypeDoc Plugin
 
 TypeDoc supports plugins which can modify how projects are converted, how converted symbols
 are organized, and how they are displayed, among other things. Plugins are Node modules which
-export a single `load` function that will be called by TypeDoc with the [Application] instance
+export a single `load` function that will be called by TypeDoc with the {@link Application} instance
 which they are to be attached to. Plugins should assume that they may be loaded multiple times
 for different applications, and that a single load of an application class may be used to convert
 multiple projects.
@@ -26,8 +27,8 @@ export function load(app) {
 ```
 
 Plugins affect TypeDoc's execution by attaching event listeners to one or many events that will be
-fired during conversion and rendering. Events are available on the [Application], [Converter],
-[Renderer], and [Serializer]/[Deserializer] classes. There are static `EVENT_*` properties on those
+fired during conversion and rendering. Events are available on the {@link Application}, {@link Converter},
+{@link Renderer}, and {@link Serializer}/{@link Deserializer} classes. There are static `EVENT_*` properties on those
 classes which describe the available events.
 
 The best way to learn what's available to plugins is to browse the docs, or look at the source code
@@ -45,10 +46,5 @@ TypeDoc works. The [development page](https://typedoc.org/guides/development/) o
 If you have specific questions regarding plugin development, please open an issue or ask in the
 [TypeScript Discord] #typedoc channel.
 
-[Application]: https://typedoc.org/api/classes/Application.html
-[Converter]: https://typedoc.org/api/classes/Converter.html
-[Renderer]: https://typedoc.org/api/classes/Renderer.html
-[Serializer]: https://typedoc.org/api/classes/Serializer.html
-[Deserializer]: https://typedoc.org/api/classes/Deserializer.html
 [typedoc-plugin-mdn-links]: https://github.com/Gerrit0/typedoc-plugin-mdn-links/blob/main/src/index.ts
 [TypeScript Discord]: https://discord.gg/typescript

internal-docs/third-party-symbols.md

@@ -1,3 +1,7 @@
+---
+title: Third Party Symbols
+---
+
 # Third Party Symbols
 
 TypeDoc 0.22 added support for linking to third party sites by associating a symbol name with npm packages.
@@ -47,7 +51,8 @@ A wildcard can be used to provide a fallback link to any unmapped type.
 }
 ```
 
-Plugins can add support for linking to third party sites by calling [`app.converter.addUnknownSymbolResolver`][addUnknownSymbolResolver].
+Plugins can add support for linking to third party sites by calling
+{@link Converter.addUnknownSymbolResolver | `app.converter.addUnknownSymbolResolver`}
 
 If the given symbol is unknown, or does not appear in the documentation site, the resolver may return `undefined`
 and no link will be rendered unless provided by another resolver.
@@ -150,12 +155,10 @@ export function load(app: Application) {
 ```
 
 The unknown symbol resolver will also be passed the reflection containing the link
-and, if the link was defined by the user, the [CommentDisplayPart] which was parsed into the [DeclarationReference] provided as the first argument.
+and, if the link was defined by the user, the {@link Models.CommentDisplayPart} which was parsed into the
+{@link DeclarationReference} provided as the first argument.
 
-If `--useTsLinkResolution` is on (the default), it may also be passed a [ReflectionSymbolId] referencing the symbol that TypeScript resolves the link to.
+If `--useTsLinkResolution` is on (the default), it may also be passed a {@link Models.ReflectionSymbolId}
+referencing the symbol that TypeScript resolves the link to.
 
 [externalSymbolLinkMappings]: https://typedoc.org/options/comments/#externalsymbollinkmappings
-[CommentDisplayPart]: https://typedoc.org/api/types/CommentDisplayPart.html
-[DeclarationReference]: https://typedoc.org/api/interfaces/DeclarationReference.html
-[ReflectionSymbolId]: https://typedoc.org/api/classes/Application.html
-[addUnknownSymbolResolver]: https://typedoc.org/api/classes/Converter.html#addUnknownSymbolResolver

package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.26.3",
+  "version": "0.26.5",
   "homepage": "https://typedoc.org",
   "type": "module",
   "exports": {

src/index.ts

@@ -60,6 +60,7 @@ export {
     LogLevel,
     Logger,
     Options,
+    OptionDefaults,
     PackageJsonReader,
     ParameterHint,
     ParameterType,

src/lib/application.ts

@@ -620,7 +620,7 @@ export class Application extends AbstractComponent<
         const ser = this.serializer.projectToObject(project, process.cwd());
 
         const space = this.options.getValue("pretty") ? "\t" : "";
-        await writeFile(out, JSON.stringify(ser, null, space));
+        await writeFile(out, JSON.stringify(ser, null, space) + "\n");
         this.logger.info(this.i18n.json_written_to_0(nicePath(out)));
         this.logger.verbose(`JSON rendering took ${Date.now() - start}ms`);
     }

src/lib/converter/comments/discovery.ts

@@ -412,6 +412,12 @@ function declarationToCommentNodeIgnoringParents(
     // ts.SourceFile is a counterexample
     if (!node.parent) return node;
 
+    // function foo(x: number)
+    //              ^^^^^^^^^
+    if (node.kind === ts.SyntaxKind.Parameter) {
+        return node;
+    }
+
     // const abc = 123
     //       ^^^
     if (node.parent.kind === ts.SyntaxKind.VariableDeclarationList) {

src/lib/converter/comments/parser.ts

@@ -202,8 +202,8 @@ export function parseCommentString(
 
     // Check for frontmatter
     let frontmatterData: Record<string, unknown> = {};
-    const firstBlock = content[0];
-    if (firstBlock.text.startsWith("---\n")) {
+    const firstBlock = content.at(0);
+    if (firstBlock?.text.startsWith("---\n")) {
         const end = firstBlock.text.indexOf("\n---\n");
         if (end !== -1) {
             const yamlText = firstBlock.text.slice("---\n".length, end);

src/lib/converter/plugins/CommentPlugin.ts

@@ -633,14 +633,12 @@ export class CommentPlugin extends ConverterComponent {
             (comment.hasModifier("@internal") && this.excludeInternal);
 
         if (
-            isHidden &&
+            !isHidden &&
             reflection.kindOf(ReflectionKind.ContainsCallSignatures)
         ) {
             return (reflection as DeclarationReflection)
                 .getNonIndexSignatures()
-                .every((sig) => {
-                    return !sig.comment || this.isHidden(sig);
-                });
+                .every((sig) => this.isHidden(sig));
         }
 
         return isHidden;