tessl/npm-react-docgen

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Information Extraction

Name: tessl/npm-react-docgen
Author: tessl

Handlers that extract specific types of information from React components during the parsing process.

Capabilities

Handler Interface

The base interface for all information extraction handlers.

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

Handlers receive a Documentation object (to populate) and a ComponentNodePath (to analyze), and modify the documentation object in place.

Component Docblock Handler

Extracts JSDoc comments and descriptions from the component definition.

const componentDocblockHandler: Handler;

Extracted Information:

Component description from JSDoc comments
@deprecated tags
@since tags
Other JSDoc annotations

Usage Example:

// Input component:
/**
 * A reusable button component for user interactions
 * @deprecated Use Button2 instead
 */
export default function Button(props) {
  return <button {...props} />;
}

// Extracted documentation:
{
  description: "A reusable button component for user interactions",
  // Additional JSDoc metadata
}

Display Name Handler

Extracts the display name of the component from various sources.

const displayNameHandler: Handler;

Sources for Display Name:

Explicit displayName property
Function/class name
Variable name in assignments
Export name

Usage Example:

// Various display name sources:
function MyButton() {} // displayName: "MyButton"
const Button = () => {}; // displayName: "Button"
export { Button as PrimaryButton }; // displayName: "PrimaryButton"

Button.displayName = "CustomButton"; // displayName: "CustomButton"

Prop Type Handler

Extracts PropTypes definitions and converts them to documentation format.

const propTypeHandler: Handler;

Supported PropTypes:

Basic types (string, number, bool, array, object, func, node, element)
Complex types (arrayOf, objectOf, oneOf, oneOfType, shape, exact)
Custom validators
Required props using .isRequired

Usage Example:

import PropTypes from 'prop-types';

function Button({ label, onClick, size }) {
  return <button onClick={onClick}>{label}</button>;
}

Button.propTypes = {
  label: PropTypes.string.isRequired,
  onClick: PropTypes.func,
  size: PropTypes.oneOf(['small', 'medium', 'large'])
};

// Extracted documentation includes detailed prop information

Default Props Handler

Extracts default prop values from various definition patterns.

const defaultPropsHandler: Handler;

Supported Patterns:

Component.defaultProps assignments
ES6 default parameters
Default values in destructuring

Usage Example:

// defaultProps assignment
Button.defaultProps = {
  size: 'medium',
  disabled: false
};

// ES6 default parameters
function Button({ label, size = 'medium', disabled = false }) {}

// Both patterns are extracted to defaultValue in PropDescriptor

Code Type Handler

Extracts TypeScript and Flow type information from component definitions.

const codeTypeHandler: Handler;

Supported Type Systems:

TypeScript interfaces and types
Flow type annotations
Generic type parameters
Union and intersection types

Usage Example:

interface ButtonProps {
  /** Button label text */
  label: string;
  /** Click handler function */
  onClick?: () => void;
  /** Button size variant */
  size?: 'small' | 'medium' | 'large';
}

function Button({ label, onClick, size }: ButtonProps) {
  return <button onClick={onClick}>{label}</button>;
}

// Extracts complete TypeScript type information

Component Methods Handler

Extracts class component methods and their signatures.

const componentMethodsHandler: Handler;

Extracted Information:

Method names and signatures
Parameter types and names
Return types
Method modifiers (static, async, etc.)

Usage Example:

class MyComponent extends React.Component {
  /**
   * Handles user click events
   */
  handleClick = (event) => {
    // Method implementation
  };

  /**
   * Validates component props
   */
  static validateProps(props) {
    return props.isValid;
  }

  render() {
    return <div onClick={this.handleClick} />;
  }
}

// Extracts method information including JSDoc

Component Methods JSDoc Handler

Extracts JSDoc documentation specifically from component methods.

const componentMethodsJsDocHandler: Handler;

Extracted Information:

Method descriptions
Parameter documentation with @param tags
Return value documentation with @returns tags
Method-specific JSDoc tags

Prop Docblock Handler

Extracts JSDoc comments associated with individual props.

const propDocblockHandler: Handler;

Usage Example:

Button.propTypes = {
  /** The text to display on the button */
  label: PropTypes.string.isRequired,
  /** Function called when button is clicked */
  onClick: PropTypes.func,
  /** Visual size of the button */
  size: PropTypes.oneOf(['small', 'medium', 'large'])
};

// Extracts individual prop descriptions

Prop Type Composition Handler

Handles composed PropTypes and HOC prop inheritance patterns.

const propTypeCompositionHandler: Handler;

Handles:

PropTypes composition with Object.assign
HOC prop merging patterns
Mixin prop inheritance

Context Type Handlers

Extract React context information from components.

const contextTypeHandler: Handler;
const childContextTypeHandler: Handler;

Extracted Information:

Context types consumed by the component
Child context types provided by the component
Context property descriptions

Usage Example:

class MyComponent extends React.Component {
  static contextTypes = {
    theme: PropTypes.object.isRequired
  };

  static childContextTypes = {
    locale: PropTypes.string
  };

  getChildContext() {
    return { locale: 'en-US' };
  }
}

// Extracts context type information

Default Handler Configuration

The default set of handlers used by the parser.

const defaultHandlers: Handler[];

The default handlers include (in order):

propTypeHandler - Extract PropTypes
contextTypeHandler - Extract context types
childContextTypeHandler - Extract child context types
propTypeCompositionHandler - Handle prop composition
propDocblockHandler - Extract prop JSDoc
codeTypeHandler - Extract TypeScript/Flow types
defaultPropsHandler - Extract default values
componentDocblockHandler - Extract component JSDoc
displayNameHandler - Extract display name
componentMethodsHandler - Extract methods
componentMethodsJsDocHandler - Extract method JSDoc

Custom Handler Development

Handlers are functions that modify the Documentation object based on AST analysis.

Handler Implementation Example:

import type { Handler } from "react-docgen";

const customHandler: Handler = (documentation, componentDefinition) => {
  // Analyze the componentDefinition AST node
  // Extract specific information
  // Modify the documentation object
  
  documentation.set('customField', extractedValue);
};

// Usage with custom handler
const docs = parse(sourceCode, {
  handlers: [...defaultHandlers, customHandler]
});

Install with Tessl CLI