docs: add examples (#127)

package.json

@@ -82,8 +82,9 @@
 		"sentences-per-line": "^0.2.1",
 		"should-semantic-release": "^0.0.4",
 		"tsup": "^6.5.0",
-		"typedoc": "^0.23.25",
+		"typedoc": "^0.23.26",
 		"typedoc-plugin-coverage": "^2.0.0",
+		"typedoc-plugin-custom-validation": "^1.1.0",
 		"typedoc-plugin-mdn-links": "^2.0.2",
 		"typedoc-plugin-versions": "^0.2.3",
 		"typescript": "4.9.5",

src/comments.ts

@@ -67,6 +67,15 @@ export type ForEachCommentCallback = (
  * Iterates over all comments owned by `node` or its children.
  *
  * @category Nodes - Other Utilities
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * tsutils.forEachComment(node, (fullText, comment) => {
+ *    console.log(`Found comment at position ${comment.pos}: '${fullText}'.`);
+ * });
+ * ```
  */
 export function forEachComment(
 	node: ts.Node,

src/compilerOptions.ts

@@ -23,6 +23,16 @@ export type BooleanCompilerOptions = keyof {
  * This function only handles boolean flags.
  *
  * @category Compiler Options
+ *
+ * @example
+ * ```ts
+ * const options = {
+ * 	allowJs: true,
+ * };
+ *
+ * isCompilerOptionEnabled(options, "allowJs"); // true
+ * isCompilerOptionEnabled(options, "allowSyntheticDefaultImports"); // false
+ * ```
  */
 export function isCompilerOptionEnabled(
 	options: ts.CompilerOptions,
@@ -105,6 +115,27 @@ export type StrictCompilerOption =
  * (except `strictPropertyInitialization`) have been enabled by `strict: true`.
  *
  * @category Compiler Options
+ *
+ * @example
+ * ```ts
+ * const optionsLenient = {
+ * 	noImplicitAny: true,
+ * };
+ *
+ * isStrictCompilerOptionEnabled(optionsLenient, "noImplicitAny"); // true
+ * isStrictCompilerOptionEnabled(optionsLenient, "noImplicitThis"); // false
+ * ```
+ *
+ * @example
+ * ```ts
+ * const optionsStrict = {
+ * 	noImplicitThis: false,
+ * 	strict: true,
+ * };
+ *
+ * isStrictCompilerOptionEnabled(optionsStrict, "noImplicitAny"); // true
+ * isStrictCompilerOptionEnabled(optionsStrict, "noImplicitThis"); // false
+ * ```
  */
 export function isStrictCompilerOptionEnabled(
 	options: ts.CompilerOptions,

src/flags.ts

@@ -25,6 +25,15 @@ function isFlagSetOnObject(obj: { flags: number }, flag: number): boolean {
  * Test if the given node has the given `ModifierFlags` set.
  *
  * @category Nodes - Flag Utilities
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isModifierFlagSet(node, ts.ModifierFlags.Abstract)) {
+ *   // ...
+ * }
+ * ```
  */
 export function isModifierFlagSet(
 	node: ts.Declaration,
@@ -37,6 +46,15 @@ export function isModifierFlagSet(
  * Test if the given node has the given `NodeFlags` set.
  *
  * @category Nodes - Flag Utilities
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isNodeFlagSet(node, ts.NodeFlags.AwaitContext)) {
+ *   // ...
+ * }
+ * ```
  */
 export const isNodeFlagSet: (node: ts.Node, flag: ts.NodeFlags) => boolean =
 	isFlagSetOnObject;
@@ -45,6 +63,15 @@ export const isNodeFlagSet: (node: ts.Node, flag: ts.NodeFlags) => boolean =
  * Test if the given node has the given `ObjectFlags` set.
  *
  * @category Nodes - Flag Utilities
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isObjectFlagSet(node, ts.ObjectFlags.Anonymous)) {
+ *   // ...
+ * }
+ * ```
  */
 export function isObjectFlagSet(
 	objectType: ts.ObjectType,
@@ -57,6 +84,15 @@ export function isObjectFlagSet(
  * Test if the given node has the given `SymbolFlags` set.
  *
  * @category Nodes - Flag Utilities
+ *
+ * @example
+ * ```ts
+ * declare const symbol: ts.Symbol;
+ *
+ * if (isSymbolFlagSet(symbol, ts.SymbolFlags.Accessor)) {
+ *   // ...
+ * }
+ * ```
  */
 export const isSymbolFlagSet: (
 	symbol: ts.Symbol,
@@ -67,6 +103,15 @@ export const isSymbolFlagSet: (
  * Test if the given node has the given `TypeFlags` set.
  *
  * @category Nodes - Flag Utilities
+ *
+ * @example
+ * ```ts
+ * declare const type: ts.Type;
+ *
+ * if (isTypeFlagSet(type, ts.TypeFlags.Any)) {
+ *   // ...
+ * }
+ * ```
  */
 export const isTypeFlagSet: (type: ts.Type, flag: ts.TypeFlags) => boolean =
 	isFlagSetOnObject;

src/modifiers.ts

@@ -7,6 +7,13 @@ import * as ts from "typescript";
  * Test if the given iterable includes a modifier of any of the given kinds.
  *
  * @category Modifier Utilities
+ *
+ * @example
+ * ```ts
+ * declare const modifiers: ts.Modifier[];
+ *
+ * hasModifier(modifiers, ts.SyntaxKind.AbstractKeyword);
+ * ```
  */
 export function includesModifier(
 	modifiers: Iterable<ts.Modifier> | undefined,

src/nodes/typeGuards/compound.ts

@@ -32,6 +32,16 @@ export type ConstAssertionIdentifier = ts.Identifier & {
  * Test if a node is a {@link ConstAssertionExpression}.
  *
  * @category Nodes - Type Guards
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isConstAssertionExpression(node)) {
+ *   // ...
+ * }
+ * ```
+ *
  * @returns Whether the given node appears to be a {@link ConstAssertionExpression}.
  */
 export function isConstAssertionExpression(
@@ -48,6 +58,16 @@ export function isConstAssertionExpression(
  * Test if a node is an `IterationStatement`.
  *
  * @category Nodes - Type Guards
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isIterationStatement(node)) {
+ *   // ...
+ * }
+ * ```
+ *
  * @returns Whether the given node appears to be an `IterationStatement`.
  */
 export function isIterationStatement(
@@ -69,6 +89,16 @@ export function isIterationStatement(
  * Test if a node is a `JSDocNamespaceDeclaration`.
  *
  * @category Nodes - Type Guards
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isJSDocNamespaceDeclaration(node)) {
+ *   // ...
+ * }
+ * ```
+ *
  * @returns Whether the given node appears to be a `JSDocNamespaceDeclaration`.
  */
 export function isJSDocNamespaceDeclaration(
@@ -85,6 +115,16 @@ export function isJSDocNamespaceDeclaration(
  * Test if a node is a `JsxTagNamePropertyAccess`.
  *
  * @category Nodes - Type Guards
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isJsxTagNamePropertyAccess(node)) {
+ *   // ...
+ * }
+ * ```
+ *
  * @returns Whether the given node appears to be a `JsxTagNamePropertyAccess`.
  */
 export function isJsxTagNamePropertyAccess(
@@ -109,6 +149,16 @@ export interface NamedDeclarationWithName extends ts.NamedDeclaration {
  * Test if a node is a {@link NamedDeclarationWithName}.
  *
  * @category Nodes - Type Guards
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isNamedDeclarationWithName(node)) {
+ *   // ...
+ * }
+ * ```
+ *
  * @returns Whether the given node appears to be a {@link NamedDeclarationWithName}.
  */
 export function isNamedDeclarationWithName(
@@ -126,6 +176,16 @@ export function isNamedDeclarationWithName(
  * Test if a node is a `NamespaceDeclaration`.
  *
  * @category Nodes - Type Guards
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isNamespaceDeclaration(node)) {
+ *   // ...
+ * }
+ * ```
+ *
  * @returns Whether the given node appears to be a `NamespaceDeclaration`.
  */
 export function isNamespaceDeclaration(
@@ -152,6 +212,16 @@ export type NumericOrStringLikeLiteral =
  * Test if a node is a {@link NumericOrStringLikeLiteral}.
  *
  * @category Nodes - Type Guards
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isNumericOrStringLikeLiteral(node)) {
+ *   // ...
+ * }
+ * ```
+ *
  * @returns Whether the given node appears to be a {@link NumericOrStringLikeLiteral}.
  */
 export function isNumericOrStringLikeLiteral(
@@ -171,6 +241,16 @@ export function isNumericOrStringLikeLiteral(
  * Test if a node is a `PropertyAccessEntityNameExpression`.
  *
  * @category Nodes - Type Guards
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isPropertyAccessEntityNameExpression(node)) {
+ *   // ...
+ * }
+ * ```
+ *
  * @returns Whether the given node appears to be a `PropertyAccessEntityNameExpression`.
  */
 export function isPropertyAccessEntityNameExpression(
@@ -187,6 +267,16 @@ export function isPropertyAccessEntityNameExpression(
  * Test if a node is a `SuperElementAccessExpression`.
  *
  * @category Nodes - Type Guards
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isSuperElementAccessExpression(node)) {
+ *   // ...
+ * }
+ * ```
+ *
  * @returns Whether the given node appears to be a `SuperElementAccessExpression`.
  */
 export function isSuperElementAccessExpression(
@@ -201,6 +291,16 @@ export function isSuperElementAccessExpression(
  * Test if a node is a `SuperPropertyAccessExpression`.
  *
  * @category Nodes - Type Guards
+ *
+ * @example
+ * ```ts
+ * declare const node: ts.Node;
+ *
+ * if (isSuperPropertyAccessExpression(node)) {
+ *   // ...
+ * }
+ * ```
+ *
  * @returns Whether the given node appears to be a `SuperPropertyAccessExpression`.
  */
 export function isSuperPropertyAccessExpression(