0
# JSDoc Processing
1

2
Comprehensive JSDoc parsing, transformation, and generation system for maintaining Closure Compiler compatibility while preserving and enhancing documentation throughout the transformation process.
3

4
## Capabilities
5

6
### JSDoc Parsing
7

8
Functions for parsing JSDoc comments from TypeScript source code.
9

10
```typescript { .api }
11
/**
12
 * Parses JSDoc from synthesized comment
13
 */
14
function parse(comment: ts.SynthesizedComment): ParsedJSDocComment | null;
15

16
/**
17
 * Parses JSDoc from comment text
18
 */
19
function parseContents(commentText: string): ParsedJSDocComment | null;
20

21
interface ParsedJSDocComment {
22
  tags: Tag[];
23
  warnings?: string[];
24
}
25

26
interface Tag {
27
  tagName: string;
28
  parameterName?: string;
29
  type?: string;
30
  optional?: boolean;
31
  restParam?: boolean;
32
}
33
```
34

35
**Usage Example:**
36

37
```typescript
38
import { parse, parseContents } from "tsickle";
39

40
// Parse from comment range
41
const commentRange = { pos: 0, end: 50, kind: ts.SyntaxKind.MultiLineCommentTrivia };
42
const parsed = parse(commentRange);
43

44
// Parse from text directly
45
const jsDocText = "/** @param {string} name - The user name */";
46
const parsed2 = parseContents(jsDocText);
47

48
console.log(parsed2.tags); // [{ tagName: 'param', type: 'string', parameterName: 'name' }]
49
```
50

51
### JSDoc Generation
52

53
Functions for converting parsed tags back to JSDoc strings and comments.
54

55
```typescript { .api }
56
/**
57
 * Serializes tags to string
58
 */
59
function toString(tags: Tag[], escapeExtraTags?: boolean): string;
60

61
/**
62
 * Converts tags to synthesized comment
63
 */
64
function toSynthesizedComment(tags: Tag[], escapeExtraTags?: boolean): ts.SynthesizedComment;
65

66
/**
67
 * Merges multiple tag arrays
68
 */
69
function merge(tagLists: Tag[][]): Tag[];
70
```
71

72
**Usage Example:**
73

74
```typescript
75
import { toString, toSynthesizedComment, merge } from "tsickle";
76

77
const tags: Tag[] = [
78
  { tagName: 'param', type: 'string', parameterName: 'name' },
79
  { tagName: 'return', type: 'boolean' }
80
];
81

82
// Convert to string
83
const jsDocString = toString(tags);
84
// Result: "/**\n * @param {string} name\n * @return {boolean}\n */"
85

86
// Convert to synthesized comment for AST
87
const comment = toSynthesizedComment(tags);
88

89
// Merge multiple tag sets
90
const moreTags: Tag[] = [{ tagName: 'deprecated' }];
91
const merged = merge([tags, moreTags]);
92
```
93

94
### Comment Synthesis and Management
95

96
Functions for managing comments in the AST during transformation.
97

98
```typescript { .api }
99
/**
100
 * Creates synthetic leading comments for node
101
 */
102
function synthesizeLeadingComments(
103
  node: ts.Node,
104
  comments: SynthesizedCommentWithOriginal[]
105
): ts.Node;
106

107
/**
108
 * Gets leading comment ranges including synthesized
109
 */
110
function getLeadingCommentRangesSynthesized(
111
  node: ts.Node
112
): SynthesizedCommentWithOriginal[] | undefined;
113

114
/**
115
 * Recursively suppresses leading comments
116
 */
117
function suppressLeadingCommentsRecursively(node: ts.Node): void;
118

119
interface SynthesizedCommentWithOriginal extends ts.SynthesizedComment {
120
  originalRange?: ts.CommentRange;
121
}
122
```
123

124
### Text Processing Utilities
125

126
Utility functions for processing comment text and formatting.
127

128
```typescript { .api }
129
/**
130
 * Normalizes line endings in text
131
 */
132
function normalizeLineEndings(text: string): string;
133

134
/**
135
 * Creates generated-from comment
136
 */
137
function createGeneratedFromComment(
138
  sourceFile: ts.SourceFile,
139
  originalCommentRange: ts.CommentRange
140
): ts.SynthesizedComment;
141
```
142

143
## JSDoc Transformation
144

145
### Main JSDoc Transformer
146

147
The primary transformer that processes JSDoc comments throughout the compilation.
148

149
```typescript { .api }
150
/**
151
 * Main JSDoc transformer factory
152
 */
153
function jsdocTransformer(
154
  host: AnnotatorHost,
155
  tsOptions: ts.CompilerOptions,
156
  typeChecker: ts.TypeChecker,
157
  diagnostics: ts.Diagnostic[]
158
): ts.TransformerFactory<ts.SourceFile>;
159
```
160

161
### Type Assertion Removal
162

