0
# Component Documentation
1

2
Comprehensive documentation structures for React components, including props, methods, and metadata extracted from TypeScript definitions.
3

4
## Capabilities
5

6
### ComponentDoc Interface
7

8
The main documentation object returned for each React component.
9

10
```typescript { .api }
11
/**
12
 * Complete documentation for a React component
13
 */
14
interface ComponentDoc {
15
  /** TypeScript symbol reference (when shouldIncludeExpression is true) */
16
  expression?: ts.Symbol;
17
  /** Root TypeScript symbol reference (when shouldIncludeExpression is true) */
18
  rootExpression?: ts.Symbol;
19
  /** Component display name */
20
  displayName: string;
21
  /** Path to the component source file */
22
  filePath: string;
23
  /** Component description from JSDoc comments */
24
  description: string;
25
  /** Component props documentation */
26
  props: Props;
27
  /** Component methods documentation */
28
  methods: Method[];
29
  /** JSDoc tags as key-value pairs */
30
  tags?: StringIndexedObject<string>;
31
}
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
import { parse } from "react-docgen-typescript";
38

39
const [componentDoc] = parse("./src/Button.tsx");
40

41
console.log(componentDoc.displayName); // "Button"
42
console.log(componentDoc.description); // "A reusable button component"
43
console.log(componentDoc.filePath); // "./src/Button.tsx"
44
console.log(Object.keys(componentDoc.props)); // ["variant", "size", "onClick", ...]
45
```
46

47
### Props Documentation
48

49
Documentation for component properties and their types.
50

51
```typescript { .api }
52
/**
53
 * String-indexed object containing PropItem entries
54
 */
55
interface Props extends StringIndexedObject<PropItem> {}
56

57
/**
58
 * Documentation for a single component property
59
 */
60
interface PropItem {
61
  /** Property name */
62
  name: string;
63
  /** Whether the property is required */
64
  required: boolean;
65
  /** Property type information */
66
  type: PropItemType;
67
  /** Property description from JSDoc comments */
68
  description: string;
69
  /** Default value if specified */
70
  defaultValue: any;
71
  /** Parent interface/type information */
72
  parent?: ParentType;
73
  /** Type declaration locations */
74
  declarations?: ParentType[];
75
  /** JSDoc tags for this property */
76
  tags?: {};
77
}
78

79
/**
80
 * Type information for a property
81
 */
82
interface PropItemType {
83
  /** Type name (string representation) */
84
  name: string;
85
  /** Type value for enums/unions */
86
  value?: any;
87
  /** Raw TypeScript type string */
88
  raw?: string;
89
}
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
import { parse } from "react-docgen-typescript";
96

97
const [componentDoc] = parse("./src/Button.tsx");
98

99
// Access prop information
100
const variantProp = componentDoc.props.variant;
101
console.log(variantProp.name); // "variant"
102
console.log(variantProp.required); // false
103
console.log(variantProp.type.name); // "primary" | "secondary" | "danger"
104
console.log(variantProp.description); // "Button style variant"
105
console.log(variantProp.defaultValue); // { value: "primary" }
106

107
// Enumerate all props
108
Object.entries(componentDoc.props).forEach(([propName, propInfo]) => {
109
  console.log(`${propName}: ${propInfo.type.name} (required: ${propInfo.required})`);
110
});
111
```
112

113
### Method Documentation
114

115
Documentation for component methods (class components and ref-exposed methods).
116

