react-docgen

react-docgen

Version 8.0.0
Published 2 months ago
231 kB
10 dependencies
MIT license

Install

npm i react-docgen

yarn add react-docgen

pnpm add react-docgen

Overview

A library to extract information from React components for documentation generation.

Index

Variables

variable builtinImporters

const builtinImporters: { fsImporter: Importer; ignoreImporter: Importer };

variable defaultHandlers

const defaultHandlers: Handler[];

Functions

function makeFsImporter

makeFsImporter: (
    lookupModule?: (filename: string, basedir: string) => string,
    { parseCache, resolveCache }?: FsImporterCache
) => Importer;

function parse

parse: (src: Buffer | string, config?: Config) => Documentation[];

Parse the *src* and scan for react components based on the config that gets supplied.
The default resolvers look for *exported* react components.
By default all handlers are applied, so that all possible different use cases are covered.
The default importer is the fs-importer that tries to resolve files based on the nodejs resolve algorithm.

Classes

class DocumentationBuilder

class DocumentationBuilder {}

constructor

constructor();

method addComposes

addComposes: (moduleName: string) => void;

method build

build: () => Documentation;

method get

get: <T>(key: string) => T | null;

method getChildContextDescriptor

getChildContextDescriptor: (propName: string) => PropDescriptor;

method getContextDescriptor

getContextDescriptor: (propName: string) => PropDescriptor;

method getPropDescriptor

getPropDescriptor: (propName: string) => PropDescriptor;

method set

set: (key: string, value: unknown) => void;

class FileState

class FileState {}

constructor

constructor(
    options: TransformOptions,
    { code, ast, importer }: { code: string; ast: File; importer: Importer }
);

property ast

ast: File;

property code

code: string;

property hub

hub: HubInterface;

property opts

opts: TransformOptions;

property path

path: NodePath<Program>;

property scope

scope: Scope;

method import

import: (path: NodePath<any>, name: string) => NodePath | null;

Try to resolve and import the ImportPath with the name

method parse

parse: (code: string, filename: string) => FileState;

Parse the content of a new file The filename is required so that potential imports inside the content can be correctly resolved and the correct babel config file could be loaded. filename needs to be an absolute path.

method traverse

traverse: {
    <S>(visitors: Visitor<S>, state?: S): void;
    (visitors: Visitor): void;
};

Interfaces

interface BaseType

interface BaseType {}

property alias

alias?: string;

property nullable

nullable?: boolean;

property required

required?: boolean;

interface Config

interface Config {}

property babelOptions

babelOptions?: TransformOptions;

property filename

filename?: string;

shortcut for babelOptions.filename Set to an absolute path (recommended) to the file currently being parsed or to an relative path that is relative to the babelOptions.cwd.

property handlers

handlers?: Handler[];

property importer

importer?: Importer;

property resolver

resolver?: Resolver;

interface Documentation

interface Documentation {}

property childContext

childContext?: Record<string, PropDescriptor>;

property composes

composes?: string[];

property context

context?: Record<string, PropDescriptor>;

property description

description?: string;

property displayName

displayName?: string;

property methods

methods?: MethodDescriptor[];

property props

props?: Record<string, PropDescriptor>;

interface ElementsType

interface ElementsType<T = FunctionSignatureType> extends BaseType {}

property elements

elements: Array<TypeDescriptor<T>>;

property name

name: string;

property raw

raw: string;

interface FunctionArgumentType

interface FunctionArgumentType<T> {}

property name

name: string;

property rest

rest?: boolean;

property type

type?: TypeDescriptor<T>;

interface FunctionSignatureType

interface FunctionSignatureType extends BaseType {}

property name

name: 'signature';

property raw

raw: string;

property signature

signature: {
    arguments: Array<FunctionArgumentType<FunctionSignatureType>>;
    return?: TypeDescriptor<FunctionSignatureType>;
};

property type

type: 'function';

interface LiteralType

interface LiteralType extends BaseType {}

property name

name: 'literal';

property value

value: string;

interface MethodParameter

interface MethodParameter {}

property description

description?: string;

property name

name: string;

property optional

optional: boolean;

property type

type?: TypeDescriptor<FunctionSignatureType> | null;

