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 =>