Skip to content

Commit 110e78a

Browse files
author
nickpape-msft
committed
Merge branch 'master' into nickpape/rush-generate
2 parents efc7d98 + 33bc436 commit 110e78a

26 files changed

Lines changed: 316 additions & 214 deletions

‎api-extractor/CHANGELOG.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,21 @@
11
{
22
"name": "@microsoft/api-extractor",
33
"entries": [
4+
{
5+
"version": "1.1.1",
6+
"tag": "@microsoft/api-extractor_v1.1.1",
7+
"date": "Thu, 19 Jan 2017 20:04:40 GMT",
8+
"comments": {
9+
"patch": [
10+
{
11+
"comment": "Check for missing JsDoc sequences changed."
12+
},
13+
{
14+
"comment": "Improved error messages"
15+
}
16+
]
17+
}
18+
},
419
{
520
"version": "1.1.0",
621
"tag": "@microsoft/api-extractor_v1.1.0",

‎api-extractor/CHANGELOG.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
# Change Log - @microsoft/api-extractor
22

3-
This log was last generated on Wed, 18 Jan 2017 20:04:29 GMT and should not be manually modified.
3+
This log was last generated on Thu, 19 Jan 2017 20:04:40 GMT and should not be manually modified.
4+
5+
## 1.1.1
6+
Thu, 19 Jan 2017 20:04:40 GMT
7+
8+
### Patches
9+
10+
- Check for missing JsDoc sequences changed.
11+
- Improved error messages
412

513
## 1.1.0
614
Wed, 18 Jan 2017 20:04:29 GMT

‎api-extractor/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@microsoft/api-extractor",
3-
"version": "1.1.0",
3+
"version": "1.1.1",
44
"description": "Validatation, documentation, and auditing for the exported API of a TypeScript package",
55
"main": "lib/index.js",
66
"typings": "lib/index.d.ts",

‎api-extractor/src/DebugRun.ts‎

Lines changed: 10 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -2,43 +2,20 @@
22
// IT IS INVOKED BY THE "Run.cmd" AND "Debug.cmd" BATCH FILES.
33

44
import * as ts from 'typescript';
5+
import * as os from 'os';
56
import Analyzer from './Analyzer';
67
import ApiFileGenerator from './generators/ApiFileGenerator';
78
import ApiJsonGenerator from './generators/ApiJsonGenerator';
8-
import { IDocItem } from './IDocItem';
9-
import { IApiDefinitionReference } from './IApiDefinitionReference';
10-
import { IDocElement, IParam } from './IDocElement';
11-
import DocItemLoader from './DocItemLoader';
12-
import DocElementParser from './DocElementParser';
13-
import TestFileComparer from './TestFileComparer';
14-
import JsonFile from './JsonFile';
15-
import ApiStructuredType from './definitions/ApiStructuredType';
16-
import ApiDocumentation from './definitions/ApiDocumentation';
17-
import Tokenizer from './Tokenizer';
189

19-
let docs: string = '{@link @microsoft/sp-core-library:Guid.equals | Guid equals}';
20-
let tokenizer: Tokenizer = new Tokenizer(docs, console.log);
21-
/* tslint:disable:no-unused-variable */
22-
const linkResult: IDocElement[] = DocElementParser.parse(tokenizer, console.log);
23-
24-
const analyzer: Analyzer = new Analyzer();
25-
26-
/**
27-
* Dummy class wrapping ApiDocumentation to test its protected methods
28-
*/
29-
let myDocumentedClass: ApiStructuredType;
30-
class TestApiDocumentation extends ApiDocumentation {
31-
constructor() {
32-
super(myDocumentedClass, analyzer.docItemLoader, (msg: string) => { return; });
33-
}
34-
35-
public parseParam(_tokenizer: Tokenizer): IParam {
36-
return this._parseParam(_tokenizer);
10+
const analyzer: Analyzer = new Analyzer(
11+
(message: string, fileName: string, lineNumber: number): void => {
12+
console.log(`ErrorHandler: ${message}` + os.EOL
13+
+ ` ${fileName}#${lineNumber}`);
3714
}
38-
}
15+
);
3916

4017
/**
41-
* Debugging inheritdoc expression parser.
18+
* Debugging inheritdoc expression parser.
4219
* Analyzer on example2 is needed for testing the parser.
4320
*/
4421
analyzer.analyze({
@@ -48,9 +25,9 @@ analyzer.analyze({
4825
moduleResolution: ts.ModuleResolutionKind.NodeJs,
4926
experimentalDecorators: true,
5027
jsx: ts.JsxEmit.React,
51-
rootDir: './testInputs/example2'
28+
rootDir: 'D:/GitRepos/sp-client/spfx-core/sp-codepart-base'
5229
},
53-
entryPointFile: './testInputs/example2/index.ts', // local/bundles/platform-exports.ts',
30+
entryPointFile: 'D:/GitRepos/sp-client/spfx-core/sp-codepart-base/src/index.ts',
5431
otherFiles: []
5532
});
5633

@@ -60,57 +37,4 @@ apiFileGenerator.writeApiFile('./lib/DebugRun.api.ts', analyzer);
6037
const apiJsonGenerator: ApiJsonGenerator = new ApiJsonGenerator();
6138
apiJsonGenerator.writeJsonFile('./lib/DebugRun.json', analyzer);
6239

63-
myDocumentedClass = analyzer.package.getSortedMemberItems()
64-
.filter(apiItem => apiItem.name === 'MyDocumentedClass')[0] as ApiStructuredType;
65-
const apiDoc: TestApiDocumentation = new TestApiDocumentation();
66-
67-
docs = '@param x - The height in {@link http://wikipedia.org/pixel_units}';
68-
tokenizer = new Tokenizer(docs, console.log);
69-
// ApiDocumentation gets the @param token before calling parseParam()
70-
tokenizer.getToken();
71-
apiDoc.parseParam(tokenizer);
72-
73-
/**
74-
* Put test cases here
75-
*/
76-
let apiReferenceExpr: string = '@microsoft/sp-core-library:Guid.equals';
77-
let actual: IApiDefinitionReference;
78-
actual = ApiDocumentation.parseApiReferenceExpression(apiReferenceExpr, apiDoc.reportError);
79-
80-
apiReferenceExpr = '@microsoft/sp-core-library:Guid';
81-
actual = ApiDocumentation.parseApiReferenceExpression(apiReferenceExpr, apiDoc.reportError);
82-
83-
apiReferenceExpr = 'sp-core-library:Guid';
84-
actual = ApiDocumentation.parseApiReferenceExpression(apiReferenceExpr, apiDoc.reportError);
85-
86-
apiReferenceExpr = 'Guid.equals';
87-
actual = ApiDocumentation.parseApiReferenceExpression(apiReferenceExpr, apiDoc.reportError);
88-
89-
apiReferenceExpr = 'Guid';
90-
actual = ApiDocumentation.parseApiReferenceExpression(apiReferenceExpr, apiDoc.reportError);
91-
92-
// Should report error
93-
apiReferenceExpr = 'sp-core-library:Guid:equals';
94-
try {
95-
actual = ApiDocumentation.parseApiReferenceExpression(apiReferenceExpr, apiDoc.reportError);
96-
} catch (error) {
97-
console.log(error);
98-
}
99-
100-
/**
101-
* Debugging DocItemLoader
102-
*/
103-
const apiDefinitionRef: IApiDefinitionReference = {
104-
scopeName: '@microsoft',
105-
packageName: 'sp-core-library',
106-
exportName: 'DisplayMode',
107-
memberName: ''
108-
};
109-
110-
const docItemLoader: DocItemLoader = new DocItemLoader('./testInputs/example2');
111-
/* tslint:disable:no-unused-variable */
112-
const apiDocItemNotInCache: IDocItem = docItemLoader.getItem(apiDefinitionRef);
113-
JsonFile.saveJsonFile('./lib/inheritedDoc-output.json', JSON.stringify(apiDocItemNotInCache));
114-
TestFileComparer.assertFileMatchesExpected('./lib/inheritedDoc-output.json', './testInputs/inheritedDoc-output.json');
115-
/* tslint:disable:no-unused-variable */
116-
const apiDocItemInCache: IDocItem = docItemLoader.getItem(apiDefinitionRef);
40+
console.log('DebugRun completed.');

‎api-extractor/src/DocElementParser.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { ITextElement, IDocElement, IHrefLinkElement, ICodeLinkElement, ISeeDocElement } from './IDocElement';
22
import { IApiDefinitionReference } from './IApiDefinitionReference';
33
import ApiDocumentation from './definitions/ApiDocumentation';
4-
import Token from './Token';
4+
import Token, { TokenType } from './Token';
55
import Tokenizer from './Tokenizer';
66

77
export default class DocElementParser {
@@ -47,7 +47,7 @@ export default class DocElementParser {
4747
break;
4848
}
4949

50-
if (token.type === 'Tag') {
50+
if (token.type === TokenType.Tag) {
5151
switch (token.tag) {
5252
case '@see':
5353
tokenizer.getToken();
@@ -60,7 +60,7 @@ export default class DocElementParser {
6060
parsing = false; // end of summary tokens
6161
break;
6262
}
63-
} else if (token.type === 'Inline') {
63+
} else if (token.type === TokenType.Inline) {
6464
switch (token.tag) {
6565
case '@link' :
6666
const linkDocElement: ICodeLinkElement | IHrefLinkElement = this.parseLinkTag(token, reportError);
@@ -73,7 +73,7 @@ export default class DocElementParser {
7373
parsing = false;
7474
break;
7575
}
76-
} else if (token.type === 'Text') {
76+
} else if (token.type === TokenType.Text) {
7777
docElements.push({kind: 'textDocElement', value: token.text} as ITextElement);
7878
tokenizer.getToken();
7979
} else {

‎api-extractor/src/Token.ts‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* Allowed Token types.
33
*/
4-
export enum TokenTypes {
4+
export enum TokenType {
55
/**
66
* A Token that contains only text.
77
*/
@@ -14,10 +14,10 @@ export enum TokenTypes {
1414
Tag,
1515

1616
/**
17-
* This is a specific kind of Tag that is important to
17+
* This is a specific kind of Tag that is important to
1818
* distinguish because it contains additional parameters.
19-
*
20-
* Example:
19+
*
20+
* Example:
2121
* \{@link http://microosft.com | microsoft home \}
2222
* \{@inheritdoc @ microsoft/sp-core-library:Guid.newGuid \}
2323
*/
@@ -30,10 +30,9 @@ export enum TokenTypes {
3030
export default class Token {
3131

3232
/**
33-
* The type of the token.
34-
* Possible options: Text, Tag, Inline.
33+
* The type of the token.
3534
*/
36-
private _type: string;
35+
private _type: TokenType;
3736

3837
/**
3938
* This is not used for Text.
@@ -46,7 +45,7 @@ export default class Token {
4645
*/
4746
private _text: string;
4847

49-
constructor(type: string, tag?: string, text?: string) {
48+
constructor(type: TokenType, tag?: string, text?: string) {
5049
this._type = type;
5150
this._tag = tag ? tag : '';
5251
this._text = text ? this._unescape(text) : '';
@@ -56,13 +55,13 @@ export default class Token {
5655
/**
5756
* Determines if the type is not what we expect.
5857
*/
59-
public requireType(type: string): void {
58+
public requireType(type: TokenType): void {
6059
if (this._type !== type) {
61-
throw new Error('Token of type \"${this._type}\" is not of required type \"${type}\"');
60+
throw new Error(`Encountered a token of type \"${this._type}\" when expecting \"${type}\"`);
6261
}
6362
}
6463

65-
public get type(): string {
64+
public get type(): TokenType {
6665
return this._type;
6766
}
6867

‎api-extractor/src/Tokenizer.ts‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import Token from './Token';
1+
import Token, { TokenType } from './Token';
22
import TypeScriptHelpers from './TypeScriptHelpers';
33

44
/**
@@ -29,7 +29,7 @@ export default class Tokenizer {
2929
* can be processed more strictly.
3030
* Example: "This is a JsDoc description with a {@link URL} and more text. \@summary example \@public"
3131
* => [
32-
* {tokenType: 'text', parameter: 'This is a JsDoc description with a'},
32+
* {tokenType: 'text', parameter: 'This is a JsDoc description with a'},
3333
* {tokenType: '@link', parameter: 'URL'},
3434
* {tokenType: '\@summary', parameter: ''},
3535
* {tokenType: 'text', parameter: 'example'},
@@ -41,7 +41,7 @@ export default class Tokenizer {
4141
return;
4242
}
4343
const docEntries: string[] = TypeScriptHelpers.splitStringWithRegEx(docs, Tokenizer._jsdocTagsRegex);
44-
const sanitizedTokens: string[] = this._sanitizeDocEntries(docEntries); // remove white space and empty entries
44+
const sanitizedTokens: string[] = this._sanitizeDocEntries(docEntries); // remove white space and empty entries
4545

4646
// process each sanitized doc string to a Token object
4747
const tokens: Token[] = [];
@@ -50,11 +50,11 @@ export default class Tokenizer {
5050
let token: Token;
5151
value = sanitizedTokens[i];
5252
if (value.charAt(0) === '@') {
53-
token = new Token('Tag', value);
53+
token = new Token(TokenType.Tag, value);
5454
} else if (value.charAt(0) === '{' && value.charAt(value.length - 1) === '}') {
5555
token = this._tokenizeInline(value); // Can return undefined if invalid inline tag
5656
} else {
57-
token = new Token('Text', '', value);
57+
token = new Token(TokenType.Text, '', value);
5858
}
5959

6060
if (token) {
@@ -66,7 +66,7 @@ export default class Tokenizer {
6666
}
6767

6868
/**
69-
* Parse an inline tag and returns the Token for it if itis a valid inline tag.
69+
* Parse an inline tag and returns the Token for it if itis a valid inline tag.
7070
* Example '{@link https://bing.com | Bing}' => '{type: 'Inline', tag: '@link', text: 'https://bing.com | Bing'}'
7171
*/
7272
protected _tokenizeInline(docEntry: string): Token {
@@ -98,11 +98,11 @@ export default class Tokenizer {
9898
}
9999

100100
tokenChunks.shift(); // Gets rid of '@link'
101-
const token: Token = new Token('Inline', '@link', tokenChunks.join(' '));
101+
const token: Token = new Token(TokenType.Inline, '@link', tokenChunks.join(' '));
102102
return token;
103103
} else if (tokenChunks[0] === '@inheritdoc') {
104104
tokenChunks.shift(); // Gets rid of '@inheritdoc'
105-
const token: Token = new Token('Inline', '@inheritdoc', tokenChunks.join(' '));
105+
const token: Token = new Token(TokenType.Inline, '@inheritdoc', tokenChunks.join(' '));
106106
return token;
107107
}
108108

@@ -119,7 +119,7 @@ export default class Tokenizer {
119119
}
120120

121121
/**
122-
* Trims whitespaces on either end of the entry (which is just a string within the doc comments),
122+
* Trims whitespaces on either end of the entry (which is just a string within the doc comments),
123123
* replaces \r and \n's with single whitespace, and removes empty entries.
124124
*
125125
* @param docEntries - Array of doc strings to be santitized
@@ -138,4 +138,4 @@ export default class Tokenizer {
138138

139139
return result;
140140
}
141-
}
141+
}

‎api-extractor/src/TypeScriptHelpers.ts‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ export default class TypeScriptHelpers {
1818
/**
1919
* End sequence is '*\/'.
2020
*/
21-
public static jsDocEndRegEx: RegExp = /^\s*\*\//g;
21+
public static jsDocEndRegEx: RegExp = /\s*\*\/\s*$/g;
2222

2323
/**
2424
* Intermediate lines of JSDoc comment character.
@@ -68,10 +68,18 @@ export default class TypeScriptHelpers {
6868
const lastJsDocIndex: number = nodeJsDocObjects.length - 1;
6969
const jsDocFullText: string = nodeJsDocObjects[lastJsDocIndex].getText();
7070
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.');
71+
const jsDocStartSeqExists: boolean = TypeScriptHelpers.jsDocStartRegEx.test(jsDocLines[0].toString());
72+
73+
// Report error for each missing sequence seperately
74+
if (!jsDocStartSeqExists) {
75+
errorLogger('JsDoc comment must begin with a \"/**\" sequence.');
76+
return '';
77+
}
78+
const jsDocEndSeqExists: boolean = TypeScriptHelpers.jsDocEndRegEx.test(
79+
jsDocLines[jsDocLines.length - 1].toString()
80+
);
81+
if (!jsDocEndSeqExists) {
82+
errorLogger('JsDoc comment must end with a \"*/\" sequence.');
7583
return '';
7684
}
7785

0 commit comments

Comments
 (0)