interface MethodReturn

interface MethodReturn {}

property description

description?: string;

property type

type: TypeDescriptor<FunctionSignatureType> | undefined;

interface ObjectSignatureType

interface ObjectSignatureType<T = FunctionSignatureType> extends BaseType {}

property name

name: 'signature';

property raw

raw: string;

property signature

signature: {
    properties: Array<{
        key: TypeDescriptor<T> | string;
        value: TypeDescriptor<T>;
        description?: string;
    }>;
    constructor?: TypeDescriptor<T>;
};

property type

type: 'object';

interface PropDescriptor

interface PropDescriptor {}

property defaultValue

defaultValue?: DefaultValueDescriptor;

property description

description?: string;

property flowType

flowType?: TypeDescriptor<FunctionSignatureType>;

property required

required?: boolean;

property tsType

tsType?: TypeDescriptor<TSFunctionSignatureType>;

property type

type?: PropTypeDescriptor;

interface PropTypeDescriptor

interface PropTypeDescriptor {}

property computed

computed?: boolean;

property description

description?: string;

property name

name:
    | 'any'
    | 'array'
    | 'arrayOf'
    | 'bool'
    | 'custom'
    | 'element'
    | 'elementType'
    | 'enum'
    | 'exact'
    | 'func'
    | 'instanceOf'
    | 'node'
    | 'number'
    | 'object'
    | 'objectOf'
    | 'shape'
    | 'string'
    | 'symbol'
    | 'union';

property raw

raw?: string;

property required

required?: boolean;

property value

value?: unknown;

interface ResolverClass

interface ResolverClass {}

property resolve

resolve: ResolverFunction;

interface SimpleType

interface SimpleType extends BaseType {}

property name

name: string;

property raw

raw?: string;

interface TSFunctionSignatureType

interface TSFunctionSignatureType extends FunctionSignatureType {}

property signature

signature: {
    arguments: Array<FunctionArgumentType<TSFunctionSignatureType>>;
    return?: TypeDescriptor<TSFunctionSignatureType>;
    this?: TypeDescriptor<TSFunctionSignatureType>;
};

Enums

enum ERROR_CODES

enum ERROR_CODES {
    MISSING_DEFINITION = 'ERR_REACTDOCGEN_MISSING_DEFINITION',
    MULTIPLE_DEFINITIONS = 'ERR_REACTDOCGEN_MULTIPLE_DEFINITIONS',
}

member MISSING_DEFINITION

MISSING_DEFINITION = 'ERR_REACTDOCGEN_MISSING_DEFINITION'

member MULTIPLE_DEFINITIONS

MULTIPLE_DEFINITIONS = 'ERR_REACTDOCGEN_MULTIPLE_DEFINITIONS'

Type Aliases

type Handler

type Handler = (
    documentation: Documentation,
    componentDefinition: NodePath<ComponentNode>
) => void;

type Importer

type Importer = (path: ImportPath, name: string, file: FileState) => NodePath | null;

type Resolver

type Resolver = ResolverClass | ResolverFunction;

type ResolverFunction

type ResolverFunction = (file: FileState) => ComponentNodePath[];

type TypeDescriptor

type TypeDescriptor<T = FunctionSignatureType> =
    | ElementsType<T>
    | LiteralType
    | ObjectSignatureType<T>
    | SimpleType
    | T;

Namespaces

namespace builtinHandlers

module 'dist/handlers/index.d.ts' {}

variable childContextTypeHandler

const childContextTypeHandler: Handler;

variable codeTypeHandler

const codeTypeHandler: Handler;

This handler tries to find flow and TS Type annotated react components and extract its types to the documentation. It also extracts docblock comments which are inlined in the type definition.

variable componentDocblockHandler

const componentDocblockHandler: Handler;

Finds the nearest block comment before the component definition.

variable componentMethodsHandler

const componentMethodsHandler: Handler;

Extract all flow types for the methods of a react component. Doesn't return any react specific lifecycle methods.

variable componentMethodsJsDocHandler

const componentMethodsJsDocHandler: Handler;

Extract info from the methods jsdoc blocks. Must be run after componentMethodsHandler.

variable contextTypeHandler

const contextTypeHandler: Handler;

