From f32fa959850eb79271ff0bfa5e0e1788d606af83 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Mon, 18 Jul 2022 12:51:04 -0400 Subject: [PATCH] new: alpha beta experimental modifiers (#53) * new: alpha, beta, and experimental modifiers This adds badges to entities that are marked with stabilitity modifiers. I'm open to suggestions on better ways of rendering this information. * move labels around --- fixtures/monorepo/standard/src/index.ts | 46 +++++++++++++++++-- .../plugin/src/components/CommentBadges.tsx | 40 ++++++++++++++++ packages/plugin/src/components/Member.tsx | 4 +- .../src/components/MemberSignatureBody.tsx | 11 +++-- packages/plugin/src/components/Reflection.tsx | 3 +- packages/plugin/src/components/styles.css | 17 +++++++ 6 files changed, 112 insertions(+), 9 deletions(-) create mode 100644 packages/plugin/src/components/CommentBadges.tsx diff --git a/fixtures/monorepo/standard/src/index.ts b/fixtures/monorepo/standard/src/index.ts index adf40fc..559fd8d 100644 --- a/fixtures/monorepo/standard/src/index.ts +++ b/fixtures/monorepo/standard/src/index.ts @@ -1,10 +1,50 @@ +/** + * a type + * @beta + */ export type Type = 'standard'; +/** + * newy new guy + * @param a a thing + * @param b b thing + * @alpha + */ +export function bizz(a: string, b: string): string; + +/** + * newy new guy + * @param a a thing + * @param b b thing + * @param c c thing + * @beta + */ +export function bizz(a: string, b: string, c: string): string; + /** * a thing for a thing * @param a id * @returns returns the param + * @beta + */ +export function bizz(...args: string[]): string { + return args[0]; +} + +/** + * thing for a thing + * @beta */ -export function bizz(a: string): string { - return a; -} \ No newline at end of file +export interface Foo { + /** + * very experimental + * @alpha + */ + foo: string; + + /** + * very experimental + * @experimental + */ + a: string; +} diff --git a/packages/plugin/src/components/CommentBadges.tsx b/packages/plugin/src/components/CommentBadges.tsx new file mode 100644 index 0000000..0b4e6e6 --- /dev/null +++ b/packages/plugin/src/components/CommentBadges.tsx @@ -0,0 +1,40 @@ +import React from 'react'; +import { JSONOutput } from 'typedoc'; + +function getModifierClassName(tag: string) { + switch (tag) { + case '@beta': + case '@experimental': + return 'warning'; + case '@alpha': + return 'danger'; + default: + return 'info'; + } +} + +export type CommentWithModifiers = Pick & + Required>; + +export function isCommentWithModifiers( + comment?: JSONOutput.Comment, +): comment is CommentWithModifiers { + return !!comment && !!comment.modifierTags && comment.modifierTags.length > 0; +} + +interface CommentBadgesProps { + comment: CommentWithModifiers; +} + +export function CommentBadges({ comment }: CommentBadgesProps) { + const { modifierTags } = comment; + return ( +
+ {modifierTags.map((tag) => ( + + {tag.slice(1)} + + ))} +
+ ); +} diff --git a/packages/plugin/src/components/Member.tsx b/packages/plugin/src/components/Member.tsx index bb63d7e..179a7f1 100644 --- a/packages/plugin/src/components/Member.tsx +++ b/packages/plugin/src/components/Member.tsx @@ -6,6 +6,7 @@ import { useReflection } from '../hooks/useReflection'; import { useReflectionMap } from '../hooks/useReflectionMap'; import { hasOwnDocument } from '../utils/visibility'; import { AnchorLink } from './AnchorLink'; +import { CommentBadges, isCommentWithModifiers } from './CommentBadges'; import { Flags } from './Flags'; import { MemberDeclaration } from './MemberDeclaration'; import { MemberGetterSetter } from './MemberGetterSetter'; @@ -20,7 +21,7 @@ export interface MemberProps { export function Member({ id }: MemberProps) { const reflections = useReflectionMap(); const reflection = useReflection(id)!; - + const { comment } = reflection; let content: React.ReactNode = null; if (reflection.signatures) { @@ -46,6 +47,7 @@ export function Member({ id }: MemberProps) { {reflection.name} + {isCommentWithModifiers(comment) && } {content} diff --git a/packages/plugin/src/components/MemberSignatureBody.tsx b/packages/plugin/src/components/MemberSignatureBody.tsx index 5f7da29..a01a1c8 100644 --- a/packages/plugin/src/components/MemberSignatureBody.tsx +++ b/packages/plugin/src/components/MemberSignatureBody.tsx @@ -4,6 +4,7 @@ import React from 'react'; import type { JSONOutput } from 'typedoc'; import { useMinimalLayout } from '../hooks/useMinimalLayout'; import { Comment, hasComment } from './Comment'; +import { CommentBadges, isCommentWithModifiers } from './CommentBadges'; import { DefaultValue } from './DefaultValue'; import { Flags } from './Flags'; import { hasSources, MemberSources } from './MemberSources'; @@ -34,11 +35,11 @@ export interface MemberSignatureBodyProps { sig: JSONOutput.SignatureReflection; } -function excludeBlockTags(comment?: JSONOutput.Comment): JSONOutput.Comment | undefined { +function excludeBlockTags(comment?: JSONOutput.Comment): JSONOutput.Comment | undefined { if (comment) { const { blockTags, ...rest } = comment; return rest; - } + } return undefined; } @@ -50,8 +51,8 @@ function intoReturnComment(comment?: JSONOutput.Comment): JSONOutput.Comment | u const index = tags.indexOf('@returns'); return { - summary: comment.blockTags[index].content - } + summary: comment.blockTags[index].content, + }; } } @@ -69,6 +70,8 @@ export function MemberSignatureBody({ hideSources, sig }: MemberSignatureBodyPro <> {!hideSources && } + {isCommentWithModifiers(sig.comment) && } + {hasComment(sig.comment) && (showTypes || showParams || showReturn) && ( diff --git a/packages/plugin/src/components/Reflection.tsx b/packages/plugin/src/components/Reflection.tsx index c1c68de..7d7cd26 100644 --- a/packages/plugin/src/components/Reflection.tsx +++ b/packages/plugin/src/components/Reflection.tsx @@ -4,6 +4,7 @@ import React, { useMemo } from 'react'; import type { JSONOutput } from 'typedoc'; import { createHierarchy } from '../utils/hierarchy'; import { Comment, hasComment } from './Comment'; +import { CommentBadges, isCommentWithModifiers } from './CommentBadges'; import { Hierarchy } from './Hierarchy'; import { Icon } from './Icon'; import { Index } from './Index'; @@ -19,13 +20,13 @@ export interface ReflectionProps { | JSONOutput.Reflection | JSONOutput.SignatureReflection; } - // eslint-disable-next-line complexity export function Reflection({ reflection }: ReflectionProps) { const hierarchy = useMemo(() => createHierarchy(reflection), [reflection]); return ( <> + {isCommentWithModifiers(reflection.comment) && } {hasComment(reflection.comment) && } {'typeParameter' in reflection && diff --git a/packages/plugin/src/components/styles.css b/packages/plugin/src/components/styles.css index 005c342..1b15cd0 100644 --- a/packages/plugin/src/components/styles.css +++ b/packages/plugin/src/components/styles.css @@ -204,6 +204,23 @@ html[data-theme='light'] .tsd-panel-content { vertical-align: middle; } +/* MODIFIERS */ + +.badge-group { + font-size: var(--tsd-font-small); + vertical-align: middle; +} + +.tsd-panel-header .badge-group { + display: inline-block; + margin-left: .25em; +} + +.badge-group > span { + margin-right: 0.25rem; +} + + /* SYNTAX */ .tsd-generics {