Skip to content

Commit f12afda

Browse files
remcohaszingremcohaszing
authored
Refactor to use TypeScript @import JSDoc tags
Closes GH-2498. Reviewed-by: Titus Wormer <tituswormer@gmail.com>
1 parent 8ccbba8 commit f12afda

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+367
-319
lines changed

‎docs/_asset/editor.jsx

+19-19
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,20 @@
22
/* @jsxImportSource react */
33

44
/**
5-
* @typedef {import('@wooorm/starry-night').Grammar} Grammar
6-
* @typedef {import('estree').Node} EstreeNode
7-
* @typedef {import('estree').Program} Program
8-
* @typedef {import('hast').Nodes} HastNodes
9-
* @typedef {import('hast').Root} HastRoot
10-
* @typedef {import('mdast').Nodes} MdastNodes
11-
* @typedef {import('mdast').Root} MdastRoot
12-
* @typedef {import('mdast-util-mdx-jsx').MdxJsxAttribute} MdxJsxAttribute
13-
* @typedef {import('mdast-util-mdx-jsx').MdxJsxAttributeValueExpression} MdxJsxAttributeValueExpression
14-
* @typedef {import('mdast-util-mdx-jsx').MdxJsxExpressionAttribute} MdxJsxExpressionAttribute
15-
* @typedef {import('mdx/types.js').MDXModule} MDXModule
16-
* @typedef {import('react-error-boundary').FallbackProps} FallbackProperties
17-
* @typedef {import('unified').PluggableList} PluggableList
18-
* @typedef {import('unist').Node} UnistNode
5+
* @import {Grammar} from '@wooorm/starry-night'
6+
* @import {Node as EstreeNode, Program} from 'estree'
7+
* @import {Nodes as HastNodes, Root as HastRoot} from 'hast'
8+
* @import {Nodes as MdastNodes, Root as MdastRoot} from 'mdast'
9+
* @import {
10+
MdxJsxAttribute,
11+
MdxJsxAttributeValueExpression,
12+
MdxJsxExpressionAttribute
13+
* } from 'mdast-util-mdx-jsx'
14+
* @import {MDXModule} from 'mdx/types.js'
15+
* @import {ReactNode} from 'react'
16+
* @import {FallbackProps} from 'react-error-boundary'
17+
* @import {PluggableList} from 'unified'
18+
* @import {Node as UnistNode} from 'unist'
1919
*/
2020

2121
/**
@@ -35,7 +35,7 @@
3535
* OK.
3636
* @property {true} ok
3737
* Whether OK.
38-
* @property {JSX.Element} value
38+
* @property {ReactNode} value
3939
* Result.
4040
*
4141
* @typedef {EvalNok | EvalOk} EvalResult
@@ -315,7 +315,7 @@ function Playground() {
315315
const scope = formatMarkdown ? 'text.md' : 'source.mdx'
316316
// Cast to actual value.
317317
const compiledResult = /** @type {EvalResult | undefined} */ (evalResult)
318-
/** @type {JSX.Element | undefined} */
318+
/** @type {ReactNode | undefined} */
319319
let display
320320

