0
# JSDoc Processing
1

2
Comprehensive JSDoc parsing system that extracts structured information from component documentation comments, supporting parameter descriptions, return types, deprecation notices, and type information.
3

4
## Capabilities
5

6
### JSDoc Parsing
7

8
The main parsing function that processes JSDoc comments and extracts structured documentation information.
9

10
```typescript { .api }
11
/**
12
 * Parses JSDoc comments and extracts structured information
13
 * @param value - JSDoc comment string or null
14
 * @param options - Parsing configuration options
15
 * @returns Structured parsing result with extracted information
16
 */
17
function parseJsDoc(
18
  value: string | null, 
19
  options?: JsDocParsingOptions
20
): JsDocParsingResult;
21

22
interface JsDocParsingOptions {
23
  /** JSDoc tags to extract (defaults to common tags) */
24
  tags?: string[];
25
}
26

27
interface JsDocParsingResult {
28
  /** Whether the input contained JSDoc formatting */
29
  includesJsDoc: boolean;
30
  /** Whether the component should be ignored (@ignore tag) */
31
  ignore: boolean;
32
  /** Cleaned description text with JSDoc removed */
33
  description?: string;
34
  /** Extracted JSDoc tag information */
35
  extractedTags?: ExtractedJsDoc;
36
}
37
```
38

39
The parser supports standard JSDoc tags including `@param`, `@arg`, `@argument`, `@returns`, `@ignore`, and `@deprecated`.
40

41
**Usage Examples:**
42

43
```typescript
44
import { parseJsDoc } from "@storybook/docs-tools";
45

46
// Basic JSDoc parsing
47
const jsDocString = `
48
  Main component description here.
49
  
50
  @param name - The user's name
51
  @param age - The user's age in years  
52
  @param options - Configuration options
53
  @returns JSX element representing the user
54
  @deprecated Use UserCardV2 instead
55
`;
56

57
const result = parseJsDoc(jsDocString);
58
console.log(result);
59
// {
60
//   includesJsDoc: true,
61
//   ignore: false,
62
//   description: "Main component description here.",
63
//   extractedTags: {
64
//     params: [
65
//       { name: "name", description: "The user's name", ... },
66
//       { name: "age", description: "The user's age in years", ... },
67
//       { name: "options", description: "Configuration options", ... }
68
//     ],
69
//     returns: { description: "JSX element representing the user", ... },
70
//     deprecated: "Use UserCardV2 instead"
71
//   }
72
// }
73

74
// Custom tag filtering
75
const customResult = parseJsDoc(jsDocString, {
76
  tags: ['param', 'returns']  // Only extract param and returns tags
77
});
78

79
// Handling ignored components
80
const ignoredJsDoc = `
81
  This component is internal only.
82
  @ignore
83
`;
84

85
const ignoredResult = parseJsDoc(ignoredJsDoc);
86
console.log(ignoredResult.ignore); // true
87
```
88

89
### Extracted JSDoc Structure
90

91
Detailed interfaces for the structured information extracted from JSDoc comments.
92

93
```typescript { .api }
94
interface ExtractedJsDoc {
95
  /** Parameter information from @param, @arg, @argument tags */
96
  params?: ExtractedJsDocParam[] | null;
97
  /** Deprecation notice from @deprecated tag */
98
  deprecated?: string | null;
99
  /** Return information from @returns tag */
100
  returns?: ExtractedJsDocReturns | null;
101
  /** Whether component should be ignored (@ignore tag) */
102
  ignore: boolean;
103
}
104

105
interface ExtractedJsDocParam extends JsDocParam {
106
  /** Parsed type information */
107
  type?: any;
108
  /** Gets clean parameter name without trailing punctuation */
109
  getPrettyName: () => string | undefined;
110
  /** Gets formatted type name string */
111
  getTypeName: () => string | null;
112
}
113

114
interface ExtractedJsDocReturns extends JsDocReturns {
115
  /** Parsed return type information */
116
  type?: any;
117
  /** Gets formatted return type name string */
118
  getTypeName: () => string | null;
119
}
120
```
121

