Write some more documentation

CHANGELOG.md

@@ -26,10 +26,6 @@ title: Changelog
 
 TODO:
 
--   Write docs for `@expand`
--   Docs for `@summary`
--   Write docs for `@import`
--   Write docs for `@class`
 -   Write docs for `@include` and `@includeCode`
 -   https://github.com/ebullient/markdown-it-obsidian-callouts plugin
 -   Validate anchors within relative linked paths?

site/tags.md

@@ -3,25 +3,29 @@ title: Tags
 children:
     - tags/alpha.md
     - tags/beta.md
-    - tags/categoryDescription.md
     - tags/category.md
+    - tags/categoryDescription.md
+    - tags/class.md
     - tags/defaultValue.md
     - tags/deprecated.md
     - tags/document.md
     - tags/enum.md
     - tags/event.md
     - tags/eventProperty.md
     - tags/example.md
+    - tags/expand.md
     - tags/experimental.md
-    - tags/groupDescription.md
     - tags/group.md
+    - tags/groupDescription.md
     - tags/hidden.md
     - tags/hideconstructor.md
     - tags/ignore.md
+    - tags/import.md
     - tags/inheritDoc.md
     - tags/interface.md
     - tags/internal.md
     - tags/label.md
+    - tags/license.md
     - tags/link.md
     - tags/module.md
     - tags/namespace.md
@@ -40,6 +44,7 @@ children:
     - tags/satisfies.md
     - tags/sealed.md
     - tags/see.md
+    - tags/summary.md
     - tags/template.md
     - tags/throws.md
     - tags/typeParam.md

site/tags/class.md

