3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-10 07:37:19 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(utils): JSDoc for all APIs (#6980)

Browse source 
* feat(utils): JSDoc for all APIs

* fix tests
This commit is contained in:
Joshua Chen 2022-03-24 21:34:31 +08:00 • committed by GitHub
parent b8d2a4e84d
commit 2eeb0e46a2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
31 changed files with 637 additions and 255 deletions
Download patch file Download diff file Expand all files Collapse all files

1
packages/docusaurus-utils-validation/package.json
View file

@ -20,6 +20,7 @@
"dependencies": {
"@docusaurus/logger": "2.0.0-beta.17",
"@docusaurus/utils": "2.0.0-beta.17",
"js-yaml": "^4.1.0",
"joi": "^17.6.0",
"tslib": "^2.3.1"
},

4
packages/docusaurus-utils-validation/src/JoiFrontMatter.ts
View file

@ -18,11 +18,13 @@ const JoiFrontMatterString: Joi.Extension = {
return {value};
},
};
/**
* Enhance the default Joi.string() type so that it can convert number to
* Enhance the default `Joi.string()` type so that it can convert number to
* strings. If user use front matter "tag: 2021", we shouldn't need to ask her
* to write "tag: '2021'". Also yaml tries to convert patterns like "2019-01-01"
* to dates automatically.
*
* @see https://github.com/facebook/docusaurus/issues/4642
* @see https://github.com/sideway/joi/issues/1442#issuecomment-823997884
*/

22
packages/docusaurus-utils-validation/src/validationUtils.ts
View file

@ -7,8 +7,10 @@
import type Joi from './Joi';
import logger from '@docusaurus/logger';
import Yaml from 'js-yaml';
import {PluginIdSchema} from './validationSchemas';
/** Print warnings returned from Joi validation. */
export function printWarning(warning?: Joi.ValidationError): void {
if (warning) {
const warningMessages = warning.details
@ -18,9 +20,14 @@ export function printWarning(warning?: Joi.ValidationError): void {
}
}
/**
* The callback that should be used to validate plugin options. Handles plugin
* IDs on a generic level: no matter what the schema declares, this callback
* would require a string ID or default to "default".
*/
export function normalizePluginOptions<T extends {id?: string}>(
schema: Joi.ObjectSchema<T>,
// This allows us to automatically normalize undefined to {id: 'default'}
// This allows us to automatically normalize undefined to { id: "default" }
options: Partial<T> = {},
): T {
// All plugins can be provided an "id" option (multi-instance support)
@ -41,6 +48,10 @@ export function normalizePluginOptions<T extends {id?: string}>(
return value;
}
/**
* The callback that should be used to validate theme config. No matter what the
* schema declares, this callback would allow unknown attributes.
*/
export function normalizeThemeConfig<T>(
schema: Joi.ObjectSchema<T>,
themeConfig: Partial<T>,
@ -62,6 +73,9 @@ export function normalizeThemeConfig<T>(
return value;
}
/**
* Validate front matter with better error message
*/
export function validateFrontMatter<T>(
frontMatter: Record<string, unknown>,
schema: Joi.ObjectSchema<T>,
@ -75,13 +89,13 @@ export function validateFrontMatter<T>(
printWarning(warning);
if (error) {
const frontMatterString = JSON.stringify(frontMatter, null, 2);
const errorDetails = error.details;
const invalidFields = errorDetails.map(({path}) => path).join(', ');
logger.error`The following front matter:
${logger.yellow(frontMatterString)}
contains invalid values for field(s): ${logger.yellow(invalidFields)}.
---
${Yaml.dump(frontMatter)}---
contains invalid values for field(s): code=${invalidFields}.
${errorDetails.map(({message}) => message)}
`;
throw error;