From 4c064e30b59d9f45ba40b6db58129919c100897f Mon Sep 17 00:00:00 2001 From: meteorlxy Date: Fri, 13 Sep 2024 01:43:13 +0800 Subject: [PATCH] chore(core): improve type comments and replace internal with private --- e2e/docs/.vuepress/plugins/foo/fooPlugin.ts | 3 +- packages/core/src/app/appInit.ts | 2 +- packages/core/src/app/appPrepare.ts | 2 +- packages/core/src/app/appUse.ts | 2 +- packages/core/src/app/createBaseApp.ts | 2 +- .../src/app/prepare/prepareClientConfigs.ts | 2 +- .../core/src/app/prepare/preparePageChunk.ts | 2 +- .../src/app/prepare/preparePageComponent.ts | 2 +- .../core/src/app/prepare/prepareRoutes.ts | 2 +- .../core/src/app/prepare/prepareSiteData.ts | 2 +- packages/core/src/app/resolveAppDir.ts | 2 +- packages/core/src/app/resolveAppEnv.ts | 2 +- packages/core/src/app/resolveAppMarkdown.ts | 2 +- packages/core/src/app/resolveAppOptions.ts | 2 +- packages/core/src/app/resolveAppPages.ts | 2 +- packages/core/src/app/resolveAppSiteData.ts | 2 +- packages/core/src/app/resolveAppVersion.ts | 2 +- packages/core/src/app/resolveAppWriteTemp.ts | 2 +- packages/core/src/app/resolvePluginObject.ts | 2 +- packages/core/src/app/resolveThemeInfo.ts | 2 +- .../core/src/app/setupAppThemeAndPlugins.ts | 2 +- packages/core/src/page/createPage.ts | 2 +- packages/core/src/page/inferPagePath.ts | 2 +- packages/core/src/page/parsePageContent.ts | 2 +- .../core/src/page/renderPageSfcBlocksToVue.ts | 2 +- .../core/src/page/resolvePageChunkInfo.ts | 2 +- .../core/src/page/resolvePageComponentInfo.ts | 2 +- packages/core/src/page/resolvePageContent.ts | 2 +- packages/core/src/page/resolvePageDate.ts | 2 +- packages/core/src/page/resolvePageFilePath.ts | 2 +- packages/core/src/page/resolvePageHtmlInfo.ts | 2 +- packages/core/src/page/resolvePageLang.ts | 2 +- packages/core/src/page/resolvePagePath.ts | 2 +- .../core/src/page/resolvePagePermalink.ts | 2 +- .../core/src/page/resolvePageRouteMeta.ts | 2 +- packages/core/src/page/resolvePageSlug.ts | 2 +- .../core/src/pluginApi/createHookQueue.ts | 2 +- .../core/src/pluginApi/createPluginApi.ts | 2 +- .../src/pluginApi/createPluginApiHooks.ts | 2 +- .../pluginApi/createPluginApiRegisterHooks.ts | 2 +- .../src/pluginApi/normalizeAliasDefineHook.ts | 2 +- .../normalizeClientConfigFileHook.ts | 2 +- packages/core/src/types/app/options.ts | 90 ++++++++++++++++++- packages/core/src/types/app/utils.ts | 23 +++++ packages/core/src/types/bundler.ts | 11 +++ packages/core/src/types/plugin.ts | 8 +- 46 files changed, 170 insertions(+), 47 deletions(-) diff --git a/e2e/docs/.vuepress/plugins/foo/fooPlugin.ts b/e2e/docs/.vuepress/plugins/foo/fooPlugin.ts index 93ef0c8cff..a6031278ff 100644 --- a/e2e/docs/.vuepress/plugins/foo/fooPlugin.ts +++ b/e2e/docs/.vuepress/plugins/foo/fooPlugin.ts @@ -1,8 +1,9 @@ +import type { Plugin } from 'vuepress/core' import { getDirname, path } from 'vuepress/utils' const __dirname = getDirname(import.meta.url) -export const fooPlugin = { +export const fooPlugin: Plugin = { name: 'test-plugin', clientConfigFile: path.resolve( __dirname, diff --git a/packages/core/src/app/appInit.ts b/packages/core/src/app/appInit.ts index 95ce110178..337941a30e 100644 --- a/packages/core/src/app/appInit.ts +++ b/packages/core/src/app/appInit.ts @@ -10,7 +10,7 @@ const log = debug('vuepress:core/app') * * Plugins should be used before initialization. * - * @internal + * @private */ export const appInit = async (app: App): Promise => { log('init start') diff --git a/packages/core/src/app/appPrepare.ts b/packages/core/src/app/appPrepare.ts index 15dd6986b7..404405b45c 100644 --- a/packages/core/src/app/appPrepare.ts +++ b/packages/core/src/app/appPrepare.ts @@ -19,7 +19,7 @@ const log = debug('vuepress:core/app') * - site data * - other files that generated by plugins * - * @internal + * @private */ export const appPrepare = async (app: App): Promise => { log('prepare start') diff --git a/packages/core/src/app/appUse.ts b/packages/core/src/app/appUse.ts index 9c98443a39..34d3b50387 100644 --- a/packages/core/src/app/appUse.ts +++ b/packages/core/src/app/appUse.ts @@ -9,7 +9,7 @@ const log = debug('vuepress:core/app') * * Should be called before initialization. * - * @internal + * @private */ export const appUse = (app: App, rawPlugin: Plugin): App => { const pluginObject = resolvePluginObject(app, rawPlugin) diff --git a/packages/core/src/app/createBaseApp.ts b/packages/core/src/app/createBaseApp.ts index 624d18ac91..7dd1d7aa1f 100644 --- a/packages/core/src/app/createBaseApp.ts +++ b/packages/core/src/app/createBaseApp.ts @@ -19,7 +19,7 @@ import { setupAppThemeAndPlugins } from './setupAppThemeAndPlugins.js' /** * Create vuepress app * - * @internal + * @private */ export const createBaseApp = (config: AppConfig): App => { const options = resolveAppOptions(config) diff --git a/packages/core/src/app/prepare/prepareClientConfigs.ts b/packages/core/src/app/prepare/prepareClientConfigs.ts index 4636bd5556..a434da4e96 100644 --- a/packages/core/src/app/prepare/prepareClientConfigs.ts +++ b/packages/core/src/app/prepare/prepareClientConfigs.ts @@ -3,7 +3,7 @@ import type { App } from '../../types/index.js' /** * Generate client configs temp file * - * @internal + * @private */ export const prepareClientConfigs = async (app: App): Promise => { // plugin hook: clientConfigFile diff --git a/packages/core/src/app/prepare/preparePageChunk.ts b/packages/core/src/app/prepare/preparePageChunk.ts index e401d9cfce..0e9be7bcb2 100644 --- a/packages/core/src/app/prepare/preparePageChunk.ts +++ b/packages/core/src/app/prepare/preparePageChunk.ts @@ -18,7 +18,7 @@ if (import.meta.hot) { /** * Generate page chunk temp file of a single page * - * @internal + * @private */ export const preparePageChunk = async (app: App, page: Page): Promise => { // page chunk file content diff --git a/packages/core/src/app/prepare/preparePageComponent.ts b/packages/core/src/app/prepare/preparePageComponent.ts index c37fe9c2c9..f3d172082a 100644 --- a/packages/core/src/app/prepare/preparePageComponent.ts +++ b/packages/core/src/app/prepare/preparePageComponent.ts @@ -4,7 +4,7 @@ import type { App, Page } from '../../types/index.js' /** * Generate page component temp file of a single page * - * @internal + * @private */ export const preparePageComponent = async ( app: App, diff --git a/packages/core/src/app/prepare/prepareRoutes.ts b/packages/core/src/app/prepare/prepareRoutes.ts index a4f8d6f549..4e54e90d94 100644 --- a/packages/core/src/app/prepare/prepareRoutes.ts +++ b/packages/core/src/app/prepare/prepareRoutes.ts @@ -23,7 +23,7 @@ if (import.meta.hot) { /** * Resolve page redirects * - * @internal + * @private */ const resolvePageRedirects = ({ path, pathInferred }: Page): string[] => { // paths that should redirect to this page, use set to dedupe diff --git a/packages/core/src/app/prepare/prepareSiteData.ts b/packages/core/src/app/prepare/prepareSiteData.ts index 7121e72845..cdf8022a9d 100644 --- a/packages/core/src/app/prepare/prepareSiteData.ts +++ b/packages/core/src/app/prepare/prepareSiteData.ts @@ -18,7 +18,7 @@ if (import.meta.hot) { /** * Generate site data temp file * - * @internal + * @private */ export const prepareSiteData = async (app: App): Promise => { let content = `\ diff --git a/packages/core/src/app/resolveAppDir.ts b/packages/core/src/app/resolveAppDir.ts index 18819dca9d..f66763b90b 100644 --- a/packages/core/src/app/resolveAppDir.ts +++ b/packages/core/src/app/resolveAppDir.ts @@ -7,7 +7,7 @@ const require = createRequire(import.meta.url) /** * Create directory util function * - * @internal + * @private */ export const createAppDirFunction = (baseDir: string): AppDirFunction => diff --git a/packages/core/src/app/resolveAppEnv.ts b/packages/core/src/app/resolveAppEnv.ts index d0b069c6a4..bcd4504b52 100644 --- a/packages/core/src/app/resolveAppEnv.ts +++ b/packages/core/src/app/resolveAppEnv.ts @@ -3,7 +3,7 @@ import type { AppEnv, AppOptions } from '../types/index.js' /** * Resolve environment flags for vuepress app * - * @internal + * @private */ export const resolveAppEnv = (options: AppOptions): AppEnv => ({ isBuild: false, diff --git a/packages/core/src/app/resolveAppMarkdown.ts b/packages/core/src/app/resolveAppMarkdown.ts index d3b35b4ef2..56893649c7 100644 --- a/packages/core/src/app/resolveAppMarkdown.ts +++ b/packages/core/src/app/resolveAppMarkdown.ts @@ -5,7 +5,7 @@ import type { App } from '../types/index.js' /** * Resolve markdown-it instance for vuepress app * - * @internal + * @private */ export const resolveAppMarkdown = async (app: App): Promise => { // plugin hook: extendsMarkdownOptions diff --git a/packages/core/src/app/resolveAppOptions.ts b/packages/core/src/app/resolveAppOptions.ts index 756227ffe5..3e38ff5793 100644 --- a/packages/core/src/app/resolveAppOptions.ts +++ b/packages/core/src/app/resolveAppOptions.ts @@ -7,7 +7,7 @@ const require = createRequire(import.meta.url) /** * Create app options with default values * - * @internal + * @private */ export const resolveAppOptions = ({ // site config diff --git a/packages/core/src/app/resolveAppPages.ts b/packages/core/src/app/resolveAppPages.ts index 51ed100308..daf4bec1da 100644 --- a/packages/core/src/app/resolveAppPages.ts +++ b/packages/core/src/app/resolveAppPages.ts @@ -7,7 +7,7 @@ const log = debug('vuepress:core/app') /** * Resolve pages for vuepress app * - * @internal + * @private */ export const resolveAppPages = async (app: App): Promise => { log('resolveAppPages start') diff --git a/packages/core/src/app/resolveAppSiteData.ts b/packages/core/src/app/resolveAppSiteData.ts index bc37720131..a66926bbe4 100644 --- a/packages/core/src/app/resolveAppSiteData.ts +++ b/packages/core/src/app/resolveAppSiteData.ts @@ -5,7 +5,7 @@ import type { AppOptions, SiteData } from '../types/index.js' * * Site data will also be used in client * - * @internal + * @private */ export const resolveAppSiteData = (options: AppOptions): SiteData => ({ base: options.base, diff --git a/packages/core/src/app/resolveAppVersion.ts b/packages/core/src/app/resolveAppVersion.ts index 5f356432a3..25e4bba1b4 100644 --- a/packages/core/src/app/resolveAppVersion.ts +++ b/packages/core/src/app/resolveAppVersion.ts @@ -6,7 +6,7 @@ const require = createRequire(import.meta.url) /** * Resolve version of vuepress app * - * @internal + * @private */ export const resolveAppVersion = (): string => { const pkgJson = fs.readJsonSync( diff --git a/packages/core/src/app/resolveAppWriteTemp.ts b/packages/core/src/app/resolveAppWriteTemp.ts index 2a3560f072..126e8306f0 100644 --- a/packages/core/src/app/resolveAppWriteTemp.ts +++ b/packages/core/src/app/resolveAppWriteTemp.ts @@ -4,7 +4,7 @@ import type { AppDir, AppWriteTemp } from '../types/index.js' /** * Resolve write temp file util for vuepress app * - * @internal + * @private */ export const resolveAppWriteTemp = (dir: AppDir): AppWriteTemp => { const writeTemp: AppWriteTemp = async (file: string, content: string) => { diff --git a/packages/core/src/app/resolvePluginObject.ts b/packages/core/src/app/resolvePluginObject.ts index 4636f48ac0..fd58c45adb 100644 --- a/packages/core/src/app/resolvePluginObject.ts +++ b/packages/core/src/app/resolvePluginObject.ts @@ -4,7 +4,7 @@ import type { App, Plugin, PluginObject } from '../types/index.js' /** * Resolve a plugin object according to name / path / module and config * - * @internal + * @private */ export const resolvePluginObject = ( app: App, diff --git a/packages/core/src/app/resolveThemeInfo.ts b/packages/core/src/app/resolveThemeInfo.ts index b16c371429..8fca922e21 100644 --- a/packages/core/src/app/resolveThemeInfo.ts +++ b/packages/core/src/app/resolveThemeInfo.ts @@ -4,7 +4,7 @@ import { resolvePluginObject } from './resolvePluginObject.js' /** * Resolve theme info and its parent theme info * - * @internal + * @private */ export const resolveThemeInfo = (app: App, theme: Theme): ThemeInfo => { // resolve current theme info diff --git a/packages/core/src/app/setupAppThemeAndPlugins.ts b/packages/core/src/app/setupAppThemeAndPlugins.ts index 39aceda92b..66e42257c2 100644 --- a/packages/core/src/app/setupAppThemeAndPlugins.ts +++ b/packages/core/src/app/setupAppThemeAndPlugins.ts @@ -4,7 +4,7 @@ import { resolveThemeInfo } from './resolveThemeInfo.js' /** * Setup theme and plugins for vuepress app * - * @internal + * @private */ export const setupAppThemeAndPlugins = (app: App, config: AppConfig): void => { // recursively resolve theme info diff --git a/packages/core/src/page/createPage.ts b/packages/core/src/page/createPage.ts index 8234621208..620f509e1a 100644 --- a/packages/core/src/page/createPage.ts +++ b/packages/core/src/page/createPage.ts @@ -16,7 +16,7 @@ import { resolvePageSlug } from './resolvePageSlug.js' /** * Create vuepress page object * - * @internal + * @private */ export const createPage = async ( app: App, diff --git a/packages/core/src/page/inferPagePath.ts b/packages/core/src/page/inferPagePath.ts index 2a406c7b66..baf56f94a0 100644 --- a/packages/core/src/page/inferPagePath.ts +++ b/packages/core/src/page/inferPagePath.ts @@ -8,7 +8,7 @@ import type { App } from '../types/index.js' /** * Infer page path according to file path * - * @internal + * @private */ export const inferPagePath = ({ app, diff --git a/packages/core/src/page/parsePageContent.ts b/packages/core/src/page/parsePageContent.ts index 03e036a87e..2ca75a62d8 100644 --- a/packages/core/src/page/parsePageContent.ts +++ b/packages/core/src/page/parsePageContent.ts @@ -10,7 +10,7 @@ import type { App, PageFrontmatter, PageOptions } from '../types/index.js' /** * Render page content and extract related info * - * @internal + * @private */ export const parsePageContent = ({ app, diff --git a/packages/core/src/page/renderPageSfcBlocksToVue.ts b/packages/core/src/page/renderPageSfcBlocksToVue.ts index 79f15e92ca..bbef2b7ca4 100644 --- a/packages/core/src/page/renderPageSfcBlocksToVue.ts +++ b/packages/core/src/page/renderPageSfcBlocksToVue.ts @@ -3,7 +3,7 @@ import type { MarkdownSfcBlocks } from '@vuepress/markdown' /** * Render page sfc blocks to vue component * - * @internal + * @private */ export const renderPageSfcBlocksToVue = ( sfcBlocks: MarkdownSfcBlocks, diff --git a/packages/core/src/page/resolvePageChunkInfo.ts b/packages/core/src/page/resolvePageChunkInfo.ts index 0d5c6b994f..4ee6066d24 100644 --- a/packages/core/src/page/resolvePageChunkInfo.ts +++ b/packages/core/src/page/resolvePageChunkInfo.ts @@ -4,7 +4,7 @@ import type { App } from '../types/index.js' /** * Resolve page data file path * - * @internal + * @private */ export const resolvePageChunkInfo = ({ app, diff --git a/packages/core/src/page/resolvePageComponentInfo.ts b/packages/core/src/page/resolvePageComponentInfo.ts index 1e5d4d6156..46c36e1630 100644 --- a/packages/core/src/page/resolvePageComponentInfo.ts +++ b/packages/core/src/page/resolvePageComponentInfo.ts @@ -4,7 +4,7 @@ import type { App } from '../types/index.js' /** * Resolve page component and related info * - * @internal + * @private */ export const resolvePageComponentInfo = ({ app, diff --git a/packages/core/src/page/resolvePageContent.ts b/packages/core/src/page/resolvePageContent.ts index 51a1aa3ab2..f341d833a1 100644 --- a/packages/core/src/page/resolvePageContent.ts +++ b/packages/core/src/page/resolvePageContent.ts @@ -10,7 +10,7 @@ const FALLBACK_CONTENT = '' /** * Resolve page content according to `content` or `filePath` * - * @internal + * @private */ export const resolvePageContent = async ({ filePath, diff --git a/packages/core/src/page/resolvePageDate.ts b/packages/core/src/page/resolvePageDate.ts index f9b2d5312c..a9bcc71163 100644 --- a/packages/core/src/page/resolvePageDate.ts +++ b/packages/core/src/page/resolvePageDate.ts @@ -11,7 +11,7 @@ const DEFAULT_DATE = '0000-00-00' * * It will be resolved as 'yyyy-MM-dd' format * - * @internal + * @private */ export const resolvePageDate = ({ frontmatter, diff --git a/packages/core/src/page/resolvePageFilePath.ts b/packages/core/src/page/resolvePageFilePath.ts index 32d34e23a5..d019862dcb 100644 --- a/packages/core/src/page/resolvePageFilePath.ts +++ b/packages/core/src/page/resolvePageFilePath.ts @@ -4,7 +4,7 @@ import type { App, PageOptions } from '../types/index.js' /** * Resolve absolute and relative path of page file * - * @internal + * @private */ export const resolvePageFilePath = ({ app, diff --git a/packages/core/src/page/resolvePageHtmlInfo.ts b/packages/core/src/page/resolvePageHtmlInfo.ts index 0417e4edbe..39623cd6e6 100644 --- a/packages/core/src/page/resolvePageHtmlInfo.ts +++ b/packages/core/src/page/resolvePageHtmlInfo.ts @@ -4,7 +4,7 @@ import type { App } from '../types/index.js' /** * Resolve page rendered html file path * - * @internal + * @private */ export const resolvePageHtmlInfo = ({ app, diff --git a/packages/core/src/page/resolvePageLang.ts b/packages/core/src/page/resolvePageLang.ts index d0774e871c..e6d185a4a9 100644 --- a/packages/core/src/page/resolvePageLang.ts +++ b/packages/core/src/page/resolvePageLang.ts @@ -4,7 +4,7 @@ import type { App, PageFrontmatter } from '../types/index.js' /** * Resolve language of page * - * @internal + * @private */ export const resolvePageLang = ({ app, diff --git a/packages/core/src/page/resolvePagePath.ts b/packages/core/src/page/resolvePagePath.ts index 0edac439de..c2206843f6 100644 --- a/packages/core/src/page/resolvePagePath.ts +++ b/packages/core/src/page/resolvePagePath.ts @@ -4,7 +4,7 @@ import type { PageOptions } from '../types/index.js' /** * Resolve the final route path of a page * - * @internal + * @private */ export const resolvePagePath = ({ permalink, diff --git a/packages/core/src/page/resolvePagePermalink.ts b/packages/core/src/page/resolvePagePermalink.ts index 4b62c069f7..753559489e 100644 --- a/packages/core/src/page/resolvePagePermalink.ts +++ b/packages/core/src/page/resolvePagePermalink.ts @@ -5,7 +5,7 @@ import type { App, PageFrontmatter } from '../types/index.js' /** * Resolve page permalink from frontmatter / options / pattern * - * @internal + * @private */ export const resolvePagePermalink = ({ app, diff --git a/packages/core/src/page/resolvePageRouteMeta.ts b/packages/core/src/page/resolvePageRouteMeta.ts index fa66e39d36..58daaab046 100644 --- a/packages/core/src/page/resolvePageRouteMeta.ts +++ b/packages/core/src/page/resolvePageRouteMeta.ts @@ -3,7 +3,7 @@ import type { PageFrontmatter } from '../types/index.js' /** * Resolve page route meta * - * @internal + * @private */ export const resolvePageRouteMeta = ({ frontmatter, diff --git a/packages/core/src/page/resolvePageSlug.ts b/packages/core/src/page/resolvePageSlug.ts index f9c3704571..0d664c41c6 100644 --- a/packages/core/src/page/resolvePageSlug.ts +++ b/packages/core/src/page/resolvePageSlug.ts @@ -5,7 +5,7 @@ const DATE_RE = /(\d{4}-\d{1,2}(-\d{1,2})?)-(.*)/ /** * Resolve page slug from filename * - * @internal + * @private */ export const resolvePageSlug = ({ filePathRelative, diff --git a/packages/core/src/pluginApi/createHookQueue.ts b/packages/core/src/pluginApi/createHookQueue.ts index 9fb70cc9ad..79d2b926f6 100644 --- a/packages/core/src/pluginApi/createHookQueue.ts +++ b/packages/core/src/pluginApi/createHookQueue.ts @@ -11,7 +11,7 @@ const log = debug('vuepress:core/plugin-api') /** * Create hook queue for plugin system * - * @internal + * @private */ export const createHookQueue = (name: T): HookQueue => { const items: HookItem[] = [] diff --git a/packages/core/src/pluginApi/createPluginApi.ts b/packages/core/src/pluginApi/createPluginApi.ts index 18aa270ed7..4918df022c 100644 --- a/packages/core/src/pluginApi/createPluginApi.ts +++ b/packages/core/src/pluginApi/createPluginApi.ts @@ -5,7 +5,7 @@ import { createPluginApiRegisterHooks } from './createPluginApiRegisterHooks.js' /** * Create vuepress plugin api * - * @internal + * @private */ export const createPluginApi = (): PluginApi => { const plugins: PluginApi['plugins'] = [] diff --git a/packages/core/src/pluginApi/createPluginApiHooks.ts b/packages/core/src/pluginApi/createPluginApiHooks.ts index d8369985bb..e1d57a393a 100644 --- a/packages/core/src/pluginApi/createPluginApiHooks.ts +++ b/packages/core/src/pluginApi/createPluginApiHooks.ts @@ -4,7 +4,7 @@ import { createHookQueue } from './createHookQueue.js' /** * Create hooks for plugin api * - * @internal + * @private */ export const createPluginApiHooks = (): PluginApi['hooks'] => ({ // life cycle hooks diff --git a/packages/core/src/pluginApi/createPluginApiRegisterHooks.ts b/packages/core/src/pluginApi/createPluginApiRegisterHooks.ts index 22c94c4a01..768e3c697d 100644 --- a/packages/core/src/pluginApi/createPluginApiRegisterHooks.ts +++ b/packages/core/src/pluginApi/createPluginApiRegisterHooks.ts @@ -5,7 +5,7 @@ import { normalizeClientConfigFileHook } from './normalizeClientConfigFileHook.j /** * Create registerHooks method for plugin api * - * @internal + * @private */ export const createPluginApiRegisterHooks = ( diff --git a/packages/core/src/pluginApi/normalizeAliasDefineHook.ts b/packages/core/src/pluginApi/normalizeAliasDefineHook.ts index 1b12ac361b..8779aeb463 100644 --- a/packages/core/src/pluginApi/normalizeAliasDefineHook.ts +++ b/packages/core/src/pluginApi/normalizeAliasDefineHook.ts @@ -4,7 +4,7 @@ import type { AliasDefineHook } from '../types/index.js' /** * Normalize alias and define hook * - * @internal + * @private */ export const normalizeAliasDefineHook = (hook: AliasDefineHook['exposed']): AliasDefineHook['normalized'] => diff --git a/packages/core/src/pluginApi/normalizeClientConfigFileHook.ts b/packages/core/src/pluginApi/normalizeClientConfigFileHook.ts index a6475852e4..c43814deab 100644 --- a/packages/core/src/pluginApi/normalizeClientConfigFileHook.ts +++ b/packages/core/src/pluginApi/normalizeClientConfigFileHook.ts @@ -5,7 +5,7 @@ import type { ClientConfigFileHook } from '../types/index.js' /** * Normalize hook for client config file * - * @internal + * @private */ export const normalizeClientConfigFileHook = (hook: ClientConfigFileHook['exposed']): ClientConfigFileHook['normalized'] => diff --git a/packages/core/src/types/app/options.ts b/packages/core/src/types/app/options.ts index 4cbcabbc37..74a11478f6 100644 --- a/packages/core/src/types/app/options.ts +++ b/packages/core/src/types/app/options.ts @@ -9,18 +9,98 @@ import type { Theme } from '../theme.js' * Vuepress app common config that shared between dev and build */ export interface AppConfigCommon extends Partial { + /** + * Source directory of the markdown files. + * + * Vuepress will load markdown files from this directory. + * + * @required + */ source: string + + /** + * Destination directory of the output files. + * + * Vuepress will output the static site files to this directory. + * + * @default `${source}/.vuepress/dist` + */ dest?: string + + /** + * Temp files directory. + * + * Vuepress will write temp files to this directory. + * + * @default `${source}/.vuepress/.temp` + */ temp?: string + + /** + * Cache files directory. + * + * Vuepress will write cache files to this directory. + * + * @default `${source}/.vuepress/.cache` + */ cache?: string + + /** + * Public files directory. + * + * Vuepress will copy the files from public directory to the output directory. + * + * @default `${source}/.vuepress/public` + */ public?: string + /** + * Whether to enable debug mode + * + * @default false + */ debug?: boolean + + /** + * Markdown options + * + * @default {} + */ markdown?: MarkdownOptions + + /** + * Patterns to match the markdown files as pages + * + * @default ['**\/*.md', '!.vuepress', '!node_modules'] + */ pagePatterns?: string[] + + /** + * Pattern to generate permalink for pages + * + * @default null + */ permalinkPattern?: string | null + + /** + * Vuepress bundler + * + * @required + */ bundler: Bundler + + /** + * Vuepress theme + * + * @required + */ theme: Theme + + /** + * Vuepress plugins + * + * @default [] + */ plugins?: PluginConfig } @@ -87,17 +167,21 @@ export interface AppConfigBuild { /** * Specify the HTML template renderer to be used for build * - * @default templateRenderer from '@vuepress/utils' + * @default `import { templateRenderer } from '@vuepress/utils'` */ templateBuildRenderer?: TemplateRenderer } /** - * Vuepress app config + * Vuepress app user config. + * + * It would be provided by user, typically via a config file. */ export type AppConfig = AppConfigBuild & AppConfigCommon & AppConfigDev /** - * Vuepress app options + * Vuepress app options that resolved from user config. + * + * It fills all optional fields with a default value. */ export type AppOptions = Required diff --git a/packages/core/src/types/app/utils.ts b/packages/core/src/types/app/utils.ts index 0e70eb5508..fdfb3fd4a7 100644 --- a/packages/core/src/types/app/utils.ts +++ b/packages/core/src/types/app/utils.ts @@ -7,11 +7,34 @@ export type AppDirFunction = (...args: string[]) => string * Directory utils */ export interface AppDir { + /** + * Resolve file path in cache directory + */ cache: AppDirFunction + + /** + * Resolve file path in temp directory + */ temp: AppDirFunction + + /** + * Resolve file path in source directory + */ source: AppDirFunction + + /** + * Resolve file path in dest directory + */ dest: AppDirFunction + + /** + * Resolve file path in public directory + */ public: AppDirFunction + + /** + * Resolve file path in client directory + */ client: AppDirFunction } diff --git a/packages/core/src/types/bundler.ts b/packages/core/src/types/bundler.ts index cd3b8dc2a7..0f8e64fa78 100644 --- a/packages/core/src/types/bundler.ts +++ b/packages/core/src/types/bundler.ts @@ -8,8 +8,19 @@ import type { App } from './app/index.js' * - build: bundle assets for deployment */ export interface Bundler { + /** + * Name of the bundler + */ name: string + + /** + * Method to run vuepress app in dev mode, starting dev server + */ dev: (app: App) => Promise<() => Promise> + + /** + * Method to run vuepress app in build mode, generating static pages and assets + */ build: (app: App) => Promise } diff --git a/packages/core/src/types/plugin.ts b/packages/core/src/types/plugin.ts index ae52a6b334..99e65f7517 100644 --- a/packages/core/src/types/plugin.ts +++ b/packages/core/src/types/plugin.ts @@ -27,10 +27,14 @@ export type PluginFunction = ( * Vuepress plugin object */ export interface PluginObject extends Partial { - // plugin name + /** + * Name of the plugin + */ name: string - // allow use a plugin multiple times or not + /** + * Allow the plugin to be used multiple times or not + */ multiple?: boolean }