117
```typescript { .api }
118
/**
119
 * Method documentation for class components
120
 */
121
interface Method {
122
  /** Method name */
123
  name: string;
124
  /** Full JSDoc comment block */
125
  docblock: string;
126
  /** Method modifiers (static, etc.) */
127
  modifiers: string[];
128
  /** Method parameters */
129
  params: MethodParameter[];
130
  /** Return type information */
131
  returns?: {
132
    description?: string | null;
133
    type?: string;
134
  } | null;
135
  /** Method description from JSDoc */
136
  description: string;
137
}
138

139
/**
140
 * Method parameter information
141
 */
142
interface MethodParameter {
143
  /** Parameter name */
144
  name: string;
145
  /** Parameter description from JSDoc */
146
  description?: string | null;
147
  /** Parameter type */
148
  type: MethodParameterType;
149
}
150

151
/**
152
 * Method parameter type information
153
 */
154
interface MethodParameterType {
155
  /** Type name */
156
  name: string;
157
}
158
```
159

160
**Usage Examples:**
161

162
```typescript
163
import { parse } from "react-docgen-typescript";
164

165
// Parse a class component with methods
166
const [componentDoc] = parse("./src/Modal.tsx");
167

168
// Access method information
169
componentDoc.methods.forEach(method => {
170
  console.log(`Method: ${method.name}`);
171
  console.log(`Description: ${method.description}`);
172
  console.log(`Modifiers: ${method.modifiers.join(', ')}`);
173
  
174
  method.params.forEach(param => {
175
    console.log(`  Param: ${param.name} (${param.type.name})`);
176
  });
177
  
178
  if (method.returns) {
179
    console.log(`  Returns: ${method.returns.type}`);
180
  }
181
});
182
```
183

184
### Type Information
185

186
Supporting type definitions for component documentation.
187

188
```typescript { .api }
189
/**
190
 * Parent type information for props
191
 */
192
interface ParentType {
193
  /** Parent type/interface name */
194
  name: string;
195
  /** File path containing the type definition */
196
  fileName: string;
197
}
198

199
/**
200
 * Component identifier interface
201
 */
202
interface Component {
203
  /** Component name */
204
  name: string;
205
}
206

207
/**
208
 * Generic string-indexed object type
209
 */
210
interface StringIndexedObject<T> {
211
  [key: string]: T;
212
}
213
```
214

215
## Prop Type Handling
216

217
### Union Types
218

219
When `shouldExtractValuesFromUnion` is enabled, union types are converted to enum format:
220

221
```typescript
222
// TypeScript definition
223
type ButtonVariant = "primary" | "secondary" | "danger";
224

225
// Resulting PropItemType
226
{
227
  name: "enum",
228
  raw: "\"primary\" | \"secondary\" | \"danger\"",
229
  value: [
230
    { value: "\"primary\"" },
231
    { value: "\"secondary\"" },
232
    { value: "\"danger\"" }
233
  ]
234
}
235
```
236

237
### Enum Types
238

239
When `shouldExtractLiteralValuesFromEnum` is enabled, string enums are extracted:
240

241
```typescript
242
// TypeScript definition
243
enum Size {
244
  Small = "sm",
245
  Medium = "md", 
246
  Large = "lg"
247
}
248

249
// Resulting PropItemType
250
{
251
  name: "enum",
252
  raw: "Size",
253
  value: [
254
    { value: "\"sm\"" },
255
    { value: "\"md\"" },
256
    { value: "\"lg\"" }
257
  ]
258
}
259
```
260

261
### Default Values
262

263
Default values are captured from various sources:
264

265
```typescript
266
// From defaultProps
267
Component.defaultProps = {
268
  variant: "primary",
269
  size: "medium"
270
};
271

272
// From JSDoc @default tag
273
/**
274
 * @param variant Button variant
275
 * @default "primary"
276
 */
277

278
// From destructuring defaults
279
const MyComponent = ({ variant = "primary" }) => { ... };
280
```
281

282
## Error Handling
283

284
Component documentation extraction handles various edge cases:
285

286
- **Missing Props Interface**: Components without explicit props return empty props object
287
- **Unresolvable Types**: Complex types fall back to string representation
288
- **Missing JSDoc**: Empty descriptions are returned for undocumented components
289
- **Invalid Components**: Non-component exports are filtered out automatically