Skip to content

Commit 6d76233

Browse files
author
nickpape-msft
committed
merge master, needs rush generate
2 parents 547c0f7 + fa7e390 commit 6d76233

21 files changed

Lines changed: 364 additions & 178 deletions

‎api-extractor/.vscode/launch.json‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
// Use IntelliSense to learn about possible Node.js debug attributes.
3+
// Hover to view descriptions of existing attributes.
4+
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
5+
"version": "0.2.0",
6+
"configurations": [
7+
{
8+
"type": "node",
9+
"request": "launch",
10+
"name": "Debug Run",
11+
"program": "${workspaceRoot}\\lib\\DebugRun.js",
12+
"cwd": "${workspaceRoot}",
13+
"sourceMaps": true
14+
},
15+
{
16+
"type": "node",
17+
"request": "attach",
18+
"name": "Attach to Process",
19+
"port": 5858
20+
}
21+
]
22+
}

‎api-extractor/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
"@types/z-schema": "3.16.20-alpha",
2626
"fs-extra": "~0.26.0",
2727
"jju": "~1.3.0",
28-
"typescript": "~2.0.3",
28+
"typescript": "~2.1.0",
2929
"z-schema": "~3.17.0"
3030
}
3131
}

‎api-extractor/src/DebugRun.ts‎

Lines changed: 6 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -37,25 +37,6 @@ class TestApiDocumentation extends ApiDocumentation {
3737
}
3838
}
3939

40-
analyzer.analyze({
41-
compilerOptions: {
42-
target: ts.ScriptTarget.ES5,
43-
module: ts.ModuleKind.CommonJS,
44-
moduleResolution: ts.ModuleResolutionKind.NodeJs,
45-
experimentalDecorators: true,
46-
jsx: ts.JsxEmit.React,
47-
rootDir: '../../spfx-core/sp-client-base'
48-
},
49-
entryPointFile: '../../spfx-core/sp-client-base/src/index.ts', // local/bundles/platform-exports.ts',
50-
otherFiles: ['../../spfx-core/sp-client-base/typings/tsd.d.ts']
51-
});
52-
53-
const apiFileGenerator: ApiFileGenerator = new ApiFileGenerator();
54-
apiFileGenerator.writeApiFile('./lib/DebugRun.api.ts', analyzer);
55-
56-
const apiJsonGenerator: ApiJsonGenerator = new ApiJsonGenerator();
57-
apiJsonGenerator.writeJsonFile('./lib/DebugRun.json', analyzer);
58-
5940
/**
6041
* Debugging inheritdoc expression parser.
6142
* Analyzer on example2 is needed for testing the parser.
@@ -73,6 +54,12 @@ analyzer.analyze({
7354
otherFiles: []
7455
});
7556

57+
const apiFileGenerator: ApiFileGenerator = new ApiFileGenerator();
58+
apiFileGenerator.writeApiFile('./lib/DebugRun.api.ts', analyzer);
59+
60+
const apiJsonGenerator: ApiJsonGenerator = new ApiJsonGenerator();
61+
apiJsonGenerator.writeJsonFile('./lib/DebugRun.json', analyzer);
62+
7663
myDocumentedClass = analyzer.package.getSortedMemberItems()
7764
.filter(apiItem => apiItem.name === 'MyDocumentedClass')[0] as ApiStructuredType;
7865
const apiDoc: TestApiDocumentation = new TestApiDocumentation();

‎api-extractor/src/DocElementParser.ts‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { IDocElement, IHrefLinkElement, ICodeLinkElement } from './IDocElement';
1+
import { ITextElement, IDocElement, IHrefLinkElement, ICodeLinkElement, ISeeDocElement } from './IDocElement';
22
import { IApiDefinitionReference } from './IApiDefinitionReference';
33
import ApiDocumentation from './definitions/ApiDocumentation';
44
import Token from './Token';
@@ -8,19 +8,19 @@ export default class DocElementParser {
88

99
/**
1010
* Matches only strings that contain characters for words.
11-
* Any non word characters or spaces, will be present in the third entry in the match results
11+
* Any non word characters or spaces, will be present in the third entry in the match results
1212
* if they exist.
1313
*/
1414
private static _wordRegEx: RegExp = /^([\w\s]*)/;
1515

