refactor(core): improve comments

Author: meteorlxy

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,

packages/core/src/app/appInit.ts

@@ -9,6 +9,8 @@ const log = debug('vuepress:core/app')
  * Initialize a vuepress app
  *
  * Plugins should be used before initialization.
+ *
+ * @internal
  */
 export const appInit = async (app: App): Promise<void> => {
   log('init start')

packages/core/src/app/appPrepare.ts

@@ -18,6 +18,8 @@ const log = debug('vuepress:core/app')
  * - routes
  * - site data
  * - other files that generated by plugins
+ *
+ * @internal
  */
 export const appPrepare = async (app: App): Promise<void> => {
   log('prepare start')

packages/core/src/app/appUse.ts

@@ -4,6 +4,13 @@ import { resolvePluginObject } from './resolvePluginObject.js'
 
 const log = debug('vuepress:core/app')
 
+/**
+ * Use a plugin in vuepress app.
+ *
+ * Should be called before initialization.
+ *
+ * @internal
+ */
 export const appUse = (app: App, rawPlugin: Plugin): App => {
   const pluginObject = resolvePluginObject(app, rawPlugin)
 

packages/core/src/app/createBaseApp.ts

@@ -17,7 +17,11 @@ import { resolveAppWriteTemp } from './resolveAppWriteTemp.js'
 import { setupAppThemeAndPlugins } from './setupAppThemeAndPlugins.js'
 
 /**
- * Create vuepress app
+ * Create base vuepress app.
+ *
+ * Notice that the base app could not be used for dev nor build.
+ *
+ * It would be used for creating dev app or build app, or for testing.
  */
 export const createBaseApp = (config: AppConfig): App => {
   const options = resolveAppOptions(config)

packages/core/src/app/createBuildApp.ts

@@ -2,7 +2,7 @@ import type { AppConfig, BuildApp } from '../types/index.js'
 import { createBaseApp } from './createBaseApp.js'
 
 /**
- * Create vuepress build app
+ * Create vuepress build app.
  */
 export const createBuildApp = (config: AppConfig): BuildApp => {
   const app = createBaseApp(config) as BuildApp

packages/core/src/app/createDevApp.ts

@@ -2,7 +2,7 @@ import type { AppConfig, DevApp } from '../types/index.js'
 import { createBaseApp } from './createBaseApp.js'
 
 /**
- * Create vuepress dev app
+ * Create vuepress dev app.
  */
 export const createDevApp = (config: AppConfig): DevApp => {
   const app = createBaseApp(config) as DevApp

packages/core/src/app/prepare/prepareClientConfigs.ts

@@ -2,6 +2,8 @@ import type { App } from '../../types/index.js'
 
 /**
  * Generate client configs temp file
+ *
+ * @internal
  */
 export const prepareClientConfigs = async (app: App): Promise<void> => {
   // plugin hook: clientConfigFile

packages/core/src/app/prepare/prepareSiteData.ts

@@ -17,6 +17,8 @@ if (import.meta.hot) {
 
 /**
  * Generate site data temp file
+ *
+ * @internal
  */
 export const prepareSiteData = async (app: App): Promise<void> => {
   let content = `\

packages/core/src/app/resolveAppDir.ts

@@ -6,6 +6,8 @@ const require = createRequire(import.meta.url)
 
 /**
  * Create directory util function
+ *
+ * @internal
  */
 export const createAppDirFunction =
   (baseDir: string): AppDirFunction =>

packages/core/src/app/resolveAppEnv.ts

@@ -2,6 +2,8 @@ import type { AppEnv, AppOptions } from '../types/index.js'
 
 /**
  * Resolve environment flags for vuepress app
+ *
+ * @internal
  */
 export const resolveAppEnv = (options: AppOptions): AppEnv => ({
   isBuild: false,

packages/core/src/app/resolveAppMarkdown.ts

@@ -4,6 +4,8 @@ import type { App } from '../types/index.js'
 
 /**
  * Resolve markdown-it instance for vuepress app
+ *
+ * @internal
  */
 export const resolveAppMarkdown = async (app: App): Promise<Markdown> => {
   // plugin hook: extendsMarkdownOptions

packages/core/src/app/resolveAppOptions.ts

@@ -6,6 +6,8 @@ const require = createRequire(import.meta.url)
 
 /**
  * Create app options with default values
+ *
+ * @internal
  */
 export const resolveAppOptions = ({
   // site config

packages/core/src/app/resolveAppPages.ts

@@ -6,6 +6,8 @@ const log = debug('vuepress:core/app')
 
 /**
  * Resolve pages for vuepress app
+ *
+ * @internal
  */
 export const resolveAppPages = async (app: App): Promise<Page[]> => {
   log('resolveAppPages start')

packages/core/src/app/resolveAppSiteData.ts

@@ -4,6 +4,8 @@ import type { AppOptions, SiteData } from '../types/index.js'
  * Resolve site data for vuepress app
  *
  * Site data will also be used in client
+ *
+ * @internal
  */
 export const resolveAppSiteData = (options: AppOptions): SiteData => ({
   base: options.base,

packages/core/src/app/resolveAppVersion.ts

@@ -5,6 +5,8 @@ const require = createRequire(import.meta.url)
 
 /**
  * Resolve version of vuepress app
+ *
+ * @internal
  */
 export const resolveAppVersion = (): string => {
   const pkgJson = fs.readJsonSync(

packages/core/src/app/resolveAppWriteTemp.ts

@@ -3,6 +3,8 @@ import type { AppDir, AppWriteTemp } from '../types/index.js'
 
 /**
  * Resolve write temp file util for vuepress app
+ *
+ * @internal
  */
 export const resolveAppWriteTemp = (dir: AppDir): AppWriteTemp => {
   const writeTemp: AppWriteTemp = async (file: string, content: string) => {

packages/core/src/app/resolvePluginObject.ts

@@ -3,6 +3,8 @@ import type { App, Plugin, PluginObject } from '../types/index.js'
 
 /**
  * Resolve a plugin object according to name / path / module and config
+ *
+ * @internal
  */
 export const resolvePluginObject = <T extends PluginObject = PluginObject>(
   app: App,

packages/core/src/app/resolveThemeInfo.ts

@@ -3,6 +3,8 @@ import { resolvePluginObject } from './resolvePluginObject.js'
 
 /**
  * Resolve theme info and its parent theme info
+ *
+ * @internal
  */
 export const resolveThemeInfo = (app: App, theme: Theme): ThemeInfo => {
   // resolve current theme info

packages/core/src/app/setupAppThemeAndPlugins.ts

@@ -3,6 +3,8 @@ import { resolveThemeInfo } from './resolveThemeInfo.js'
 
 /**
  * Setup theme and plugins for vuepress app
+ *
+ * @internal
  */
 export const setupAppThemeAndPlugins = (app: App, config: AppConfig): void => {
   // recursively resolve theme info

packages/core/src/page/createPage.ts

@@ -13,6 +13,9 @@ import { resolvePagePermalink } from './resolvePagePermalink.js'
 import { resolvePageRouteMeta } from './resolvePageRouteMeta.js'
 import { resolvePageSlug } from './resolvePageSlug.js'
 
+/**
+ * Create vuepress page object
+ */
 export const createPage = async (
   app: App,
   options: PageOptions,

packages/core/src/page/inferPagePath.ts

@@ -7,6 +7,8 @@ import type { App } from '../types/index.js'
 
 /**
  * Infer page path according to file path
+ *
+ * @internal
  */
 export const inferPagePath = ({
   app,

packages/core/src/page/parsePageContent.ts

@@ -9,6 +9,8 @@ import type { App, PageFrontmatter, PageOptions } from '../types/index.js'
 
 /**
  * Render page content and extract related info
+ *
+ * @internal
  */
 export const parsePageContent = ({
   app,

packages/core/src/page/renderPageSfcBlocksToVue.ts

@@ -2,6 +2,8 @@ import type { MarkdownSfcBlocks } from '@vuepress/markdown'
 
 /**
  * Render page sfc blocks to vue component
+ *
+ * @internal
  */
 export const renderPageSfcBlocksToVue = (
   sfcBlocks: MarkdownSfcBlocks,

packages/core/src/page/resolvePageChunkInfo.ts

@@ -3,6 +3,8 @@ import type { App } from '../types/index.js'
 
 /**
  * Resolve page data file path
+ *
+ * @internal
  */
 export const resolvePageChunkInfo = ({
   app,

packages/core/src/page/resolvePageComponentInfo.ts

@@ -3,6 +3,8 @@ import type { App } from '../types/index.js'
 
 /**
  * Resolve page component and related info
+ *
+ * @internal
  */
 export const resolvePageComponentInfo = ({
   app,

packages/core/src/page/resolvePageContent.ts

@@ -9,6 +9,8 @@ const FALLBACK_CONTENT = ''
 
 /**
  * Resolve page content according to `content` or `filePath`
+ *
+ * @internal
  */
 export const resolvePageContent = async ({
   filePath,

packages/core/src/page/resolvePageDate.ts

@@ -10,6 +10,8 @@ const DEFAULT_DATE = '0000-00-00'
  * Resolve page date according to frontmatter or file path
  *
  * It will be resolved as 'yyyy-MM-dd' format
+ *
+ * @internal
  */
 export const resolvePageDate = ({
   frontmatter,

packages/core/src/page/resolvePageFilePath.ts

@@ -3,6 +3,8 @@ import type { App, PageOptions } from '../types/index.js'
 
 /**
  * Resolve absolute and relative path of page file
+ *
+ * @internal
  */
 export const resolvePageFilePath = ({
   app,

packages/core/src/page/resolvePageHtmlInfo.ts

@@ -3,6 +3,8 @@ import type { App } from '../types/index.js'
 
 /**
  * Resolve page rendered html file path
+ *
+ * @internal
  */
 export const resolvePageHtmlInfo = ({
   app,

packages/core/src/page/resolvePageLang.ts

@@ -3,6 +3,8 @@ import type { App, PageFrontmatter } from '../types/index.js'
 
 /**
  * Resolve language of page
+ *
+ * @internal
  */
 export const resolvePageLang = ({
   app,

packages/core/src/page/resolvePagePath.ts

@@ -3,6 +3,8 @@ import type { PageOptions } from '../types/index.js'
 
 /**
  * Resolve the final route path of a page
+ *
+ * @internal
  */
 export const resolvePagePath = ({
   permalink,

packages/core/src/page/resolvePagePermalink.ts

@@ -4,6 +4,8 @@ import type { App, PageFrontmatter } from '../types/index.js'
 
 /**
  * Resolve page permalink from frontmatter / options / pattern
+ *
+ * @internal
  */
 export const resolvePagePermalink = ({
   app,

packages/core/src/page/resolvePageRouteMeta.ts

@@ -2,6 +2,8 @@ import type { PageFrontmatter } from '../types/index.js'
 
 /**
  * Resolve page route meta
+ *
+ * @internal
  */
 export const resolvePageRouteMeta = ({
   frontmatter,

packages/core/src/page/resolvePageSlug.ts

@@ -4,6 +4,8 @@ const DATE_RE = /(\d{4}-\d{1,2}(-\d{1,2})?)-(.*)/
 
 /**
  * Resolve page slug from filename
+ *
+ * @internal
  */
 export const resolvePageSlug = ({
   filePathRelative,

packages/core/src/pluginApi/createHookQueue.ts

@@ -10,6 +10,8 @@ const log = debug('vuepress:core/plugin-api')
 
 /**
  * Create hook queue for plugin system
+ *
+ * @internal
  */
 export const createHookQueue = <T extends HooksName>(name: T): HookQueue<T> => {
   const items: HookItem<T>[] = []

packages/core/src/pluginApi/createPluginApi.ts

@@ -2,6 +2,11 @@ import type { PluginApi } from '../types/index.js'
 import { createPluginApiHooks } from './createPluginApiHooks.js'
 import { createPluginApiRegisterHooks } from './createPluginApiRegisterHooks.js'
 
+/**
+ * Create vuepress plugin api
+ *
+ * @internal
+ */
 export const createPluginApi = (): PluginApi => {
   const plugins: PluginApi['plugins'] = []
   const hooks = createPluginApiHooks()

packages/core/src/pluginApi/createPluginApiHooks.ts

@@ -1,6 +1,11 @@
 import type { PluginApi } from '../types/index.js'
 import { createHookQueue } from './createHookQueue.js'
 
+/**
+ * Create hooks for plugin api
+ *
+ * @internal
+ */
 export const createPluginApiHooks = (): PluginApi['hooks'] => ({
   // life cycle hooks
   onInitialized: createHookQueue('onInitialized'),

packages/core/src/pluginApi/createPluginApiRegisterHooks.ts

@@ -2,6 +2,11 @@ import type { PluginApi } from '../types/index.js'
 import { normalizeAliasDefineHook } from './normalizeAliasDefineHook.js'
 import { normalizeClientConfigFileHook } from './normalizeClientConfigFileHook.js'
 
+/**
+ * Create registerHooks method for plugin api
+ *
+ * @internal
+ */
 export const createPluginApiRegisterHooks =
   (
     plugins: PluginApi['plugins'],

packages/core/src/pluginApi/normalizeAliasDefineHook.ts

@@ -3,6 +3,8 @@ import type { AliasDefineHook } from '../types/index.js'
 
 /**
  * Normalize alias and define hook
+ *
+ * @internal
  */
 export const normalizeAliasDefineHook =
   (hook: AliasDefineHook['exposed']): AliasDefineHook['normalized'] =>

packages/core/src/pluginApi/normalizeClientConfigFileHook.ts

@@ -4,6 +4,8 @@ import type { ClientConfigFileHook } from '../types/index.js'
 
 /**
  * Normalize hook for client config file
+ *
+ * @internal
  */
 export const normalizeClientConfigFileHook =
   (hook: ClientConfigFileHook['exposed']): ClientConfigFileHook['normalized'] =>