Skip to content

Commit

Permalink
Improve support for modifier tags
Browse files Browse the repository at this point in the history 
Resolves #1381
  • Loading branch information
@Gerrit0
Gerrit0 committed Feb 18, 2022
1 parent 357c9b7 commit d053b92
Show file tree
Hide file tree
Showing 13 changed files with 63 additions and 24 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Expand Up @@ -22,6 +22,7 @@
- TypeDoc will now search for `typedoc.js(on)` in the `.config` folder in the current working directory.
- 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.

### Bug Fixes

Expand Down
3 changes: 3 additions & 0 deletions src/lib/converter/context.ts
View file
Expand Up @@ -186,6 +186,9 @@ export class Context {
"@internal",
"@readonly",
"@packageDocumentation",
"@deprecated",
"@alpha",
"@beta",
// TypeDoc specific tags
"@hidden",
"@ignore",
Expand Down
2 changes: 2 additions & 0 deletions src/lib/output/themes/default/partials/comment.tsx
View file
Expand Up @@ -50,6 +50,8 @@ function displayPartsToMarkdown(parts: CommentDisplayPart[], urlTo: DefaultTheme
export function comment({ markdown, urlTo }: DefaultThemeRenderContext, props: Reflection) {
if (!props.comment?.hasVisibleComponent()) return;

// Note: Comment modifiers are handled in `renderFlags`

return (
<div class="tsd-comment tsd-typography">
<Raw html={markdown(displayPartsToMarkdown(props.comment.summary, urlTo))} />
Expand Down
11 changes: 8 additions & 3 deletions src/lib/output/themes/default/partials/index.tsx
View file
@@ -1,4 +1,4 @@
import { wbr } from "../../lib";
import { classNames, wbr } from "../../lib";
import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
import { JSX } from "../../../../utils";
import type { ContainerReflection, ReflectionCategory } from "../../../../models";
Expand All @@ -9,7 +9,7 @@ function renderCategory({ urlTo }: DefaultThemeRenderContext, item: ReflectionCa
<h3>{prependName ? `${prependName} ${item.title}` : item.title}</h3>
<ul class="tsd-index-list">
{item.children.map((item) => (
<li class={item.cssClasses}>
<li class={classNames({ deprecated: item.comment?.hasModifier("@deprecated") }, item.cssClasses)}>
<a href={urlTo(item)} class="tsd-kind-icon">
{item.name ? wbr(item.name) : <em>{wbr(item.kindString!)}</em>}
</a>
Expand Down Expand Up @@ -47,7 +47,12 @@ export function index(context: DefaultThemeRenderContext, props: ContainerReflec
<h3>{item.title}</h3>
<ul class="tsd-index-list">
{item.children.map((item) => (
<li class={item.cssClasses}>
<li
class={classNames(
{ deprecated: item.comment?.hasModifier("@deprecated") },
item.cssClasses
)}
>
<a href={context.urlTo(item)} class="tsd-kind-icon">
{item.name ? wbr(item.name) : <em>{wbr(item.kindString!)}</em>}
</a>
Expand Down
2 changes: 1 addition & 1 deletion src/lib/output/themes/default/partials/member.signature.body.tsx
View file
Expand Up @@ -25,7 +25,7 @@ export const memberSignatureBody = (
{props.parameters.map((item) => (
<li>
<h5>
{renderFlags(item.flags)}
{renderFlags(item.flags, item.comment)}
{!!item.flags.isRest && <span class="tsd-signature-symbol">...</span>}
{item.name}
{": "}
Expand Down
8 changes: 5 additions & 3 deletions src/lib/output/themes/default/partials/member.tsx
View file
@@ -1,4 +1,4 @@
import { renderFlags, wbr } from "../../lib";
import { classNames, renderFlags, wbr } from "../../lib";
import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
import { JSX } from "../../../../utils";
import { DeclarationReflection, ReferenceReflection } from "../../../../models";
Expand All @@ -9,8 +9,10 @@ export const member = (context: DefaultThemeRenderContext, props: DeclarationRef
<a id={props.anchor} class="tsd-anchor"></a>
{!!props.name && (
<h3 class="tsd-anchor-link">
{renderFlags(props.flags)}
{wbr(props.name)}
{renderFlags(props.flags, props.comment)}
<span class={classNames({ deprecated: props.comment?.hasModifier("@deprecated") })}>
{wbr(props.name)}
</span>
{anchorIcon(props.anchor)}
</h3>
)}
Expand Down
19 changes: 16 additions & 3 deletions src/lib/output/themes/default/partials/navigation.tsx
View file
Expand Up @@ -64,7 +64,7 @@ function primaryNavigation(context: DefaultThemeRenderContext, props: PageEvent<
}

return (
<li class={classNames({ current }) + " " + mod.cssClasses}>
<li class={classNames({ current, deprecated: mod.comment?.hasModifier("@deprecated") }, mod.cssClasses)}>
<a href={context.urlTo(mod)}>{wbr(mod.name)}</a>
{childNav}
</li>
Expand All @@ -86,7 +86,12 @@ function secondaryNavigation(context: DefaultThemeRenderContext, props: PageEven
.filter((child) => !child.kindOf(ReflectionKind.SomeModule))
.map((child) => {
return (
<li class={child.cssClasses}>
<li
class={classNames(
{ deprecated: child.comment?.hasModifier("@deprecated") },
child.cssClasses
)}
>
<a href={context.urlTo(child)} class="tsd-kind-icon">
{wbr(child.name)}
</a>
Expand All @@ -103,7 +108,15 @@ function secondaryNavigation(context: DefaultThemeRenderContext, props: PageEven
return (
<nav class="tsd-navigation secondary menu-sticky">
<ul>
<li class={"current " + props.model.cssClasses}>
<li
class={classNames(
{
deprecated: props.model.comment?.hasModifier("@deprecated"),
current: true,
},
props.model.cssClasses
)}
>
<a href={context.urlTo(props.model)} class="tsd-kind-icon">
{wbr(props.model.name)}
</a>
Expand Down
6 changes: 3 additions & 3 deletions src/lib/output/themes/default/partials/parameter.tsx
View file
Expand Up @@ -63,7 +63,7 @@ export const parameter = (context: DefaultThemeRenderContext, props: Declaration
{/* standard type */}
<li class="tsd-parameter">
<h5>
{renderFlags(item.flags)}
{renderFlags(item.flags, item.comment)}
{!!item.flags.isRest && <span class="tsd-signature-symbol">...</span>}
{wbr(item.name)}
<span class="tsd-signature-symbol">
Expand All @@ -85,7 +85,7 @@ export const parameter = (context: DefaultThemeRenderContext, props: Declaration
{/* getter */}
<li class="tsd-parameter">
<h5>
{renderFlags(item.getSignature.flags)}
{renderFlags(item.getSignature.flags, item.getSignature.comment)}
<span class="tsd-signature-symbol">get </span>
{wbr(item.name)}
<span class="tsd-signature-symbol">(): </span>
Expand All @@ -101,7 +101,7 @@ export const parameter = (context: DefaultThemeRenderContext, props: Declaration
{/* setter */}
<li class="tsd-parameter">
<h5>
{renderFlags(item.setSignature.flags)}
{renderFlags(item.setSignature.flags, item.setSignature.comment)}
<span class="tsd-signature-symbol">set </span>
{wbr(item.name)}
<span class="tsd-signature-symbol">(</span>
Expand Down
20 changes: 15 additions & 5 deletions src/lib/output/themes/lib.tsx
View file
@@ -1,4 +1,5 @@
import {
Comment,
DeclarationReflection,
Reflection,
ReflectionFlags,
Expand Down Expand Up @@ -51,10 +52,15 @@ export function join<T>(joiner: JSX.Children, list: readonly T[], cb: (x: T) =>
return <>{result}</>;
}

export function renderFlags(flags: ReflectionFlags) {
export function renderFlags(flags: ReflectionFlags, comment: Comment | undefined) {
const allFlags = [...flags];
if (comment) {
allFlags.push(...Array.from(comment.modifierTags, (tag) => tag.replace(/@([a-z])/, (x) => x[1].toUpperCase())));
}

return (
<>
{flags.map((item) => (
{allFlags.map((item) => (
<>
<span class={"tsd-flag ts-flag" + item}>{item}</span>{" "}
</>
Expand All @@ -63,11 +69,15 @@ export function renderFlags(flags: ReflectionFlags) {
);
}

export function classNames(names: Record<string, boolean | null | undefined>) {
return Object.entries(names)
export function classNames(names: Record<string, boolean | null | undefined>, extraCss?: string) {
const css = Object.entries(names)
.filter(([, include]) => include)
.map(([key]) => key)
.join(" ");
.concat(extraCss || "")
.join(" ")
.trim()
.replace(/\s+/g, " ");
return css.length ? css : undefined;
}

export function hasTypeParameters(
Expand Down
2 changes: 1 addition & 1 deletion src/test/converter/class/class.ts
View file
Expand Up @@ -3,7 +3,7 @@
*
* TestClass comment text.
*
* @see [[TestClass]] @ fixtures
* @see {@link TestClass} @ fixtures
*/
export class TestClass {
/**
Expand Down
2 changes: 1 addition & 1 deletion src/test/converter/class/type-operator.ts
View file
Expand Up @@ -3,7 +3,7 @@
*
* TestClass comment text.
*
* @see [[TestClass]] @ fixtures
* @see {@link TestClass} @ fixtures
*/
export class TestClass {
a: string;
Expand Down
7 changes: 3 additions & 4 deletions src/test/converter/comment/specs.json
View file
Expand Up @@ -29,10 +29,6 @@
}
],
"blockTags": [
{
"tag": "@deprecated",
"content": []
},
{
"tag": "@todo",
"content": [
Expand All @@ -42,6 +38,9 @@
}
]
}
],
"modifierTags": [
"@deprecated"
]
},
"children": [
Expand Down
4 changes: 4 additions & 0 deletions static/style.css
View file
Expand Up @@ -1402,3 +1402,7 @@ img {
.tsd-anchor-link:hover > .tsd-anchor-icon svg {
visibility: visible;
}

.deprecated {
text-decoration: line-through;
}

0 comments on commit d053b92

Please sign in to comment.