321321
if (compiledResult) {
@@ -579,9 +579,9 @@ function Playground() {
579579

580580
/**
581581
*
582-
* @param {Readonly<FallbackProperties>} properties
582+
* @param {Readonly<FallbackProps>} properties
583583
* Properties.
584-
* @returns {JSX.Element}
584+
* @returns {ReactNode}
585585
* Element.
586586
*/
587587
function ErrorFallback(properties) {
@@ -601,7 +601,7 @@ function ErrorFallback(properties) {
601601
/**
602602
* @param {DisplayProperties} properties
603603
* Properties.
604-
* @returns {JSX.Element}
604+
* @returns {ReactNode}
605605
* Element.
606606
*/
607607
function DisplayError(properties) {

‎docs/_component/blog.jsx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
2-
* @typedef {import('./sort.js').Item} Item
2+
* @import {ReactNode} from 'react'
3+
* @import {Item} from './sort.js'
34
*/
45

56
/**
@@ -29,7 +30,7 @@ const dateTimeFormat = new Intl.DateTimeFormat('en', {dateStyle: 'long'})
2930
/**
3031
* @param {Readonly<EntryProperties>} properties
3132
* Properties.
32-
* @returns {JSX.Element}
33+
* @returns {ReactNode}
3334
* Element.
3435
*/
3536
export function BlogEntry(properties) {
@@ -106,7 +107,7 @@ export function BlogEntry(properties) {
106107
/**
107108
* @param {Readonly<GroupProperties>} properties
108109
* Properties.
109-
* @returns {JSX.Element}
110+
* @returns {ReactNode}
110111
* Element.
111112
*/
112113
export function BlogGroup(properties) {

‎docs/_component/home.jsx

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
/**
2-
* @typedef {import('react').ReactNode} ReactNode
3-
* @typedef {import('vfile').Data['meta']} DataMeta
4-
* @typedef {import('./sort.js').Item} Item
2+
* @import {ReactNode} from 'react'
3+
* @import {Data} from 'vfile'
4+
* @import {Item} from './sort.js'
55
*/
66

77
/**
8-
* @typedef {Exclude<DataMeta, undefined>} Meta
8+
* @typedef {Exclude<Data['meta'], undefined>} Meta
99
*
1010
* @typedef Properties
1111
* Properties.
@@ -26,7 +26,7 @@ import {NavigationSite, NavigationSiteSkip} from './nav-site.jsx'
2626
/**
2727
* @param {Readonly<Properties>} properties
2828
* Properties.
29-
* @returns {JSX.Element}
29+
* @returns {ReactNode}
3030
* Element.
3131
*/
3232
export function Home(properties) {

‎docs/_component/layout.jsx

+6-5
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
/**
2-
* @typedef {import('vfile').Data['meta']} DataMeta
3-
* @typedef {import('./sort.js').Item} Item
2+
* @import {ReactNode} from 'react'
3+
* @import {Data} from 'vfile'
4+
* @import {Item} from './sort.js'
45
*/
56

67
/**
@@ -10,11 +11,11 @@
1011
* Name.
1112
* @property {Readonly<URL>} ghUrl
1213
* GitHub URL.
13-
* @property {Readonly<DataMeta> | undefined} [meta]
14+
* @property {Readonly<Data['meta']> | undefined} [meta]
1415
* Meta.
1516
* @property {Readonly<Item>} navigationTree
1617
* Navigation tree.
17-
* @property {JSX.Element} children
18+
* @property {ReactNode} children
1819
* Children.
1920
*/
2021

@@ -28,7 +29,7 @@ const dateTimeFormat = new Intl.DateTimeFormat('en', {dateStyle: 'long'})
2829
/**
2930
* @param {Readonly<Properties>} properties
3031
* Properties.
31-
* @returns {JSX.Element}
32+
* @returns {ReactNode}
3233
* Element.
3334
*/
3435
export function Layout(properties) {

‎docs/_component/nav-site.jsx

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
2-
* @typedef {import('./sort.js').Item} Item
2+
* @import {ReactNode} from 'react'
3+
* @import {Item} from './sort.js'
34
*/
45

56
/**
@@ -34,7 +35,7 @@ export function NavigationSiteSkip() {
3435
/**
3536
* @param {Readonly<Properties>} properties
3637
* Properties.
37-
* @returns {JSX.Element}
38+
* @returns {ReactNode}
3839
* Element.
3940
*/
4041
export function NavigationSite(properties) {

‎docs/_component/nav.jsx

+5-5
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
/// <reference types="rehype-infer-description-meta" />
33

44
/**
5-
* @typedef {import('hast').ElementContent} ElementContent
6-
* @typedef {import('react').ReactNode} ReactNode
7-
* @typedef {import('./sort.js').Item} Item
5+
* @import {ElementContent} from 'hast'
6+
* @import {ReactNode} from 'react'
7+
* @import {Item} from './sort.js'
88
*/
99

1010
/**
@@ -46,7 +46,7 @@ const dateTimeFormat = new Intl.DateTimeFormat('en', {dateStyle: 'long'})
4646
/**
4747
* @param {Readonly<GroupProperties>} properties
4848
* Properties.
49-
* @returns {JSX.Element}
49+
* @returns {ReactNode}
5050
* Element.
5151
*/
5252
export function NavigationGroup(properties) {
@@ -69,7 +69,7 @@ export function NavigationGroup(properties) {
6969
/**
7070
* @param {Readonly<ItemProperties>} properties
7171
* Properties.
72-
* @returns {JSX.Element}
72+
* @returns {ReactNode}
7373
* Element.
7474
*/
7575
export function NavigationItem(properties) {

‎docs/_component/note.jsx

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* @typedef {import('react').ReactNode} ReactNode
2+
* @import {ReactNode} from 'react'
33
*/
44

55
/**
@@ -22,7 +22,7 @@ const known = new Set(['info', 'legacy', 'important'])
2222
/**
2323
* @param {Readonly<Properties>} properties
2424
* Properties.
25-
* @returns {JSX.Element}
25+
* @returns {ReactNode}
2626
* Element.
2727
*/
2828
export function Note(properties) {

‎docs/_component/snowfall.jsx

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @import {ReactNode} from 'react'
3+
*/
4+
15
/**
26
* @typedef Properties
37
* Properties.
@@ -14,7 +18,7 @@ const data = [6, 5, 2, 4.5, 1.5, 2.5, 2, 2.5, 1.5, 2.5, 3.5, 7]
1418
/**
1519
* @param {Readonly<Properties>} properties
1620
* Properties.
17-
* @returns {JSX.Element}
21+
* @returns {ReactNode}
1822
* Element.
1923
*/
2024
export function Chart(properties) {

‎docs/_component/sort.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
* @typedef {import('vfile').Data} Data
2+
* @import {Data} from 'vfile'
33
*/
44

55
/**

‎docs/blog/index.mdx

+11-5
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
{
2+
/**
3+
* @import {Item} from '../_component/sort.js
4+
*/
5+
6+
/**
7+
* @typedef Props
8+
* @property {Item} navigationTree
9+
*/
10+
}
11+
112
import assert from 'node:assert/strict'
213
import {BlogGroup} from '../_component/blog.jsx'
314

@@ -16,11 +27,6 @@ The latest news about MDX.
1627

1728
{
1829
(function () {
19-
/**
20-
* @typedef {import('../_component/sort.js').Item} Item
21-
*/
22-
23-
/** @type {Item} */
2430
const navigationTree = props.navigationTree
2531
const category = navigationTree.children.find(function (item) {
2632
return item.name === '/blog/'

‎docs/community/index.mdx

+11-5
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
{
2+
/**
3+
* @import {Item} from '../_component/sort.js
4+
*/
5+
6+
/**
7+
* @typedef Props
8+
* @property {Item} navigationTree
9+
*/
10+
}
11+
112
import assert from 'node:assert/strict'
213
import {NavigationGroup} from '../_component/nav.jsx'
314

@@ -15,11 +26,6 @@ and some background information.
1526

1627
{
1728
(function () {
18-
/**
19-
* @typedef {import('../_component/sort.js').Item} Item
20-
*/
21-
22-
/** @type {Item} */
2329
const navigationTree = props.navigationTree
2430
const category = navigationTree.children.find(function (item) {
2531
return item.name === '/community/'

‎docs/docs/index.mdx

+11-5
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
{
2+
/**
3+
* @import {Item} from '../_component/sort.js
4+
*/
5+
6+
/**
7+
* @typedef Props
8+
* @property {Item} navigationTree
9+
*/
10+
}
11+
112
import assert from 'node:assert/strict'
213
import {NavigationGroup} from '../_component/nav.jsx'
314

@@ -17,11 +28,6 @@ Reading through these should give you a good understanding of MDX.
1728

1829
{
1930
(function () {
20-
/**
21-
* @typedef {import('../_component/sort.js').Item} Item
22-
*/
23-
24-
/** @type {Item} */
2531
const navigationTree = props.navigationTree
2632
const category = navigationTree.children.find(function (item) {
2733
return item.name === '/docs/'

‎docs/guides/index.mdx

+11-5
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
{
2+
/**
3+
* @import {Item} from '../_component/sort.js
4+
*/
5+
6+
/**
7+
* @typedef Props
8+
* @property {Item} navigationTree
9+
*/
10+
}
11+
112
import assert from 'node:assert/strict'
213
import {NavigationGroup} from '../_component/nav.jsx'
314

@@ -15,11 +26,6 @@ around MDX.
1526

1627
{
1728
(function () {
18-
/**
19-
* @typedef {import('../_component/sort.js').Item} Item
20-
*/
21-
22-
/** @type {Item} */
2329
const navigationTree = props.navigationTree
2430
const category = navigationTree.children.find(function (item) {
2531
return item.name === '/guides/'

‎docs/packages/index.mdx

+11-5
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
{
2+
/**
3+
* @import {Item} from '../_component/sort.js
4+
*/
5+
6+
/**
7+
* @typedef Props
8+
* @property {Item} navigationTree
9+
*/
10+
}
11+
112
import assert from 'node:assert/strict'
213
import {NavigationGroup} from '../_component/nav.jsx'
314

@@ -17,11 +28,6 @@ bundlers and frontend frameworks.
1728

1829
{
1930
(function () {
20-
/**
21-
* @typedef {import('../_component/sort.js').Item} Item
22-
*/
23-
24-
/** @type {Item} */
2531
const navigationTree = props.navigationTree
2632
const category = navigationTree.children.find(function (item) {
2733
return item.name === '/packages/'

0 commit comments

Comments
 (0)