From 7a48a172fffb75a0b5adc1fdc9fc224b05ce45c4 Mon Sep 17 00:00:00 2001
From: Gerrit Birkeland <gerrit@gerritbirkeland.com>
Date: Sun, 26 Feb 2023 14:00:39 -0700
Subject: [PATCH] Document additional changes

---
 CHANGELOG.md                         |  7 ++++
 internal-docs/third-party-symbols.md | 55 ++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f9853d605..01c061a54 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,12 +1,19 @@
 # Unreleased
 
+### Features
+
+-   Added `Application.EVENT_VALIDATE_PROJECT` event for plugins which implement custom validation, #2183.
+-   Plugins may now return an object from external symbol resolvers, #2066.
+
 ### Bug Fixes
 
 -   Fix crash when converting `export default undefined`, #2175
 
 ### Thanks!
 
+-   @captain-torch
 -   @loopingz
+-   @RebeccaStevens
 
 ## v0.23.25 (2023-02-11)
 
diff --git a/internal-docs/third-party-symbols.md b/internal-docs/third-party-symbols.md
index 58b0fe354..bbe2fce6a 100644
--- a/internal-docs/third-party-symbols.md
+++ b/internal-docs/third-party-symbols.md
@@ -96,3 +96,58 @@ export function load(app: Application) {
     });
 }
 ```
+
+Since TypeDoc 0.23.26, plugins may also return return an object for more control
+over the displayed link. The returned `caption` will be used if the user does not
+specify the link text.
+
+```ts
+import { Application, type DeclarationReference } from "typedoc";
+
+const documentedExports = [
+    "chunk",
+    "compact",
+    "concat",
+    "difference",
+    "differenceBy",
+    "differenceWith",
+];
+
+export function load(app: Application) {
+    app.converter.addUnknownSymbolResolver((ref: DeclarationReference) => {
+        if (
+            // TS defined symbols
+            ref.moduleSource !== "@types/lodash" &&
+            // User {@link} tags
+            ref.moduleSource !== "lodash"
+        ) {
+            return;
+        }
+
+        // If someone did {@link lodash!}, link them directly to the home page.
+        if (!ref.symbolReference) {
+            return "https://lodash.com/";
+        }
+
+        if (!ref.symbolReference.path) {
+            // Someone included a meaning, but not a path.
+            // https://typedoc.org/guides/declaration-references/#meaning
+            return;
+        }
+
+        if (ref.symbolReference.path.length === 1) {
+            const name = ref.symbolReference.path[0].path;
+            if (documentedExports.includes(name)) {
+                return {
+                    target: `https://lodash.com/docs/4.17.15#${name}`,
+                    caption: name,
+                };
+            }
+        }
+    });
+}
+```
+
+The unknown symbol resolver will also be passed the reflection containing the link
+and, if the link was defined by the user, the [CommentDisplayPart](https://typedoc.org/api/types/CommentDisplayPart.html)
+which was parsed into the `DeclarationReference` provided as the first argument.