0
# Core Parsing
1

2
Core parsing functionality for extracting React component documentation from source code using Babel AST analysis.
3

4
## Capabilities
5

6
### Main Parse Function
7

8
The primary function for parsing React component source code and extracting documentation.
9

10
```typescript { .api }
11
/**
12
 * Parse the source code and scan for react components based on the config
13
 * The default resolvers look for exported react components.
14
 * By default all handlers are applied, covering all possible use cases.
15
 * The default importer is the fs-importer that resolves files using Node.js resolution.
16
 */
17
function parse(src: Buffer | string, config?: Config): Documentation[];
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { parse } from "react-docgen";
24

25
// Basic parsing with default configuration
26
const componentCode = `
27
export default function Button({ label, onClick }) {
28
  return <button onClick={onClick}>{label}</button>;
29
}
30
`;
31

32
const documentation = parse(componentCode);
33

34
// Parsing with custom configuration
35
const docs = parse(componentCode, {
36
  handlers: [/* custom handlers */],
37
  resolver: /* custom resolver */,
38
  filename: '/path/to/component.jsx'
39
});
40
```
41

42
### Documentation Interface
43

44
The structured documentation object returned by the parser.
45

46
```typescript { .api }
47
interface Documentation {
48
  /** Child context types defined by the component */
49
  childContext?: Record<string, PropDescriptor>;
50
  /** Array of HOC or mixin names this component composes */
51
  composes?: string[];
52
  /** Context types consumed by the component */
53
  context?: Record<string, PropDescriptor>;
54
  /** Component description from JSDoc comments */
55
  description?: string;
56
  /** Display name of the component */
57
  displayName?: string;
58
  /** Array of component methods with their signatures */
59
  methods?: MethodDescriptor[];
60
  /** Component props with type information and descriptions */
61
  props?: Record<string, PropDescriptor>;
62
}
63
```
64

65
### Error Handling
66

67
React-docgen provides specific error types for different parsing scenarios.
68

69
```typescript { .api }
70
enum ERROR_CODES {
71
  MISSING_DEFINITION = 'ERR_REACTDOCGEN_MISSING_DEFINITION',
72
  MULTIPLE_DEFINITIONS = 'ERR_REACTDOCGEN_MULTIPLE_DEFINITIONS'
73
}
74
```
75

76
**Usage Example:**
77

78
```typescript
79
import { parse, ERROR_CODES } from "react-docgen";
80

81
try {
82
  const docs = parse(sourceCode);
83
} catch (error) {
84
  // Errors thrown during parsing are standard Error objects
85
  // Check error message to determine error type
86
  console.error("Parsing failed:", error.message);
87
}
88
```
89

90
### Built-in Collections
91

92
Pre-configured collections of handlers, resolvers, and importers for common use cases.
93

94
```typescript { .api }
95
/** Collection of all available built-in handlers */
96
const builtinHandlers: {
97
  componentDocblockHandler: Handler;
98
  componentMethodsHandler: Handler;
99
  componentMethodsJsDocHandler: Handler;
100
  defaultPropsHandler: Handler;
101
  displayNameHandler: Handler;
102
  codeTypeHandler: Handler;
103
  propDocblockHandler: Handler;
104
  propTypeCompositionHandler: Handler;
105
  propTypeHandler: Handler;
106
  contextTypeHandler: Handler;
107
  childContextTypeHandler: Handler;
108
};
109

110
/** Collection of all available built-in resolvers */
111
const builtinResolvers: {
112
  FindAllDefinitionsResolver: ResolverClass;
113
  FindAnnotatedDefinitionsResolver: ResolverClass;
114
  FindExportedDefinitionsResolver: ResolverClass;
115
  ChainResolver: ResolverClass;
116
};
117

118
/** Collection of all available built-in importers */
119
const builtinImporters: {
120
  fsImporter: Importer;
121
  ignoreImporter: Importer;
122
};
123

124
/** Default set of handlers used by the parser */
125
const defaultHandlers: Handler[];
126
```
127

128
### File State Management
129

130
Internal file state management during parsing and import resolution.
131

132
```typescript { .api }
133
class FileState {
134
  /** Parse method for handling imports and module resolution */
135
  parse: (src: string, config: Config) => Documentation[];
136
  /** Import method for resolving module dependencies */
137
  import: (path: ImportPath, name: string) => NodePath | null;
138
}
139
```
140

141
### Type Definitions
142

143
Core type definitions used throughout the parsing system.
144

145
```typescript { .api }
146
interface PropDescriptor {
147
  /** PropType information extracted from prop-types */
148
  type?: PropTypeDescriptor;
149
  /** Flow type information when available */
150
  flowType?: TypeDescriptor<FunctionSignatureType>;
151
  /** TypeScript type information when available */
152
  tsType?: TypeDescriptor<TSFunctionSignatureType>;
153
  /** Whether the prop is required */
154
  required?: boolean;
155
  /** Default value if specified */
156
  defaultValue?: DefaultValueDescriptor;
157
  /** JSDoc description of the prop */
158
  description?: string;
159
}
160

161
interface MethodDescriptor {
162
  /** Method name */
163
  name: string;
164
  /** JSDoc description */
165
  description?: string | null;
166
  /** Raw JSDoc comment block */
167
  docblock: string | null;
168
  /** Method modifiers (async, static, etc.) */
169
  modifiers: MethodModifier[];
170
  /** Method parameters */
171
  params: MethodParameter[];
172
  /** Return type information */
173
  returns: MethodReturn | null;
174
}
175

176
interface MethodParameter {
177
  /** Parameter name */
178
  name: string;
179
  /** Parameter description from JSDoc */
180
  description?: string;
181
  /** Whether parameter is optional */
182
  optional: boolean;
183
  /** Parameter type information */
184
  type?: TypeDescriptor<FunctionSignatureType> | null;
185
}
186

187
type MethodModifier = 'async' | 'generator' | 'get' | 'set' | 'static';
188

189
interface DefaultValueDescriptor {
190
  /** The default value */
191
  value: unknown;
192
  /** Whether the value was computed or literal */
193
  computed: boolean;
194
}
195
```