@@ -0,0 +1,28 @@
+---
+title: "@class"
+---
+
+# @class
+
+**Tag Kind:** [Modifier](../tags.md#Modifier-Tags)
+
+If present on a variable, will cause it to be converted as a class. This
+will result in all "dynamic" properties being expanded to real properties.
+
+TypeDoc will also ignore types/interfaces declared with the same name as
+variables annotated with `@class`.
+
+## Example
+
+```ts
+/** @class */
+export function ClassLike() {
+    if (new.target) {
+        //
+    }
+}
+```
+
+## See Also
+
+-   The [`@interface`](interface.md) tag

site/tags/expand.md

@@ -0,0 +1,52 @@
+---
+title: "@expand"
+---
+
+# @expand
+
+**Tag Kind:** [Modifier](../tags.md#Modifier-Tags)
+
+The `@expand` tag may be placed on type aliases and interfaces. When a type is
+annotated with `@expand`, TypeDoc will inline the type declaration of that type
+wherever it is referenced and TypeDoc has a place to include it.
+
+> Note: Use of this tag can _significantly_ increase the size of your generated
+> 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
+
+This is particularly useful for React components, where the documentation for
+props is useful when viewing the component function. The `Hello` component below
+will take the description "Props docs" from `HelloProps` for its `props`
+parameter and also render details about the referenced type.
+
+The `Hello2` component behaves similarly, but provides a more relevant
+description for the overall type, which prevents the summary provided in
+`HelloProps` from being used.
+
+```tsx
+/**
+ * Props docs
+ * @expand
+ */
+export type HelloProps = {
+    /** Name property docs */
+    name: string;
+};
+
+/**
+ * Hello
+ */
+export function Hello(props: HelloProps) {
+    return {};
+}
+
+/**
+ * Hello2
+ * @param props Props docs (used instead of `@expand` description)
+ */
+export function Hello2(props: HelloProps) {
+    return {};
+}
+```

site/tags/import.md

@@ -0,0 +1,29 @@
+---
+title: "@import"
+---
+
+# @import
+
+**Tag Kind:** [Block](../tags.md#Block-Tags)
+
+The `@import` tag is recognized for use in JavaScript projects which can use it
+to declare type imports since TypeScript 5.5. Any comment containing `@import`
+will be ignored by TypeDoc.
+
+## Example
+
+Taken from the [TypeScript 5.5 release notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html#the-jsdoc-import-tag)
+
+```js
+/** @import { SomeType } from "some-module" */
+/**
+ * @param {SomeType} myValue
+ */
+function doSomething(myValue) {
+    // ...
+}
+```
+
+## See Also
+
+-   The [TypeScript 5.5 release notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html#the-jsdoc-import-tag)

site/tags/license.md

@@ -0,0 +1,18 @@
+---
+title: "@license"
+---
+
+# @license
+
+**Tag Kind:** [Block](../tags.md#Block-Tags)
+
+The `@license` tag is recognized to declare a license comment which should not
+be included in the documentation. Any comments containing `@license` will be
+excluded from the generated documentation.
+
+## Example
+
+```js
+/** @license Apache-2.0 */
+export const api = {...} // not documented
+```

site/tags/summary.md

@@ -0,0 +1,29 @@
+---
+title: "@summary"
+---
+
+# @summary
+
+**Tag Kind:** [Block](../tags.md#Block-Tags) <br>
+**JSDoc Reference:** [@summary](https://jsdoc.app/tags-summary)
+
+When rendering modules, TypeDoc uses the first paragraph of comment's summary
+text (text before any [block tags](../tags.md#Block-Tags)) as the member's
+summary on the modules page. As this may not always be suitable for standalone
+display, if a `@summary` tag is present TypeDoc will render that block instead.
+
+## Example
+
+```ts
+/**
+ * This description will be used on the **module** page
+ */
+export function runProcess(): void;
+
+/**
+ * This description will be used on the **member** page
+ * @summary
+ * This description will be used on the **module** page
+ */
+export function forkProcess(): void;
+```

src/lib/models/reflections/abstract.ts

@@ -16,6 +16,7 @@ import type {
     Internationalization,
     TranslatedString,
 } from "../../internationalization/index.js";
+import type { ParameterReflection } from "./parameter.js";
 
 /**
  * Current reflection id.
@@ -478,6 +479,9 @@ export abstract class Reflection {
     isDeclaration(): this is DeclarationReflection {
         return false;
     }
+    isParameter(): this is ParameterReflection {
+        return false;
+    }
     isDocument(): this is DocumentReflection {
         return false;
     }

src/lib/models/reflections/parameter.ts

@@ -37,6 +37,10 @@ export class ParameterReflection extends Reflection {
         }
     }
 
+    override isParameter(): this is ParameterReflection {
+        return true;
+    }
+
     /**
      * Return a string representation of this reflection.
      */

src/lib/output/themes/default/partials/comment.tsx

@@ -1,6 +1,6 @@
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext.js";
 import { JSX, Raw } from "../../../../utils/index.js";
-import { type CommentDisplayPart, type Reflection, ReflectionKind } from "../../../../models/index.js";
+import { Comment, type CommentDisplayPart, type Reflection, ReflectionKind } from "../../../../models/index.js";
 import { anchorIcon } from "./anchor-icon.js";
 import { join } from "../../lib.js";
 
@@ -25,16 +25,29 @@ export function commentShortSummary({ markdown }: DefaultThemeRenderContext, pro
     );
 }
 
-export function commentSummary({ markdown }: DefaultThemeRenderContext, props: Reflection) {
-    if (!props.comment?.summary.some((part) => part.text)) return;
-
+function renderSummary(context: DefaultThemeRenderContext, comment: Comment) {
     return (
         <div class="tsd-comment tsd-typography">
-            <Raw html={markdown(props.comment.summary)} />
+            <Raw html={context.markdown(comment.summary)} />
         </div>
     );
 }
 
+export function commentSummary(context: DefaultThemeRenderContext, props: Reflection) {
+    if (props.comment?.summary.some((part) => part.text)) {
+        return renderSummary(context, props.comment);
+    }
+
+    const target =
+        (props.isDeclaration() || props.isParameter()) && props.type?.type === "reference"
+            ? props.type.reflection
+            : undefined;
+
+    if (target?.comment?.hasModifier("@expand") && target?.comment?.summary.some((part) => part.text)) {
+        return renderSummary(context, target.comment);
+    }
+}
+
 export function commentTags(context: DefaultThemeRenderContext, props: Reflection) {
     if (!props.comment) return;