1616
/**
1717
* Matches a href reference. This is used to get an idea whether a given reference is for an href
1818
* or an API definition reference.
19-
*
19+
*
2020
* For example, the following would be matched:
2121
* 'http://'
2222
* 'https://'
23-
*
23+
*
2424
* The following would not be matched:
2525
* '@microsoft/sp-core-library:Guid.newGuid'
2626
* 'Guid.newGuid'
@@ -32,7 +32,7 @@ export default class DocElementParser {
3232
if (!text) {
3333
return;
3434
}
35-
return {kind: 'textDocElement', value: text};
35+
return {kind: 'textDocElement', value: text} as ITextElement;
3636
}
3737

3838
public static parse(tokenizer: Tokenizer, reportError: (message: string) => void): IDocElement[] {
@@ -54,7 +54,7 @@ export default class DocElementParser {
5454
docElements.push({
5555
kind: 'seeDocElement',
5656
seeElements: this.parse(tokenizer, reportError)
57-
});
57+
} as ISeeDocElement);
5858
break;
5959
default:
6060
parsing = false; // end of summary tokens
@@ -67,14 +67,14 @@ export default class DocElementParser {
6767
if (linkDocElement) {
6868
docElements.push(linkDocElement);
6969
}
70-
tokenizer.getToken(); // get the link token
70+
tokenizer.getToken(); // get the link token
7171
break;
7272
default:
7373
parsing = false;
7474
break;
7575
}
7676
} else if (token.type === 'Text') {
77-
docElements.push({kind: 'textDocElement', value: token.text});
77+
docElements.push({kind: 'textDocElement', value: token.text} as ITextElement);
7878
tokenizer.getToken();
7979
} else {
8080
reportError(`Unidentifiable Token ${token.type} ${token.tag} ${token.text}`);
@@ -85,12 +85,12 @@ export default class DocElementParser {
8585

8686
/**
8787
* This method parses the semantic information in an \@link JSDoc tag, creates and returns a
88-
* linkDocElement with the corresponding information. If the corresponding inline tag \@link is
88+
* linkDocElement with the corresponding information. If the corresponding inline tag \@link is
8989
* not formatted correctly an error will be reported.
90-
*
91-
* The format for the \@link tag is {\@link url or API defintion reference | display text}, where
90+
*
91+
* The format for the \@link tag is {\@link url or API defintion reference | display text}, where
9292
* the '|' is only needed if the optional display text is given.
93-
*
93+
*
9494
* Examples:
9595
* \{@link http://microsoft.com | microsoft home \}
9696
* \{@link http://microsoft.com \}
@@ -104,7 +104,7 @@ export default class DocElementParser {
104104
return;
105105
}
106106

107-
// Make sure there are no extra pipes
107+
// Make sure there are no extra pipes
108108
let pipeSplitContent: string[] = tokenItem.text.split('|');
109109
pipeSplitContent = pipeSplitContent.map( value => {
110110
if (value) {
@@ -116,7 +116,7 @@ export default class DocElementParser {
116116
return;
117117
}
118118

119-
// Try to guess if the tokenContent is a link or API definition reference
119+
// Try to guess if the tokenContent is a link or API definition reference
120120
let linkDocElement: ICodeLinkElement | IHrefLinkElement;
121121
if (tokenItem.text.match(this._hrefRegEx)) {
122122
const urlContent: string[] = pipeSplitContent[0].split(' ');
@@ -135,7 +135,7 @@ export default class DocElementParser {
135135
};
136136

137137
} else {
138-
// we are processing an API definition reference
138+
// we are processing an API definition reference
139139
const apiDefitionRef: IApiDefinitionReference = ApiDocumentation.parseApiReferenceExpression(
140140
pipeSplitContent[0], reportError);
141141

@@ -160,7 +160,7 @@ export default class DocElementParser {
160160
reportError('Display name in @link token may only contain alphabetic characters.');
161161
return;
162162
}
163-
// Full match is valid text
163+
// Full match is valid text
164164
linkDocElement.value = displayTextParts[0].trim();
165165
}
166166

‎api-extractor/src/IDocElement.ts‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
/**
2-
* The following interfaces represent Doc Elements of a
3-
* documentation block.
2+
* The following interfaces represent Doc Elements of a
3+
* documentation block.
44
*/
55
export interface IBaseDocElement {
66
kind: string;
@@ -16,10 +16,10 @@ export interface ITextElement extends IBaseDocElement {
1616

1717
/**
1818
* A link that was specified as \{@link http://url | optional display text\}.
19-
* The alternative to the IHrefLinkElement is ICodeLinkElement, where instead
19+
* The alternative to the IHrefLinkElement is ICodeLinkElement, where instead
2020
* of a href the reference is to an API definition.
21-
*
22-
* Examples:
21+
*
22+
* Examples:
2323
* \{@link http://microsoft.com | Microsoft \}
2424
* \{@link http://microsoft.com \}
2525
*/
@@ -78,20 +78,20 @@ export interface ICodeLinkElement extends IBaseDocElement {
7878
}
7979

8080
/**
81-
* An element that denotes one of more elements to see for reference.
82-
*
81+
* An element that denotes one of more elements to see for reference.
82+
*
8383
* Example:
84-
* @see
84+
* @see
8585
* {@link http://microsoft.com | Microsoft}
86-
* This is a description of the link.
86+
* This is a description of the link.
8787
* ->
8888
* {
89-
* kind: 'seeDocElement,
89+
* kind: 'seeDocElement,
9090
* seeElements: [
91-
* {kind: 'linkDocElement', targetUrl: http://microsoft.com, value: Microsoft},
91+
* {kind: 'linkDocElement', targetUrl: http://microsoft.com, value: Microsoft},
9292
* {kind: 'textDocElement', value: 'This is a description of the link.'}
9393
* ]
94-
* }
94+
* }
9595
*/
9696
export interface ISeeDocElement extends IBaseDocElement {
9797
kind: 'seeDocElement';
@@ -103,9 +103,9 @@ export type ILinkDocElement = IHrefLinkElement | ICodeLinkElement;
103103
export type IDocElement = ITextElement | ILinkDocElement | ISeeDocElement;
104104

105105
/**
106-
* An element that represents a param and relevant information to its use.
107-
*
108-
* Example:
106+
* An element that represents a param and relevant information to its use.
107+
*
108+
* Example:
109109
* @param1 httpClient - description of httpClient {@link http://website.com}
110110
* ->
111111
* {
@@ -115,7 +115,7 @@ export type IDocElement = ITextElement | ILinkDocElement | ISeeDocElement;
115115
* {kind: 'linkDocElement', targetUrl: 'http://website.com}
116116
* ]
117117
* }
118-
*
118+
*
119119
*/
120120
export interface IParam {
121121
name: string;
@@ -126,8 +126,8 @@ export interface IParam {
126126
}
127127

128128
/**
129-
* Describes a return type and description of the return type
130-
* that is given in documentation comments.
129+
* Describes a return type and description of the return type
130+
* that is given in documentation comments.
131131
*/
132132
export interface IReturn {
133133
type: string;

‎api-extractor/src/PrettyPrinter.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,8 @@ export default class PrettyPrinter {
5757

5858
for (const childNode of node.getChildren()) {
5959
switch (childNode.kind) {
60+
case ts.SyntaxKind.JSDocComment:
61+
break;
6062
case ts.SyntaxKind.Block:
6163
result += ';';
6264
break;

‎api-extractor/src/TypeScriptHelpers.ts‎

Lines changed: 72 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,26 @@ import PrettyPrinter from './PrettyPrinter';
55

66
export default class TypeScriptHelpers {
77

8+
/**
9+
* Splits by the characters '\r\n'.
10+
*/
11+
public static newLineRegEx: RegExp = /\r\n|\n/g;
12+
13+
/**
14+
* Start sequence is '/**'.
15+
*/
16+
public static jsDocStartRegEx: RegExp = /^\s*\/\*\*\s?/g;
17+
18+
/**
19+
* End sequence is '*\/'.
20+
*/
21+
public static jsDocEndRegEx: RegExp = /^\s*\*\//g;
22+
23+
/**
24+
* Intermediate lines of JSDoc comment character.
25+
*/
26+
public static jsDocIntermediateRegEx: RegExp = /^\s*[*]\s?/g;
27+
828
/**
929
* Returns the Symbol for the provided Declaration. This is a workaround for a missing
1030
* feature of the TypeScript Compiler API. It is the only apparent way to reach
@@ -35,10 +55,60 @@ export default class TypeScriptHelpers {
3555

3656
/**
3757
* Returns the JSDoc comments associated with the specified node, if any.
58+
*
59+
* Example:
60+
* "This \n is \n a comment" from "\/** This\r\n* is\r\n* a comment *\/
3861
*/
39-
public static getJsDocComments(node: ts.Node, sourceFile: ts.SourceFile): ts.CommentRange[] {
62+
public static getJsDocComments(node: ts.Node, errorLogger: (message: string) => void): string {
63+
let jsDoc: string = '';
4064
// tslint:disable-next-line:no-any
41-
return (ts as any).getJsDocComments(node, sourceFile);
65+
const nodeJsDocObjects: any = (node as any).jsDoc;
66+
if (nodeJsDocObjects && nodeJsDocObjects.length > 0) {
67+
// Use the JSDoc closest to the declaration
68+
const lastJsDocIndex: number = nodeJsDocObjects.length - 1;
69+
const jsDocFullText: string = nodeJsDocObjects[lastJsDocIndex].getText();
70+
const jsDocLines: string[] = jsDocFullText.split(TypeScriptHelpers.newLineRegEx);
71+
const jsDocStartSeqExists: boolean = TypeScriptHelpers.jsDocStartRegEx.test(jsDocLines[0]);
72+
const jsDocEndSeqExists: boolean = TypeScriptHelpers.jsDocEndRegEx.test(jsDocLines[jsDocLines.length - 1]);
73+
if (!(jsDocStartSeqExists && jsDocEndSeqExists)) {
74+
errorLogger('JsDoc comment must begin with \"/**\" sequence and end with \"*/\" sequence.');
75+
return '';
76+
}
77+
78+
jsDoc = TypeScriptHelpers.removeJsDocSequences(jsDocLines);
79+
}
80+
81+
return jsDoc;
82+
}
83+
84+
/**
85+
* Helper function to remove the comment stars ('/**'. '*', '/*) from lines of comment text.
86+
*
87+
* Example:
88+
* ["\/**", "*This \n", "*is \n", "*a comment", "*\/"] to "This \n is \n a comment"
89+
*/
90+
public static removeJsDocSequences(textLines: string[]): string {
91+
// Remove '/**'
92+
textLines[0] = textLines[0].replace(TypeScriptHelpers.jsDocStartRegEx, '');
93+
if (textLines[0] === '') {
94+
textLines.shift();
95+
}
96+
// Remove '*/'
97+
textLines[textLines.length - 1] = textLines[textLines.length - 1].replace(
98+
TypeScriptHelpers.jsDocEndRegEx,
99+
'');
100+
if (textLines[textLines.length - 1] === '') {
101+
textLines.pop();
102+
}
103+
104+
// Remove the leading '*' from any intermediate lines
105+
if (textLines.length > 0) {
106+
for (let i: number = 0; i < textLines.length; i++) {
107+
textLines[i] = textLines[i].replace(TypeScriptHelpers.jsDocIntermediateRegEx, '');
108+
}
109+
}
110+
111+
return textLines.join('\n');
42112
}
43113

44114
/**

0 commit comments

Comments
 (0)