variable defaultPropsHandler

const defaultPropsHandler: Handler;

variable displayNameHandler

const displayNameHandler: Handler;

variable propDocblockHandler

const propDocblockHandler: Handler;

variable propTypeCompositionHandler

const propTypeCompositionHandler: Handler;

variable propTypeHandler

const propTypeHandler: Handler;

type Handler

type Handler = (
    documentation: Documentation,
    componentDefinition: NodePath<ComponentNode>
) => void;

namespace builtinResolvers

module 'dist/resolver/index.d.ts' {}

class ChainResolver

class ChainResolver implements ResolverClass {}

constructor

constructor(resolvers: Resolver[], options: ChainResolverOptions);

property Logic

static Logic: typeof ChainingLogic;

property options

options: ChainResolverOptions;

property resolvers

resolvers: Resolver[];

method resolve

resolve: (file: FileState) => ComponentNodePath[];

class FindAllDefinitionsResolver

class FindAllDefinitionsResolver implements ResolverClass {}

Given an AST, this function tries to find all object expressions that are passed to React.createClass calls, by resolving all references properly.

method resolve

resolve: (file: FileState) => ComponentNodePath[];

class FindAnnotatedDefinitionsResolver

class FindAnnotatedDefinitionsResolver implements ResolverClass {}

Given an AST, this function tries to find all react components which are annotated with an annotation

constructor

constructor({ annotation }?: FindAnnotatedDefinitionsResolverOptions);

property annotation

annotation: string;

method resolve

resolve: (file: FileState) => ComponentNodePath[];

class FindExportedDefinitionsResolver

class FindExportedDefinitionsResolver implements ResolverClass {}

Given an AST, this function tries to find the exported component definitions.
The component definitions are either the ObjectExpression passed to React.createClass or a class definition extending React.Component or having a render() method.
If a definition is part of the following statements, it is considered to be exported:
modules.exports = Definition; exports.foo = Definition; export default Definition; export var Definition = ...;
limit can be used to limit the components to be found. When the limit is reached an error will be thrown

constructor

constructor({ limit }?: FindExportedDefinitionsResolverOptions);

property limit

limit: number;

method resolve

resolve: (file: FileState) => ComponentNodePath[];

interface ResolverClass

interface ResolverClass {}

property resolve

resolve: ResolverFunction;

type ComponentNode

type ComponentNode =
    | CallExpression
    | ClassDeclaration
    | ClassExpression
    | ObjectExpression
    | StatelessComponentNode;

type ComponentNodePath

type ComponentNodePath = NodePath<ComponentNode>;

type Resolver

type Resolver = ResolverClass | ResolverFunction;

type ResolverFunction

type ResolverFunction = (file: FileState) => ComponentNodePath[];

type StatelessComponentNode

type StatelessComponentNode =
    | ArrowFunctionExpression
    | FunctionDeclaration
    | FunctionExpression
    | ObjectMethod;

namespace utils

module 'dist/utils/index.d.ts' {}

variable COMPUTED_PREFIX

const COMPUTED_PREFIX: string;

function applyToTypeProperties

applyToTypeProperties: (
    documentation: Documentation,
    path: NodePath,
    callback: (propertyPath: NodePath, params: TypeParameters | null) => void,
    typeParams: TypeParameters | null
) => void;

function findFunctionReturn

findFunctionReturn: <T extends NodePath = NodePath>(
    path: NodePath,
    predicate: Predicate<T>
) => T | undefined;

This can be used in two ways 1. Find the first return path that passes the predicate function (for example to check if a function is returning something) 2. Find all occurrences of return values For this the predicate acts more like a collector and always needs to return false

function getClassMemberValuePath

getClassMemberValuePath: (
    classDefinition: NodePath<any>,
    memberName: string
) => NodePath<ClassMethod | Expression> | null;

function getFlowType

getFlowType: (
    path: NodePath<FlowType>,
    typeParams?: TypeParameters | null
) => TypeDescriptor;

Tries to identify the flow type by inspecting the path for known flow type names. This method doesn't check whether the found type is actually existing. It simply assumes that a match is always valid.
If there is no match, "unknown" is returned.

function getMemberExpressionRoot

