Skip to content

Commit 8055e7f

Browse files
sandersnsandersn
committed
Test new JSDoc surface area
1 parent 0f73a0a commit 8055e7f

File tree

2 files changed

+328
-0
lines changed

2 files changed

+328
-0
lines changed

‎tests/baselines/reference/APISample_jsdoc.js

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
//// [APISample_jsdoc.ts]
2+
/*
3+
* Note: This test is a public API sample. The original sources can be found
4+
* at: https://github.com/YousefED/typescript-json-schema
5+
* https://github.com/vega/ts-json-schema-generator
6+
* Please log a "breaking change" issue for any API breaking change affecting this issue
7+
*/
8+
9+
declare var console: any;
10+
11+
import * as ts from "typescript";
12+
13+
// excerpted from https://github.com/YousefED/typescript-json-schema
14+
// (converted from a method and modified; for example, `this: any` to compensate, among other changes)
15+
function parseCommentsIntoDefinition(this: any,
16+
symbol: ts.Symbol,
17+
definition: {description?: string, [s: string]: string | undefined},
18+
otherAnnotations: { [s: string]: true}): void {
19+
if (!symbol) {
20+
return;
21+
}
22+
23+
// the comments for a symbol
24+
let comments = symbol.getDocumentationComment();
25+
26+
if (comments.length) {
27+
definition.description = comments.map(comment => comment.kind === "lineBreak" ? comment.text : comment.text.trim().replace(/\r\n/g, "\n")).join("");
28+
}
29+
30+
// jsdocs are separate from comments
31+
const jsdocs = symbol.getJsDocTags();
32+
jsdocs.forEach(doc => {
33+
// if we have @TJS-... annotations, we have to parse them
34+
const { name, text } = doc;
35+
if (this.userValidationKeywords[name]) {
36+
definition[name] = this.parseValue(text);
37+
} else {
38+
// special annotations
39+
otherAnnotations[doc.name] = true;
40+
}
41+
});
42+
}
43+
44+
45+
// excerpted from https://github.com/vega/ts-json-schema-generator
46+
export interface Annotations {
47+
[name: string]: any;
48+
}
49+
function getAnnotations(this: any, node: ts.Node): Annotations | undefined {
50+
const symbol: ts.Symbol = (node as any).symbol;
51+
if (!symbol) {
52+
return undefined;
53+
}
54+
55+
const jsDocTags: ts.JSDocTagInfo[] = symbol.getJsDocTags();
56+
if (!jsDocTags || !jsDocTags.length) {
57+
return undefined;
58+
}
59+
60+
const annotations: Annotations = jsDocTags.reduce((result: Annotations, jsDocTag: ts.JSDocTagInfo) => {
61+
const value = this.parseJsDocTag(jsDocTag);
62+
if (value !== undefined) {
63+
result[jsDocTag.name] = value;
64+
}
65+
66+
return result;
67+
}, {});
68+
return Object.keys(annotations).length ? annotations : undefined;
69+
}
70+
71+
// these examples are artificial and mostly nonsensical
72+
function parseSpecificTags(node: ts.Node) {
73+
if (node.kind === ts.SyntaxKind.Parameter) {
74+
return ts.getJSDocParameterTags(node as ts.ParameterDeclaration);
75+
}
76+
if (node.kind === ts.SyntaxKind.FunctionDeclaration) {
77+
const func = node as ts.FunctionDeclaration;
78+
if (ts.hasJSDocParameterTags(func)) {
79+
const flat: ts.JSDocTag[] = [];
80+
for (const tags of func.parameters.map(ts.getJSDocParameterTags)) {
81+
if (tags) flat.push(...tags);
82+
}
83+
return flat;
84+
}
85+
}
86+
}
87+
88+
function getReturnTypeFromJSDoc(node: ts.Node) {
89+
if (node.kind === ts.SyntaxKind.FunctionDeclaration) {
90+
return ts.getJSDocReturnType(node);
91+
}
92+
let type = ts.getJSDocType(node);
93+
if (type && type.kind === ts.SyntaxKind.FunctionType) {
94+
return (type as ts.FunctionTypeNode).type;
95+
}
96+
}
97+
98+
function getAllTags(node: ts.Node) {
99+
ts.getJSDocTags(node);
100+
}
101+
102+
function getSomeOtherTags(node: ts.Node) {
103+
const tags: (ts.JSDocTag | undefined)[] = [];
104+
tags.push(ts.getJSDocAugmentsTag(node));
105+
tags.push(ts.getJSDocClassTag(node));
106+
tags.push(ts.getJSDocReturnTag(node));
107+
const type = ts.getJSDocTypeTag(node);
108+
if (type) {
109+
tags.push(type);
110+
}
111+
tags.push(ts.getJSDocTemplateTag(node));
112+
return tags;
113+
}
114+
115+
116+
//// [APISample_jsdoc.js]
117+
"use strict";
118+
/*
119+
* Note: This test is a public API sample. The original sources can be found
120+
* at: https://github.com/YousefED/typescript-json-schema
121+
* https://github.com/vega/ts-json-schema-generator
122+
* Please log a "breaking change" issue for any API breaking change affecting this issue
123+
*/
124+
exports.__esModule = true;
125+
var ts = require("typescript");
126+
// excerpted from https://github.com/YousefED/typescript-json-schema
127+
// (converted from a method and modified; for example, `this: any` to compensate, among other changes)
128+
function parseCommentsIntoDefinition(symbol, definition, otherAnnotations) {
129+
var _this = this;
130+
if (!symbol) {
131+
return;
132+
}
133+
// the comments for a symbol
134+
var comments = symbol.getDocumentationComment();
135+
if (comments.length) {
136+
definition.description = comments.map(function (comment) { return comment.kind === "lineBreak" ? comment.text : comment.text.trim().replace(/\r\n/g, "\n"); }).join("");
137+
}
138+
// jsdocs are separate from comments
139+
var jsdocs = symbol.getJsDocTags();
140+
jsdocs.forEach(function (doc) {
141+
// if we have @TJS-... annotations, we have to parse them
142+
var name = doc.name, text = doc.text;
143+
if (_this.userValidationKeywords[name]) {
144+
definition[name] = _this.parseValue(text);
145+
}
146+
else {
147+
// special annotations
148+
otherAnnotations[doc.name] = true;
149+
}
150+
});
151+
}
152+
function getAnnotations(node) {
153+
var _this = this;
154+
var symbol = node.symbol;
155+
if (!symbol) {
156+
return undefined;
157+
}
158+
var jsDocTags = symbol.getJsDocTags();
159+
if (!jsDocTags || !jsDocTags.length) {
160+
return undefined;
161+
}
162+
var annotations = jsDocTags.reduce(function (result, jsDocTag) {
163+
var value = _this.parseJsDocTag(jsDocTag);
164+
if (value !== undefined) {
165+
result[jsDocTag.name] = value;
166+
}
167+
return result;
168+
}, {});
169+
return Object.keys(annotations).length ? annotations : undefined;
170+
}
171+
// these examples are artificial and mostly nonsensical
172+
function parseSpecificTags(node) {
173+
if (node.kind === ts.SyntaxKind.Parameter) {
174+
return ts.getJSDocParameterTags(node);
175+
}
176+
if (node.kind === ts.SyntaxKind.FunctionDeclaration) {
177+
var func = node;
178+
if (ts.hasJSDocParameterTags(func)) {
179+
var flat = [];
180+
for (var _i = 0, _a = func.parameters.map(ts.getJSDocParameterTags); _i < _a.length; _i++) {
181+
var tags = _a[_i];
182+
if (tags)
183+
flat.push.apply(flat, tags);
184+
}
185+
return flat;
186+
}
187+
}
188+
}
189+
function getReturnTypeFromJSDoc(node) {
190+
if (node.kind === ts.SyntaxKind.FunctionDeclaration) {
191+
return ts.getJSDocReturnType(node);
192+
}
193+
var type = ts.getJSDocType(node);
194+
if (type && type.kind === ts.SyntaxKind.FunctionType) {
195+
return type.type;
196+
}
197+
}
198+
function getAllTags(node) {
199+
ts.getJSDocTags(node);
200+
}
201+
function getSomeOtherTags(node) {
202+
var tags = [];
203+
tags.push(ts.getJSDocAugmentsTag(node));
204+
tags.push(ts.getJSDocClassTag(node));
205+
tags.push(ts.getJSDocReturnTag(node));
206+
var type = ts.getJSDocTypeTag(node);
207+
if (type) {
208+
tags.push(type);
209+
}
210+
tags.push(ts.getJSDocTemplateTag(node));
211+
return tags;
212+
}

