chore(core): improve type comments and replace internal with private

vuepress · Sep 12, 2024 · 4c064e3 · 4c064e3
1 parent b37b2cc
commit 4c064e3
Show file tree

Hide file tree

Showing 46 changed files with 170 additions and 47 deletions.
diff --git 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
@@ -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<void> => {
   log('init start')

diff --git 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<void> => {
   log('prepare start')

diff --git 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
@@ -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
@@ -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<void> => {
   // plugin hook: clientConfigFile

diff --git 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<void> => {
   // page chunk file content

diff --git 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
@@ -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
@@ -18,7 +18,7 @@ if (import.meta.hot) {
 /**
  * Generate site data temp file
  *
- * @internal
+ * @private
  */
 export const prepareSiteData = async (app: App): Promise<void> => {
   let content = `\

diff --git 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
@@ -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
@@ -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<Markdown> => {
   // plugin hook: extendsMarkdownOptions

diff --git 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
@@ -7,7 +7,7 @@ const log = debug('vuepress:core/app')
 /**
  * Resolve pages for vuepress app
  *
- * @internal
+ * @private
  */
 export const resolveAppPages = async (app: App): Promise<Page[]> => {
   log('resolveAppPages start')

diff --git 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
@@ -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
@@ -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
@@ -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 = <T extends PluginObject = PluginObject>(
   app: App,

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -11,7 +11,7 @@ const log = debug('vuepress:core/plugin-api')
 /**
  * Create hook queue for plugin system
  *
- * @internal
+ * @private
  */
 export const createHookQueue = <T extends HooksName>(name: T): HookQueue<T> => {
   const items: HookItem<T>[] = []

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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'] =>