getMemberExpressionRoot: (
    memberExpressionPath: NodePath<MemberExpression>
) => NodePath<Expression>;

Returns the path to the first part of the MemberExpression. I.e. given a path representing
foo.bar.baz
it returns the path of/to foo.

function getMemberExpressionValuePath

getMemberExpressionValuePath: (
    variableDefinition: NodePath,
    memberName: string
) => NodePath<Expression> | null;

function getMembers

getMembers: (path: NodePath, includeRoot?: boolean) => MemberDescriptor[];

Given a "nested" Member/CallExpression, e.g.
foo.bar()[baz][42]
this returns a list of "members". In this example it would be something like [ {path: NodePath, arguments: NodePath, computed: false}, {path: NodePath, arguments: null, computed: true}, {path: NodePath<42>, arguments: null, computed: false} ]

function getMemberValuePath

getMemberValuePath: (
    componentDefinition: NodePath<any>,
    memberName: string
) => NodePath<ClassMethod | Expression | ObjectMethod> | null;

This is a helper method for handlers to make it easier to work either with an ObjectExpression from React.createClass class or with a class definition.
Given a path and a name, this function will either return the path of the property value if the path is an ObjectExpression, or the value of the ClassProperty/MethodDefinition if it is a class definition (declaration or expression).
It also normalizes the names so that e.g. defaultProps and getDefaultProps can be used interchangeably.

function getMethodDocumentation

getMethodDocumentation: (
    methodPath: MethodNodePath,
    options?: { isStatic?: boolean }
) => MethodDescriptor | null;

function getNameOrValue

getNameOrValue: (path: NodePath) => boolean | number | string | null;

If node is an Identifier, it returns its name. If it is a literal, it returns its value.

function getParameterName

getParameterName: (parameterPath: NodePath<any>) => string;

function getPropertyName

getPropertyName: (propertyPath: NodePath<any>) => string | null;