122
**Usage Examples:**
123

124
```typescript
125
// Working with extracted parameters
126
const processParams = (extractedTags: ExtractedJsDoc) => {
127
  if (extractedTags.params) {
128
    extractedTags.params.forEach(param => {
129
      const name = param.getPrettyName();
130
      const type = param.getTypeName();
131
      const description = param.description;
132
      
133
      console.log(`${name}: ${type} - ${description}`);
134
    });
135
  }
136
};
137

138
// Processing return type information
139
const processReturns = (extractedTags: ExtractedJsDoc) => {
140
  if (extractedTags.returns) {
141
    const returnType = extractedTags.returns.getTypeName();
142
    const description = extractedTags.returns.description;
143
    
144
    console.log(`Returns: ${returnType} - ${description}`);
145
  }
146
};
147

148
// Handling deprecation
149
const checkDeprecation = (extractedTags: ExtractedJsDoc) => {
150
  if (extractedTags.deprecated) {
151
    console.warn(`Deprecated: ${extractedTags.deprecated}`);
152
  }
153
};
154
```
155

156
### Base JSDoc Interfaces
157

158
Core interfaces that define the structure of JSDoc information.
159

160
```typescript { .api }
161
interface JsDocParam {
162
  /** Parameter name */
163
  name: string | undefined | null;
164
  /** Parameter description */
165
  description?: string | null;
166
}
167

168
interface JsDocReturns {
169
  /** Return value description */
170
  description?: string | null;
171
}
172

173
interface JsDocTags {
174
  /** Collection of parameter information */
175
  params?: JsDocParam[] | null;
176
  /** Return value information */
177
  returns?: JsDocReturns | null;
178
}
179
```
180

181
### Type Information Extraction
182

183
The JSDoc parser includes sophisticated type parsing capabilities for TypeScript-style type annotations.
184

185
```typescript
186
// Example JSDoc with type information
187
const typedJsDoc = `
188
  Process user data with validation.
189
  
190
  @param {string} name - User's full name
191
  @param {number|undefined} age - User's age, optional
192
  @param {{email: string, phone?: string}} contact - Contact information
193
  @returns {Promise<User>} Processed user object
194
`;
195

196
const typedResult = parseJsDoc(typedJsDoc);
197

198
// Access type information
199
const nameParam = typedResult.extractedTags?.params?.[0];
200
if (nameParam) {
201
  console.log(nameParam.getTypeName()); // "string"
202
}
203

204
const returnsInfo = typedResult.extractedTags?.returns;
205
if (returnsInfo) {
206
  console.log(returnsInfo.getTypeName()); // "Promise<User>"
207
}
208
```
209

210
### Integration with Component Systems
211

212
Common patterns for integrating JSDoc parsing with component documentation systems.
213

214
```typescript
215
import { parseJsDoc } from "@storybook/docs-tools";
216

217
// Process component docgen information
218
function processComponentDocs(component: any) {
219
  const docgenInfo = component.__docgenInfo;
220
  
221
  if (docgenInfo?.description) {
222
    const jsDocResult = parseJsDoc(docgenInfo.description);
223
    
224
    if (jsDocResult.ignore) {
225
      return null; // Skip ignored components
226
    }
227
    
228
    return {
229
      component,
230
      description: jsDocResult.description,
231
      jsDocTags: jsDocResult.extractedTags,
232
      deprecated: jsDocResult.extractedTags?.deprecated
233
    };
234
  }
235
  
236
  return { component };
237
}
238

239
// Enhance prop documentation with JSDoc
240
function enhancePropDocs(propName: string, propInfo: any) {
241
  const jsDocResult = parseJsDoc(propInfo.description);
242
  
243
  return {
244
    name: propName,
245
    ...propInfo,
246
    description: jsDocResult.description,
247
    jsDocTags: jsDocResult.extractedTags,
248
    ignore: jsDocResult.ignore
249
  };
250
}
251
```