Write JSDoc comments and inline documentation for Valibot library source code in /library/src/. Use when documenting schemas, actions, methods, or utilities. Covers interface documentation, function overloads, purity annotations, inline comment patterns, and terminology consistency.
Documentation patterns for library source code in /library/src/.
/**
* String issue interface.
*/
export interface StringIssue extends BaseIssue<unknown> {
/**
* The issue kind.
*/
readonly kind: 'schema';
/**
* The issue type.
*/
readonly type: 'string';
}
Rules:
[Name] [category] interface. (e.g., "String issue interface.")The [description]. (always start with "The", end with period)readonlyEach overload gets its own complete JSDoc:
/**
* Creates a string schema.
*
* @returns A string schema.
*/
export function string(): StringSchema<undefined>;
/**
* Creates a string schema.
*
* @param message The error message.
*
* @returns A string schema.
*/
export function string<
const TMessage extends ErrorMessage<StringIssue> | undefined,
>(message: TMessage): StringSchema<TMessage>;
Rules:
Creates a [name] [category]. (use "a" vs "an" correctly)@param name The [description]. (start with "The", end with period)@returns A [name] [category]. or @returns The [description].Add hints after the main description, before @param:
/**
* Creates an object schema.
*
* Hint: This schema removes unknown entries. To include unknown entries, use
* `looseObject`. To reject unknown entries, use `strictObject`.
*
* @param entries The entries schema.
*
* @returns An object schema.
*/
Link to external resources when relevant using markdown format:
/**
* Creates an [email](https://en.wikipedia.org/wiki/Email_address) validation action.
*/
The implementation has NO JSDoc but uses // @__NO_SIDE_EFFECTS__:
// @__NO_SIDE_EFFECTS__
export function string(
message?: ErrorMessage<StringIssue>
): StringSchema<ErrorMessage<StringIssue> | undefined> {
return {
/* ... */
};
}
// @__NO_SIDE_EFFECTS__ rules:
_addIssue)/**
* Stringifies an unknown input to a literal or type string.
*
* @param input The unknown input.
*
* @returns A literal or type string.
*
* @internal
*/
// @__NO_SIDE_EFFECTS__
export function _stringify(input: unknown): string {
// ...
}
Rules:
@internal tag for internal utilities_// @__NO_SIDE_EFFECTS__ if function is pure'~run'(dataset, config) {
// Get input value from dataset
const input = dataset.value;
// If root type is valid, check nested types
if (Array.isArray(input)) {
// Set typed to true and value to empty array
dataset.typed = true;
dataset.value = [];
// Parse schema of each array item
for (let key = 0; key < input.length; key++) {
// ...
}
}
}
Rules:
// If root type is valid, check nested types
if (input && typeof input === 'object') {
// ...
}
// Otherwise, add issue
else {
_addIssue(this, 'type', dataset, config);
}
Rules:
// Hint: The issue is deliberately not constructed with the spread operator
// for performance reasons
const issue: BaseIssue<unknown> = {
/* ... */
};
Rules:
// TODO: Should we add "n" suffix to bigints?
if (type === 'bigint') {
/* ... */
}
Used for internal dataset mutations TypeScript can't track:
// @ts-expect-error
dataset.typed = true;
string.ts, object.ts, etc.)// @__NO_SIDE_EFFECTS__'~run' method containing inline commentsemail.ts, minLength.ts, etc.)// @__NO_SIDE_EFFECTS__parse.ts, pipe.ts, etc.)More complex logic, require more inline comments.
_addIssue.ts, _stringify.ts)@internal// @__NO_SIDE_EFFECTS__ only if pureJSDoc descriptions must match the kind property if present:
kind Property | JSDoc Wording |
|---|---|
'schema' | "Creates a ... schema." |
'validation' | "Creates a ... validation action." |
'transformation' | "Creates a ... transformation action." |
| Type | Pattern |
|---|---|
| Interface | [Name] [category] interface. |
| Type | [Name] [category] type. |
| Function | Creates a [name] [category]. |
| Utility | [Verb]s [description]. |
| Pattern | Example |
|---|---|
// Get [what] | // Get input value from dataset |
// If [condition], [action] | // If root type is valid, check nested types |
// Otherwise, [action] | // Otherwise, add issue |
// Create [what] | // Create object path item |
// Add [what] to [where] | // Add issues to dataset |
// Parse [what] | // Parse schema of each array item |
// Set [property] to [value] | // Set typed to true |
// Hint: [explanation] | // Hint: This is for performance |
// TODO: [task] | // TODO: Add bigint suffix |
Use consistently:
[Name] [category] interface.The [description].// @__NO_SIDE_EFFECTS__@__NO_SIDE_EFFECTS__@internal tag