In an ObjectExpression, the name of a property can either be an identifier or a literal (or dynamic, but we don't support those). This function simply returns the value of the literal or name of the identifier.

function getPropertyValuePath

getPropertyValuePath: (
    path: NodePath<ObjectExpression>,
    propertyName: string
) => NodePath<Expression | ObjectMethod> | null;

Given an ObjectExpression, this function returns the path of the value of the property with name propertyName. if the property is an ObjectMethod we return the ObjectMethod itself.

function getPropType

getPropType: (path: NodePath) => PropTypeDescriptor;

Tries to identify the prop type by inspecting the path for known prop type names. This method doesn't check whether the found type is actually from React.PropTypes. It simply assumes that a match has the same meaning as the React.PropTypes one.
If there is no match, "custom" is returned.

function getTSType

getTSType: (
    path: NodePath<TypeScript>,
    typeParamMap?: TypeParameters | null
) => TypeDescriptor<TSFunctionSignatureType>;

Tries to identify the typescript type by inspecting the path for known typescript type names. This method doesn't check whether the found type is actually existing. It simply assumes that a match is always valid.
If there is no match, "unknown" is returned.

function getTypeAnnotation

getTypeAnnotation: <T extends Node = any>(
    path: NodePath<any>
) => NodePath<T> | null;

Gets the most inner valuable TypeAnnotation from path. If no TypeAnnotation can be found null is returned

function getTypeFromReactComponent

getTypeFromReactComponent: (componentDefinition: NodePath) => NodePath[];

Given an React component (stateless or class) tries to find flow or TS types for the props. It may find multiple types. If not found or it is not one of the supported component types, this function returns an empty array.

function getTypeIdentifier

getTypeIdentifier: (path: NodePath) => NodePath | null;

function getTypeParameters

getTypeParameters: (
    declaration: NodePath<any>,
    instantiation: NodePath<any>,
    inputParams: TypeParameters | null | undefined
) => TypeParameters;

function isDestructuringAssignment

isDestructuringAssignment: (path: NodePath, name: string) => boolean;

Checks if the input Identifier is part of a destructuring Assignment and the name of the property key matches the input name

function isExportsOrModuleAssignment

isExportsOrModuleAssignment: (path: NodePath) => boolean;

Returns true if the expression is of form exports.foo = ...; or modules.exports = ...;.

function isImportSpecifier

isImportSpecifier: (path: NodePath, name: string) => boolean;

Checks if the path is a ImportSpecifier that imports the given named export

function isReactBuiltinCall

isReactBuiltinCall: (path: NodePath, name: string) => path is NodePath<any>;

Returns true if the expression is a function call of the form React.foo(...).

function isReactBuiltinReference

isReactBuiltinReference: (path: NodePath, name: string) => boolean;

Returns true if the expression is a reference to a react export.

function isReactChildrenElementCall

isReactChildrenElementCall: (path: NodePath) => path is NodePath<any>;

Returns true if the expression is a function call of the form React.Children.only(...) or React.Children.map(...).

function isReactCloneElementCall

isReactCloneElementCall: (path: NodePath) => path is NodePath<any>;

Returns true if the expression is a function call of the form React.cloneElement(...).

function isReactComponentClass

isReactComponentClass: (path: NodePath) => path is NodePath<any>;

Returns true of the path represents a class definition which either extends React.Component or has a superclass and implements a render() method.

function isReactComponentMethod

isReactComponentMethod: (methodPath: NodePath) => boolean;

Returns if the method path is a Component method.

function isReactCreateClassCall

isReactCreateClassCall: (path: NodePath) => path is NodePath<any>;

Returns true if the expression is a function call of the form React.createClass(...) or
import createReactClass from 'create-react-class'; createReactClass(...);

function isReactCreateElementCall

isReactCreateElementCall: (path: NodePath) => path is NodePath<any>;

Returns true if the expression is a function call of the form React.createElement(...).

function isReactForwardRefCall

isReactForwardRefCall: (path: NodePath) => path is NodePath<any>;

Returns true if the expression is a function call of the form React.forwardRef(...).

function isReactModuleName

isReactModuleName: (moduleName: string) => boolean;

Takes a module name (string) and returns true if it refers to a root react module name.

function isRequiredPropType

isRequiredPropType: (path: NodePath) => boolean;

Returns true of the prop is required, according to its type definition

function isStatelessComponent

isStatelessComponent: (path: NodePath) => path is NodePath<any>;

Returns true if the path represents a function which returns a JSXElement

function isSupportedDefinitionType

isSupportedDefinitionType: (path: NodePath) => path is NodePath<any>;

function isUnreachableFlowType

isUnreachableFlowType: (path: NodePath) => boolean;

Returns true of the path is an unreachable TypePath This evaluates the NodePaths returned from resolveToValue

function normalizeClassDefinition

normalizeClassDefinition: (classDefinition: NodePath<any>) => void;

Given a class definition (i.e. class declaration or expression), this function "normalizes" the definition, by looking for assignments of static properties and converting them to ClassProperties.
Example:
class MyComponent extends React.Component { // ... } MyComponent.propTypes = { ... };
is converted to
class MyComponent extends React.Component { // ... static propTypes = { ... }; }

function parseJsDoc

parseJsDoc: (docblock: string) => JsDoc;

function postProcessDocumentation

postProcessDocumentation: (documentation: Documentation) => Documentation;

function printValue

printValue: (path: NodePath) => string;

Prints the given path without leading or trailing comments.

function resolveExportDeclaration

resolveExportDeclaration: (path: NodePath<any>) => NodePath[];

function resolveFunctionDefinitionToReturnValue

resolveFunctionDefinitionToReturnValue: (
    path: NodePath<BabelFunction>
) => NodePath<Expression> | null;

function resolveGenericTypeAnnotation

resolveGenericTypeAnnotation: (path: NodePath) => NodePath | undefined;

Given an React component (stateless or class) tries to find the flow or ts type for the props. If not found or not one of the supported component types returns undefined.

function resolveHOC

resolveHOC: (path: NodePath) => NodePath;

If the path is a call expression, it recursively resolves to the rightmost argument, stopping if it finds a React.createClass call expression
Else the path itself is returned.

function resolveObjectKeysToArray

resolveObjectKeysToArray: (path: NodePath) => string[] | null;

Returns an ArrayExpression which contains all the keys resolved from an object
Ignores setters in objects
Returns null in case of unresolvable spreads computed identifier keys

function resolveObjectPatternPropertyToValue

resolveObjectPatternPropertyToValue: (
    path: NodePath<ObjectProperty>
) => NodePath | null;

Resolve and ObjectProperty inside an ObjectPattern to its value if possible If not found null is returned

function resolveObjectToNameArray

resolveObjectToNameArray: (
    objectPath: NodePath,
    raw?: boolean
) => string[] | null;

function resolveObjectValuesToArray

resolveObjectValuesToArray: (path: NodePath) => string[] | null;

Returns an ArrayExpression which contains all the values resolved from an object
Ignores setters in objects
Returns null in case of unresolvable spreads computed identifier values

function resolveToModule

resolveToModule: (path: NodePath) => string | null;

Given a path (e.g. call expression, member expression or identifier), this function tries to find the name of module from which the "root value" was imported.

function resolveToValue

resolveToValue: (path: NodePath) => NodePath;

If the path is an identifier, it is resolved in the scope chain. If it is an assignment expression, it resolves to the right hand side. If it is a member expression it is resolved to it's initialization value.
Else the path itself is returned.

function setPropDescription

setPropDescription: (
    documentation: Documentation,
    propertyPath: NodePath<any>
) => void;

type MethodNodePath

type MethodNodePath =
    | NodePath<AssignmentExpression>
    | NodePath<ClassMethod>
    | NodePath<ClassPrivateMethod>
    | NodePath<ClassProperty>
    | NodePath<ObjectMethod>
    | NodePath<ObjectProperty>;

type TypeParameters

type TypeParameters = Record<string, NodePath>;

namespace docblock

module 'dist/utils/docblock.d.ts' {}

Helper functions to work with docblock comments.

function getDocblock

getDocblock: (path: NodePath, trailing?: boolean) => string | null;

Given a path, this function returns the closest preceding docblock if it exists.

function getDoclets

getDoclets: (str: string) => Record<string, string>;

Given a string, this functions returns an object with doclet names as keys and their "content" as values.

namespace expressionTo

module 'dist/utils/expressionTo.d.ts' {}

Splits a MemberExpression or CallExpression into parts. E.g. foo.bar.baz becomes ['foo', 'bar', 'baz']

function Array

Array: (path: NodePath<any>) => string[];

Splits a MemberExpression or CallExpression into parts. E.g. foo.bar.baz becomes ['foo', 'bar', 'baz']

function String

String: (path: NodePath<any>) => string;

Creates a string representation of a member expression.

namespace flowUtilityTypes

module 'dist/utils/flowUtilityTypes.d.ts' {}

See supportedUtilityTypes for which types are supported and https://flow.org/en/docs/types/utilities/ for which types are available.

function isSupportedUtilityType

isSupportedUtilityType: (
    path: NodePath
) => path is NodePath<GenericTypeAnnotation>;

See supportedUtilityTypes for which types are supported and https://flow.org/en/docs/types/utilities/ for which types are available.

function unwrapUtilityType

unwrapUtilityType: (path: NodePath) => NodePath;

Unwraps well known utility types. For example:
$ReadOnly => T

namespace traverse

module 'dist/utils/traverse.d.ts' {}

variable shallowIgnoreVisitors

const shallowIgnoreVisitors: {
    FunctionDeclaration: { enter: typeof ignore };
    FunctionExpression: { enter: typeof ignore };
    Class: { enter: typeof ignore };
    IfStatement: { enter: typeof ignore };
    WithStatement: { enter: typeof ignore };
    SwitchStatement: { enter: typeof ignore };
    CatchClause: { enter: typeof ignore };
    Loop: { enter: typeof ignore };
    ExportNamedDeclaration: { enter: typeof ignore };
    ExportDefaultDeclaration: { enter: typeof ignore };
    ConditionalExpression: { enter: typeof ignore };
};

function ignore

ignore: <T>(path: NodePath<T>) => void;

Package Files (75)

Dependencies (10)

Dev Dependencies (0)

No dev dependencies.

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/react-docgen.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/react-docgen)

HTML

<a href="https://www.jsdocs.io/package/react-docgen"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 1 month ago.
Package analyzed in 4589 ms.
Missing or incorrect documentation? Open an issue for this package.