Skip to content

Commit

Permalink
refactor(core): improve comments
Browse files Browse the repository at this point in the history
  • Loading branch information
meteorlxy committed Sep 12, 2024
1 parent 017abb3 commit a0da533
Show file tree
Hide file tree
Showing 46 changed files with 227 additions and 9 deletions.
3 changes: 2 additions & 1 deletion e2e/docs/.vuepress/plugins/foo/fooPlugin.ts
Original file line number Diff line number Diff line change
@@ -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,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/appInit.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/appPrepare.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand Down
7 changes: 7 additions & 0 deletions packages/core/src/app/appUse.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
6 changes: 5 additions & 1 deletion packages/core/src/app/createBaseApp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion packages/core/src/app/createBuildApp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion packages/core/src/app/createDevApp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/prepare/prepareClientConfigs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/prepare/prepareRoutes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ if (import.meta.hot) {

/**
* Resolve page redirects
*
* @internal
*/
const resolvePageRedirects = ({ path, pathInferred }: Page): string[] => {
// paths that should redirect to this page, use set to dedupe
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/prepare/prepareSiteData.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ if (import.meta.hot) {

/**
* Generate site data temp file
*
* @internal
*/
export const prepareSiteData = async (app: App): Promise<void> => {
let content = `\
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/resolveAppDir.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ const require = createRequire(import.meta.url)

/**
* Create directory util function
*
* @internal
*/
export const createAppDirFunction =
(baseDir: string): AppDirFunction =>
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/resolveAppEnv.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/resolveAppMarkdown.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/resolveAppOptions.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ const require = createRequire(import.meta.url)

/**
* Create app options with default values
*
* @internal
*/
export const resolveAppOptions = ({
// site config
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/resolveAppPages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/resolveAppSiteData.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/resolveAppVersion.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ const require = createRequire(import.meta.url)

/**
* Resolve version of vuepress app
*
* @internal
*/
export const resolveAppVersion = (): string => {
const pkgJson = fs.readJsonSync(
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/resolveAppWriteTemp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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) => {
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/resolvePluginObject.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/resolveThemeInfo.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/app/setupAppThemeAndPlugins.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions packages/core/src/page/createPage.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/inferPagePath.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ import type { App } from '../types/index.js'

/**
* Infer page path according to file path
*
* @internal
*/
export const inferPagePath = ({
app,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/parsePageContent.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/renderPageSfcBlocksToVue.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ import type { MarkdownSfcBlocks } from '@vuepress/markdown'

/**
* Render page sfc blocks to vue component
*
* @internal
*/
export const renderPageSfcBlocksToVue = (
sfcBlocks: MarkdownSfcBlocks,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/resolvePageChunkInfo.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ import type { App } from '../types/index.js'

/**
* Resolve page data file path
*
* @internal
*/
export const resolvePageChunkInfo = ({
app,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/resolvePageComponentInfo.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ import type { App } from '../types/index.js'

/**
* Resolve page component and related info
*
* @internal
*/
export const resolvePageComponentInfo = ({
app,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/resolvePageContent.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ const FALLBACK_CONTENT = ''

/**
* Resolve page content according to `content` or `filePath`
*
* @internal
*/
export const resolvePageContent = async ({
filePath,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/resolvePageDate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/resolvePageFilePath.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/resolvePageHtmlInfo.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ import type { App } from '../types/index.js'

/**
* Resolve page rendered html file path
*
* @internal
*/
export const resolvePageHtmlInfo = ({
app,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/resolvePageLang.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ import type { App, PageFrontmatter } from '../types/index.js'

/**
* Resolve language of page
*
* @internal
*/
export const resolvePageLang = ({
app,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/resolvePagePath.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ import type { PageOptions } from '../types/index.js'

/**
* Resolve the final route path of a page
*
* @internal
*/
export const resolvePagePath = ({
permalink,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/resolvePagePermalink.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ import type { App, PageFrontmatter } from '../types/index.js'

/**
* Resolve page permalink from frontmatter / options / pattern
*
* @internal
*/
export const resolvePagePermalink = ({
app,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/resolvePageRouteMeta.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ import type { PageFrontmatter } from '../types/index.js'

/**
* Resolve page route meta
*
* @internal
*/
export const resolvePageRouteMeta = ({
frontmatter,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/page/resolvePageSlug.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/pluginApi/createHookQueue.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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>[] = []
Expand Down
5 changes: 5 additions & 0 deletions packages/core/src/pluginApi/createPluginApi.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
5 changes: 5 additions & 0 deletions packages/core/src/pluginApi/createPluginApiHooks.ts
Original file line number Diff line number Diff line change
@@ -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'),
Expand Down
5 changes: 5 additions & 0 deletions packages/core/src/pluginApi/createPluginApiRegisterHooks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'],
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/pluginApi/normalizeAliasDefineHook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'] =>
Expand Down
2 changes: 2 additions & 0 deletions packages/core/src/pluginApi/normalizeClientConfigFileHook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'] =>
Expand Down
Loading

0 comments on commit a0da533

Please sign in to comment.