Add support for @preventExpand and @expandType

Resolves #2862

Author: Gerrit0

.vscode/settings.json

@@ -42,8 +42,12 @@
 
     "eslint.workingDirectories": [".", "./example"],
     "mochaExplorer.configFile": ".config/mocha.test-explorer.json",
-    // Ignore usernames in the Thanks sections of the changelog
-    "cSpell.ignoreRegExpList": ["/^- +@[A-Z0-9_-]+/igm"],
+    "cSpell.ignoreRegExpList": [
+        // Ignore usernames in the Thanks sections of the changelog
+        "/^- +@[A-Z0-9_-]+/igm",
+        // Ignore combined hashes in JSON output for rendering testing
+        "/#[a-z0-9_]+\"/"
+    ],
     "cSpell.words": [
         "callouts",
         "cname",

CHANGELOG.md

@@ -35,6 +35,9 @@ title: Changelog
 - `ReflectionKind.singularString` and `ReflectionKind.pluralString` now returns translated strings.
   The methods on `Internationalization` to do this previously have been removed.
 - The HTML output structure for the search box has changed to support the new modal.
+- `DefaultThemeRenderContext`'s `typeDeclaration` and `typeDetailsIfUseful`
+  methods now require both a reflection and a type in order to support
+  `@expandType`
 
 ### Features
 
@@ -51,6 +54,7 @@ title: Changelog
 - Introduced `@function` tag to force TypeDoc to convert variable declarations with a type annotation as functions, #2881.
 - Exposed a `TypeDoc` global object in the HTML theme which can be used to prevent TypeDoc from using `localStorage`, #2872.
 - Introduced `@preventInline` and `@inlineType` tags for further control extending the `@inline` tag, #2862.
+- Introduced `@preventExpand` and `@expandType` tags for further control extending the `@expand` tag, #2862.
 - API: Introduced `DefaultThemeRenderContext.reflectionIcon` for more granular control over displayed reflection icons.
 
 ### Bug Fixes

site/tags.md

@@ -114,13 +114,15 @@ examples for how to use the export ([`@example`](./tags/example.md)).
 - [`@deprecated`](./tags/deprecated.md)
 - [`@document`](./tags/document.md)
 - [`@example`](./tags/example.md)
+- [`@expandType`](./tags/expand.md#expandtype)
 - [`@group`, `@groupDescription`, `@showGroups`, `@hideGroups`](./tags/group.md)
 - [`@import`](./tags/import.md)
 - [`@inlineType`](./tags/inline.md#inlinetype)
 - [`@license`](./tags/license.md)
 - [`@mergeModuleWith`](./tags/mergeModuleWith.md)
 - [`@module`](./tags/module.md)
 - [`@param`](./tags/param.md)
+- [`@preventExpand`](./tags/expand.md#preventexpand)
 - [`@preventInline`](./tags/inline.md#preventinline)
 - [`@privateRemarks`](./tags/privateRemarks.md)
 - [`@property`, `@prop`](./tags/property.md)

site/tags/expand.md

@@ -2,7 +2,12 @@
 title: "@expand"
 ---
 
-# @expand
+# Expand Tags
+
+The `@expand`, `@expandType`, and `@preventExpand` tags can be used to control
+how TypeDoc _displays_ references to type aliases and interfaces.
+
+## @expand
 
 **Tag Kind:** [Modifier](../tags.md#modifier-tags)
 
@@ -15,7 +20,7 @@ wherever it is referenced and TypeDoc has a place to include it.
 > documentation if it is applied to commonly used types as it will result in
 > inlining the comments for those types everywhere they are referenced.
 
-## Example
+### Example
 
 This is particularly useful for React components, where the documentation for
 props is useful when viewing the component function. The `Hello` component below
@@ -52,6 +57,65 @@ export function Hello2(props: HelloProps) {
 }
 ```
 
+## @expandType
+
+**Tag Kind:** [Block](../tags.md#block-tags)
+
+The `@expandType` can be placed on any reflection to tell TypeDoc to expand a type
+reference when rendering it within that reflection. It should specify the type name
+without type arguments.
+
+`@expandType` is inherited, it may be placed on a namespace or module where there are
+multiple references to a type to instruct TypeDoc to expand the type everywhere in that
+module.
+
+### Example
+
+TypeDoc will expand `HelloProps` within `Hello` as if `@expand` had been placed
+on `HelloProps`.
+
+```ts
+export type HelloProps = {
+    /** Name description */
+    name: string;
+};
+
+/**
+ * Hello component
+ * @expandType HelloProps
+ */
+export function Hello(props: HelloProps) {
+    return <span>Hello {props.name}!</span>;
+}
+```
+
+## @preventExpand
+
+**Tag Kind:** [Block](../tags.md#block-tags)
+
+The `@preventExpand` block tag can be used to instruct TypeDoc to not expand a
+tag which has been expanded with `@expand`, `@preventExpand`, or by highlighting
+properties of the reference type with `@param`.
+
+```tsx
+/**
+ * @expand
+ */
+export type HelloProps = {
+    /** Name property docs */
+    name: string;
+};
+
+/**
+ * Hello component - HelloProps will NOT be expanded here
+ * @preventExpand HelloProps
+ */
+export function Hello2(props: HelloProps) {
+    return <span>Hello {props.name}!</span>;
+}
+```
+
 ## See Also
 
-- The [`@inline`](inline.md) tag
+- The [`@inline`](inline.md) tags
+- The [`@param`](param.md) tag

site/tags/inline.md

@@ -98,4 +98,4 @@ export function Hello2(props: HelloProps) {
 
 ## See Also
 
-- The [`@expand`](expand.md) tag
+- The [`@expand`](expand.md) tags

src/lib/output/themes/default/partials/member.declaration.tsx

@@ -43,7 +43,7 @@ export function memberDeclaration(context: DefaultThemeRenderContext, props: Dec
 
             {hasTypeParameters(props) && context.typeParameters(props.typeParameters)}
 
-            {props.type && context.typeDeclaration(props.type)}
+            {props.type && context.typeDeclaration(props, props.type)}
 
             {context.commentTags(props)}
 

src/lib/output/themes/default/partials/member.signature.body.tsx

@@ -38,7 +38,7 @@ export function memberSignatureBody(
                                 </span>
                                 {context.commentSummary(item)}
                                 {context.commentTags(item)}
-                                {context.typeDetailsIfUseful(item.type)}
+                                {context.typeDetailsIfUseful(item, item.type)}
                             </li>
                         ))}
                     </ul>
@@ -50,7 +50,7 @@ export function memberSignatureBody(
                         {i18n.theme_returns()} {context.type(props.type)}
                     </h4>
                     {returnsTag && <JSX.Raw html={context.markdown(returnsTag.content)} />}
-                    {context.typeDetailsIfUseful(props.type)}
+                    {context.typeDetailsIfUseful(props, props.type)}
                 </>
             )}