163
Transformer for removing TypeScript type assertions while preserving runtime behavior.
164

165
```typescript { .api }
166
/**
167
 * Creates transformer to remove type assertions
168
 */
169
function removeTypeAssertions(): ts.TransformerFactory<ts.SourceFile>;
170
```
171

172
### Template and Heritage Clause Processing
173

174
Functions for adding template and heritage information to JSDoc.
175

176
```typescript { .api }
177
/**
178
 * Adds template clause to JSDoc if needed
179
 */
180
function maybeAddTemplateClause(tags: Tag[], node: ts.Node): void;
181

182
/**
183
 * Adds heritage clauses to JSDoc
184
 */
185
function maybeAddHeritageClauses(tags: Tag[], classDecl: ts.ClassDeclaration): void;
186

187
/**
188
 * Escapes text for use in comments
189
 */
190
function escapeForComment(str: string): string;
191
```
192

193
## File Overview Comments
194

195
### File Overview Transformer
196

197
Specialized transformer for adding file overview comments with suppressions.
198

199
```typescript { .api }
200
/**
201
 * Creates transformer for fileoverview comments with suppressions
202
 */
203
function transformFileoverviewCommentFactory(
204
  options: ts.CompilerOptions,
205
  diagnostics: ts.Diagnostic[],
206
  generateExtraSuppressions: boolean
207
): ts.TransformerFactory<ts.SourceFile>;
208
```
209

210
**Usage Example:**
211

212
```typescript
213
// Generates fileoverview comments like:
214
/**
215
 * @fileoverview This file was generated from TypeScript sources.
216
 * @suppress {checkTypes,constantProperty,extraRequire,missingOverride,missingReturn,unusedPrivateMembers,uselessCode}
217
 */
218
```
219

220
## Tag Processing
221

222
### Conflict Detection
223

224
Detection of JSDoc tags that conflict with type annotations.
225

226
```typescript { .api }
227
/**
228
 * Set of JSDoc tag names that conflict with type annotations
229
 */
230
const TAGS_CONFLICTING_WITH_TYPE: Set<string>;
231
```
232

233
Common conflicting tags include:
234
- `@type` - Conflicts with TypeScript type annotations
235
- `@param` type information - Handled by type translator
236
- `@return` type information - Generated from TypeScript return types
237

238
### Tag Transformation Examples
239

240
```typescript
241
// Before transformation (TypeScript)
242
/**
243
 * Processes user data
244
 * @param userData - The user information
245
 */
246
function processUser(userData: UserData): Promise<ProcessedUser> {
247
  // ...
248
}
249

250
// After transformation (Closure-compatible JSDoc)
251
/**
252
 * Processes user data
253
 * @param {!UserData} userData - The user information
254
 * @return {!Promise<!ProcessedUser>}
255
 */
256
function processUser(userData) {
257
  // ...
258
}
259
```
260

261
## Integration with Type System
262

263
JSDoc processing integrates closely with the type translation system:
264

265
### Type Annotation Generation
266

267
```typescript
268
// TypeScript generic function
269
function map<T, U>(items: T[], fn: (item: T) => U): U[] {
270
  return items.map(fn);
271
}
272

273
// Generated JSDoc with template tags
274
/**
275
 * @template T, U
276
 * @param {!Array<T>} items
277
 * @param {function(T): U} fn
278
 * @return {!Array<U>}
279
 */
280
function map(items, fn) {
281
  return items.map(fn);
282
}
283
```
284

285
### Class Documentation
286

287
```typescript
288
// TypeScript class
289
/**
290
 * Represents a user in the system
291
 */
292
class User implements Serializable {
293
  constructor(public name: string, public age: number) {}
294
  
295
  serialize(): string {
296
    return JSON.stringify(this);
297
  }
298
}
299

300
// Generated JSDoc
301
/**
302
 * Represents a user in the system
303
 * @implements {Serializable}
304
 */
305
class User {
306
  /** @param {string} name @param {number} age */
307
  constructor(name, age) {
308
    this.name = name;
309
    this.age = age;
310
  }
311
  
312
  /** @return {string} */
313
  serialize() {
314
    return JSON.stringify(this);
315
  }
316
}
317
```
318

319
## Error Handling and Diagnostics
320

321
The JSDoc processing system provides comprehensive error reporting:
322

323
- **Invalid JSDoc syntax**: Parse errors with line/column information
324
- **Type conflicts**: Detection of conflicting type information
325
- **Missing documentation**: Warnings for undocumented public APIs
326
- **Malformed tags**: Validation of tag structure and parameters
327

328
## Performance Considerations
329

330
JSDoc processing is optimized for performance:
331

332
- **Lazy parsing**: Comments are parsed only when needed
333
- **Caching**: Parsed comments are cached to avoid re-parsing
334
- **Incremental processing**: Only modified files have their JSDoc re-processed
335
- **Memory efficiency**: Minimal memory footprint for large codebases