Visitar URL original
docs(options): use `@linkcode` where possible · rolldown/rolldown@d68f013 · GitHub
Skip to content

Commit d68f013

Browse files
sapphi-redsapphi-red
committed
docs(options): use @linkcode where possible
1 parent d214ddc commit d68f013

3 files changed

Lines changed: 57 additions & 33 deletions

File tree

‎docs/.vitepress/scripts/extract-options-plugin.ts‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,12 @@ function escapeRegex(s: string) {
66
return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
77
}
88

9-
function extractPropertySection(contents: string, propertyName: string): string | undefined {
9+
function extractPropertySection(
10+
contents: string,
11+
propertyName: string,
12+
parentName: string,
13+
propertyNameMap: Map<string, string>,
14+
): string | undefined {
1015
if (!contents) return undefined;
1116
const namePattern = escapeRegex(propertyName);
1217
const headingRe = new RegExp(
@@ -47,6 +52,13 @@ function extractPropertySection(contents: string, propertyName: string): string
4752
.replace(/^# (.+)\?\n?/m, '# $1')
4853
// Remove trailing horizontal separator
4954
.replace(/\*\*\*$/, '')
55+
// Transform in-page anchor links to cross-file links
56+
// e.g., [`output.file`](#file) -> [`output.file`](./OutputOptions.file)
57+
// Uses propertyNameMap to get correct casing (anchors are always lowercase)
58+
.replace(/\[([^\]]+)\]\(#([a-z][a-z0-9]*)\)/gi, (_, linkText, anchor) => {
59+
const propertyName = propertyNameMap.get(anchor.toLowerCase()) ?? anchor;
60+
return `[${linkText}](./${parentName}.${propertyName})`;
61+
})
5062
);
5163
}
5264

@@ -60,14 +72,24 @@ export function load(app: td.Application) {
6072

6173
const parentContents = page.contents ?? '';
6274

75+
const propertyNameMap = new Map<string, string>();
76+
for (const prop of parentReflection.children) {
77+
propertyNameMap.set(prop.name.toLowerCase(), prop.name);
78+
}
79+
6380
for (const property of parentReflection.children) {
6481
const newPage = new td.PageEvent(property);
6582

6683
newPage.project = page.project;
6784
newPage.filename = `${parentReflection.name}.${property.name}.md`;
6885
newPage.url = `${parentReflection.name}.${property.name}.md`;
6986

70-
const extracted = extractPropertySection(parentContents, property.name);
87+
const extracted = extractPropertySection(
88+
parentContents,
89+
property.name,
90+
parentReflection.name,
91+
propertyNameMap,
92+
);
7193
newPage.contents = extracted;
7294

7395
const outDir = app.options.getValue('out');

‎packages/rolldown/src/options/input-options.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,7 @@ export type OnwarnFunction = (
236236

237237
export interface InputOptions {
238238
/**
239-
* Defines entries and location(s) of entry modules for the bundle. Relative paths are resolved based on the `cwd` option.
239+
* Defines entries and location(s) of entry modules for the bundle. Relative paths are resolved based on the {@linkcode cwd} option.
240240
* {@include ./docs/input.md}
241241
*/
242242
input?: InputOption;
@@ -346,7 +346,7 @@ export interface InputOptions {
346346
*/
347347
symlinks?: boolean;
348348
/**
349-
* @deprecated Use the top-level `tsconfig` option instead.
349+
* @deprecated Use the top-level {@linkcode tsconfig} option instead.
350350
*/
351351
tsconfigFilename?: string;
352352
};
@@ -420,7 +420,7 @@ export interface InputOptions {
420420
* {@include ./docs/on-warn.md}
421421
*
422422
* @deprecated
423-
* This is a legacy API. Consider using `onLog` instead for better control over all log types.
423+
* This is a legacy API. Consider using {@linkcode onLog} instead for better control over all log types.
424424
*
425425
* {@include ./docs/on-warn-deprecation.md}
426426
*/

‎packages/rolldown/src/options/output-options.ts‎

Lines changed: 30 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ import type { SourcemapIgnoreListOption, SourcemapPathTransformOption } from '..
44
import type { ModuleInfo } from '../types/module-info';
55
import type { RenderedChunk } from '../types/rolldown-output';
66
import type { NullValue, StringOrRegExp } from '../types/utils';
7+
// oxlint-disable-next-line no-unused-vars -- this is used in JSDoc links
8+
import type { InputOptions } from './input-options';
79

810
export type GeneratedCodePreset = 'es5' | 'es2015';
911

@@ -99,15 +101,15 @@ export interface OutputOptions {
99101
/**
100102
* The directory in which all generated chunks are placed.
101103
*
102-
* The [`file`](https://rolldown.rs/reference/OutputOptions.file) option should be used instead if only a single chunk is generated.
104+
* The {@linkcode file | output.file} option should be used instead if only a single chunk is generated.
103105
*
104106
* @default 'dist'
105107
*/
106108
dir?: string;
107109
/**
108110
* The file path for the single generated chunk.
109111
*
110-
* The [`dir`](https://rolldown.rs/reference/OutputOptions.dir) option should be used instead if multiple chunks are generated.
112+
* The {@linkcode dir | output.dir} option should be used instead if multiple chunks are generated.
111113
*/
112114
file?: string;
113115
/**
@@ -217,45 +219,45 @@ export interface OutputOptions {
217219
/**
218220
* A string to prepend to the bundle before `renderChunk` hook.
219221
*
220-
* See [`output.intro`](https://rolldown.rs/reference/OutputOptions.intro), [`output.postBanner`](https://rolldown.rs/reference/OutputOptions.postBanner) as well.
222+
* See {@linkcode intro | output.intro}, {@linkcode postBanner | output.postBanner} as well.
221223
*
222224
* {@include ./docs/output-banner.md}
223225
*/
224226
banner?: string | AddonFunction;
225227
/**
226228
* A string to append to the bundle before `renderChunk` hook.
227229
*
228-
* See [`output.outro`](https://rolldown.rs/reference/OutputOptions.outro), [`output.postFooter`](https://rolldown.rs/reference/OutputOptions.postFooter) as well.
230+
* See {@linkcode outro | output.outro}, {@linkcode postFooter | output.postFooter} as well.
229231
*
230232
* {@include ./docs/output-footer.md}
231233
*/
232234
footer?: string | AddonFunction;
233235
/**
234236
* A string to prepend to the bundle after `renderChunk` hook and minification.
235237
*
236-
* See [`output.banner`](https://rolldown.rs/reference/OutputOptions.banner), [`output.intro`](https://rolldown.rs/reference/OutputOptions.intro) as well.
238+
* See {@linkcode banner | output.banner}, {@linkcode intro | output.intro} as well.
237239
*/
238240
postBanner?: string | AddonFunction;
239241
/**
240242
* A string to append to the bundle after `renderChunk` hook and minification.
241243
*
242-
* See [`output.footer`](https://rolldown.rs/reference/OutputOptions.footer), [`output.outro`](https://rolldown.rs/reference/OutputOptions.outro) as well.
244+
* See {@linkcode footer | output.footer}, {@linkcode outro | output.outro} as well.
243245
*/
244246
postFooter?: string | AddonFunction;
245247
/**
246248
* A string to prepend inside any format-specific wrapper.
247249
*
248-
* See [`output.banner`](https://rolldown.rs/reference/OutputOptions.banner), [`output.postBanner`](https://rolldown.rs/reference/OutputOptions.postBanner) as well.
250+
* See {@linkcode banner | output.banner}, {@linkcode postBanner | output.postBanner} as well.
249251
*/
250252
intro?: string | AddonFunction;
251253
/**
252254
* A string to append inside any format-specific wrapper.
253255
*
254-
* See [`output.footer`](https://rolldown.rs/reference/OutputOptions.footer), [`output.postFooter`](https://rolldown.rs/reference/OutputOptions.postFooter) as well.
256+
* See {@linkcode footer | output.footer}, {@linkcode postFooter | output.postFooter} as well.
255257
*/
256258
outro?: string | AddonFunction;
257259
/**
258-
* Whether to extend the global variable defined by the name option in `umd` or `iife` formats.
260+
* Whether to extend the global variable defined by the {@linkcode OutputOptions.name | name} option in `umd` or `iife` formats.
259261
*
260262
* When `true`, the global variable will be defined as `global.name = global.name || {}`.
261263
* When `false`, the global defined by name will be overwritten like `global.name = {}`.
@@ -281,12 +283,12 @@ export interface OutputOptions {
281283
* Patterns support the following placeholders:
282284
* - `[extname]`: The file extension of the asset including a leading dot, e.g. `.css`.
283285
* - `[ext]`: The file extension without a leading dot, e.g. css.
284-
* - `[hash]`: A hash based on the content of the asset. You can also set a specific hash length via e.g. `[hash:10]`. By default, it will create a base-64 hash. If you need a reduced character set, see [`output.hashCharacters`](https://rolldown.rs/reference/OutputOptions.hashCharacters).
286+
* - `[hash]`: A hash based on the content of the asset. You can also set a specific hash length via e.g. `[hash:10]`. By default, it will create a base-64 hash. If you need a reduced character set, see {@linkcode hashCharacters | output.hashCharacters}.
285287
* - `[name]`: The file name of the asset excluding any extension.
286288
*
287289
* Forward slashes (`/`) can be used to place files in sub-directories.
288290
*
289-
* See also [`output.chunkFileNames`](https://rolldown.rs/reference/OutputOptions.chunkFileNames), [`output.entryFileNames`](https://rolldown.rs/reference/OutputOptions.entryFileNames).
291+
* See also {@linkcode chunkFileNames | output.chunkFileNames}, {@linkcode entryFileNames | output.entryFileNames}.
290292
*
291293
* @default 'assets/[name]-[hash][extname]'
292294
*/
@@ -296,12 +298,12 @@ export interface OutputOptions {
296298
*
297299
* Patterns support the following placeholders:
298300
* - `[format]`: The rendering format defined in the output options, e.g. `es` or `cjs`.
299-
* - `[hash]`: A hash based only on the content of the final generated chunk, including transformations in `renderChunk` and any referenced file hashes. You can also set a specific hash length via e.g. `[hash:10]`. By default, it will create a base-64 hash. If you need a reduced character set, see [`output.hashCharacters`](https://rolldown.rs/reference/OutputOptions.hashCharacters).
301+
* - `[hash]`: A hash based only on the content of the final generated chunk, including transformations in `renderChunk` and any referenced file hashes. You can also set a specific hash length via e.g. `[hash:10]`. By default, it will create a base-64 hash. If you need a reduced character set, see {@linkcode hashCharacters | output.hashCharacters}.
300302
* - `[name]`: The file name (without extension) of the entry point, unless the object form of input was used to define a different name.
301303
*
302-
* Forward slashes (`/`) can be used to place files in sub-directories. This pattern will also be used for every file when setting the [`output.preserveModules`](https://rolldown.rs/reference/OutputOptions.preserveModules) option.
304+
* Forward slashes (`/`) can be used to place files in sub-directories. This pattern will also be used for every file when setting the {@linkcode preserveModules | output.preserveModules} option.
303305
*
304-
* See also [`output.assetFileNames`](https://rolldown.rs/reference/OutputOptions.assetFileNames), [`output.chunkFileNames`](https://rolldown.rs/reference/OutputOptions.chunkFileNames).
306+
* See also {@linkcode assetFileNames | output.assetFileNames}, {@linkcode chunkFileNames | output.chunkFileNames}.
305307
*
306308
* @default '[name].js'
307309
*/
@@ -311,12 +313,12 @@ export interface OutputOptions {
311313
*
312314
* Patterns support the following placeholders:
313315
* - `[format]`: The rendering format defined in the output options, e.g. `es` or `cjs`.
314-
* - `[hash]`: A hash based only on the content of the final generated chunk, including transformations in `renderChunk` and any referenced file hashes. You can also set a specific hash length via e.g. `[hash:10]`. By default, it will create a base-64 hash. If you need a reduced character set, see [`output.hashCharacters`](https://rolldown.rs/reference/OutputOptions.hashCharacters).
315-
* - `[name]`: The name of the chunk. This can be explicitly set via the [`output.advancedChunks`](https://rolldown.rs/reference/OutputOptions.advancedChunks) option or when the chunk is created by a plugin via `this.emitFile`. Otherwise, it will be derived from the chunk contents.
316+
* - `[hash]`: A hash based only on the content of the final generated chunk, including transformations in `renderChunk` and any referenced file hashes. You can also set a specific hash length via e.g. `[hash:10]`. By default, it will create a base-64 hash. If you need a reduced character set, see {@linkcode hashCharacters | output.hashCharacters}.
317+
* - `[name]`: The name of the chunk. This can be explicitly set via the {@linkcode advancedChunks | output.advancedChunks} option or when the chunk is created by a plugin via `this.emitFile`. Otherwise, it will be derived from the chunk contents.
316318
*
317319
* Forward slashes (`/`) can be used to place files in sub-directories.
318320
*
319-
* See also [`output.assetFileNames`](https://rolldown.rs/reference/OutputOptions.assetFileNames), [`output.entryFileNames`](https://rolldown.rs/reference/OutputOptions.entryFileNames).
321+
* See also {@linkcode assetFileNames | output.assetFileNames}, {@linkcode entryFileNames | output.entryFileNames}.
320322
*
321323
* @default '[name]-[hash].js'
322324
*/
@@ -507,7 +509,7 @@ export interface OutputOptions {
507509
* Note that unlike Rollup, object form is not supported.
508510
*
509511
* @deprecated
510-
* Please use `advancedChunks` instead.
512+
* Please use {@linkcode advancedChunks | output.advancedChunks} instead.
511513
*
512514
* :::warning
513515
* If `manualChunks` and `advancedChunks` are both specified, `manualChunks` option will be ignored.
@@ -541,32 +543,32 @@ export interface OutputOptions {
541543
* By default, each group will also include captured modules' dependencies. This reduces the chance of generating circular chunks.
542544
*
543545
* If you want to disable this behavior, it's recommended to both set
544-
* - `preserveEntrySignatures: false | 'allow-extension'`
545-
* - `strictExecutionOrder: true`
546+
* - {@linkcode InputOptions.preserveEntrySignatures | preserveEntrySignatures}: `false | 'allow-extension'`
547+
* - `experimental.strictExecutionOrder`: `true`
546548
*
547549
* to avoid generating invalid chunks.
548550
*
549551
* @default true
550552
*/
551553
includeDependenciesRecursively?: boolean;
552554
/**
553-
* Global fallback of {@link AdvancedChunksGroup.minSize | `group.minSize`}, if it's not specified in the group.
555+
* Global fallback of {@linkcode AdvancedChunksGroup.minSize | group.minSize}, if it's not specified in the group.
554556
*/
555557
minSize?: number;
556558
/**
557-
* Global fallback of {@link AdvancedChunksGroup.maxSize | `group.maxSize`}, if it's not specified in the group.
559+
* Global fallback of {@linkcode AdvancedChunksGroup.maxSize | group.maxSize}, if it's not specified in the group.
558560
*/
559561
maxSize?: number;
560562
/**
561-
* Global fallback of {@link AdvancedChunksGroup.maxModuleSize | `group.maxModuleSize`}, if it's not specified in the group.
563+
* Global fallback of {@linkcode AdvancedChunksGroup.maxModuleSize | group.maxModuleSize}, if it's not specified in the group.
562564
*/
563565
maxModuleSize?: number;
564566
/**
565-
* Global fallback of {@link AdvancedChunksGroup.minModuleSize | `group.minModuleSize`}, if it's not specified in the group.
567+
* Global fallback of {@linkcode AdvancedChunksGroup.minModuleSize | group.minModuleSize}, if it's not specified in the group.
566568
*/
567569
minModuleSize?: number;
568570
/**
569-
* Global fallback of {@link AdvancedChunksGroup.minShareCount | `group.minShareCount`}, if it's not specified in the group.
571+
* Global fallback of {@linkcode AdvancedChunksGroup.minShareCount | group.minShareCount}, if it's not specified in the group.
570572
*/
571573
minShareCount?: number;
572574
/**
@@ -613,7 +615,7 @@ export interface OutputOptions {
613615
*/
614616
virtualDirname?: string;
615617
/**
616-
* A directory path to input modules that should be stripped away from [`output.dir`](https://rolldown.rs/reference/OutputOptions.dir) when using preserve modules mode.
618+
* A directory path to input modules that should be stripped away from {@linkcode dir | output.dir} when using preserve modules mode.
617619
*
618620
* {@include ./docs/output-preserve-modules-root.md}
619621
*/
@@ -638,7 +640,7 @@ export interface OutputOptions {
638640
*/
639641
minifyInternalExports?: boolean;
640642
/**
641-
* Clean output directory ([`output.dir`](https://rolldown.rs/reference/OutputOptions.dir)) before emitting output.
643+
* Clean output directory ({@linkcode dir | output.dir}) before emitting output.
642644
*
643645
* @default false
644646
*
@@ -659,7 +661,7 @@ export interface OutputOptions {
659661

660662
export type AdvancedChunksGroup = {
661663
/**
662-
* Name of the group. It will be also used as the name of the chunk and replace the `[name]` placeholder in the `chunkFileNames` option.
664+
* Name of the group. It will be also used as the name of the chunk and replace the `[name]` placeholder in the {@linkcode OutputOptions.chunkFileNames | output.chunkFileNames} option.
663665
*
664666
* For example,
665667
*

0 commit comments

Comments
 (0)