‎tests/cases/compiler/APISample_jsdoc.ts

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
// @module: commonjs
2+
// @includebuiltfile: typescript_standalone.d.ts
3+
// @strict:true
4+
5+
/*
6+
* Note: This test is a public API sample. The original sources can be found
7+
* at: https://github.com/YousefED/typescript-json-schema
8+
* https://github.com/vega/ts-json-schema-generator
9+
* Please log a "breaking change" issue for any API breaking change affecting this issue
10+
*/
11+
12+
declare var console: any;
13+
14+
import * as ts from "typescript";
15+
16+
// excerpted from https://github.com/YousefED/typescript-json-schema
17+
// (converted from a method and modified; for example, `this: any` to compensate, among other changes)
18+
function parseCommentsIntoDefinition(this: any,
19+
symbol: ts.Symbol,
20+
definition: {description?: string, [s: string]: string | undefined},
21+
otherAnnotations: { [s: string]: true}): void {
22+
if (!symbol) {
23+
return;
24+
}
25+
26+
// the comments for a symbol
27+
let comments = symbol.getDocumentationComment();
28+
29+
if (comments.length) {
30+
definition.description = comments.map(comment => comment.kind === "lineBreak" ? comment.text : comment.text.trim().replace(/\r\n/g, "\n")).join("");
31+
}
32+
33+
// jsdocs are separate from comments
34+
const jsdocs = symbol.getJsDocTags();
35+
jsdocs.forEach(doc => {
36+
// if we have @TJS-... annotations, we have to parse them
37+
const { name, text } = doc;
38+
if (this.userValidationKeywords[name]) {
39+
definition[name] = this.parseValue(text);
40+
} else {
41+
// special annotations
42+
otherAnnotations[doc.name] = true;
43+
}
44+
});
45+
}
46+
47+
48+
// excerpted from https://github.com/vega/ts-json-schema-generator
49+
export interface Annotations {
50+
[name: string]: any;
51+
}
52+
function getAnnotations(this: any, node: ts.Node): Annotations | undefined {
53+
const symbol: ts.Symbol = (node as any).symbol;
54+
if (!symbol) {
55+
return undefined;
56+
}
57+
58+
const jsDocTags: ts.JSDocTagInfo[] = symbol.getJsDocTags();
59+
if (!jsDocTags || !jsDocTags.length) {
60+
return undefined;
61+
}
62+
63+
const annotations: Annotations = jsDocTags.reduce((result: Annotations, jsDocTag: ts.JSDocTagInfo) => {
64+
const value = this.parseJsDocTag(jsDocTag);
65+
if (value !== undefined) {
66+
result[jsDocTag.name] = value;
67+
}
68+
69+
return result;
70+
}, {});
71+
return Object.keys(annotations).length ? annotations : undefined;
72+
}
73+
74+
// these examples are artificial and mostly nonsensical
75+
function parseSpecificTags(node: ts.Node) {
76+
if (node.kind === ts.SyntaxKind.Parameter) {
77+
return ts.getJSDocParameterTags(node as ts.ParameterDeclaration);
78+
}
79+
if (node.kind === ts.SyntaxKind.FunctionDeclaration) {
80+
const func = node as ts.FunctionDeclaration;
81+
if (ts.hasJSDocParameterTags(func)) {
82+
const flat: ts.JSDocTag[] = [];
83+
for (const tags of func.parameters.map(ts.getJSDocParameterTags)) {
84+
if (tags) flat.push(...tags);
85+
}
86+
return flat;
87+
}
88+
}
89+
}
90+
91+
function getReturnTypeFromJSDoc(node: ts.Node) {
92+
if (node.kind === ts.SyntaxKind.FunctionDeclaration) {
93+
return ts.getJSDocReturnType(node);
94+
}
95+
let type = ts.getJSDocType(node);
96+
if (type && type.kind === ts.SyntaxKind.FunctionType) {
97+
return (type as ts.FunctionTypeNode).type;
98+
}
99+
}
100+
101+
function getAllTags(node: ts.Node) {
102+
ts.getJSDocTags(node);
103+
}
104+
105+
function getSomeOtherTags(node: ts.Node) {
106+
const tags: (ts.JSDocTag | undefined)[] = [];
107+
tags.push(ts.getJSDocAugmentsTag(node));
108+
tags.push(ts.getJSDocClassTag(node));
109+
tags.push(ts.getJSDocReturnTag(node));
110+
const type = ts.getJSDocTypeTag(node);
111+
if (type) {
112+
tags.push(type);
113+
}
114+
tags.push(ts.getJSDocTemplateTag(node));
115+
return tags;
116+
}

0 commit comments

Comments
 (0)