@microsoft/api-extractor
Advanced tools
Comparing version 1.1.7 to 1.1.8
@@ -5,2 +5,14 @@ { | ||
{ | ||
"version": "1.1.8", | ||
"tag": "@microsoft/api-extractor_v1.1.8", | ||
"date": "Sat, 04 Feb 2017 02:32:05 GMT", | ||
"comments": { | ||
"patch": [ | ||
{ | ||
"comment": "Moved ApiItem references within ApiDocumentation, to ApiItem caller." | ||
} | ||
] | ||
} | ||
}, | ||
{ | ||
"version": "1.1.7", | ||
@@ -7,0 +19,0 @@ "tag": "@microsoft/api-extractor_v1.1.7", |
# Change Log - @microsoft/api-extractor | ||
This log was last generated on Thu, 02 Feb 2017 14:05:53 GMT and should not be manually modified. | ||
This log was last generated on Sat, 04 Feb 2017 02:32:05 GMT and should not be manually modified. | ||
## 1.1.8 | ||
Sat, 04 Feb 2017 02:32:05 GMT | ||
### Patches | ||
- Moved ApiItem references within ApiDocumentation, to ApiItem caller. | ||
## 1.1.7 | ||
@@ -6,0 +13,0 @@ Thu, 02 Feb 2017 14:05:53 GMT |
/// <reference types="es6-collections" /> | ||
import ApiItem from './ApiItem'; | ||
import { IDocElement, IParam } from '../IDocElement'; | ||
@@ -56,4 +55,2 @@ import DocItemLoader from '../DocItemLoader'; | ||
export default class ApiDocumentation { | ||
private static _allowedRegularJsdocTags; | ||
private static _allowedInlineJsdocTags; | ||
/** | ||
@@ -63,3 +60,5 @@ * Match JsDoc block tags and inline tags | ||
*/ | ||
private static _jsdocTagsRegex; | ||
static readonly _jsdocTagsRegex: RegExp; | ||
private static _allowedRegularJsdocTags; | ||
private static _allowedInlineJsdocTags; | ||
/** | ||
@@ -79,12 +78,7 @@ * Splits an API reference expression into two parts, first part is the scopename/packageName and | ||
/** | ||
* Corresponding ApiItem for this documentation object | ||
*/ | ||
apiItem: ApiItem; | ||
/** | ||
* This returns the JSDoc comment block for the given item (without "/**" characters), | ||
* or an empty string if there is no comment. This propery will never be undefined. | ||
* The original JsDoc comment. | ||
* | ||
* Example: "Example Function\n@returns the number of items\n@internal" | ||
* Example: "This is a summary. \{\@link a\} \@remarks These are remarks." | ||
*/ | ||
docComment: string; | ||
originalJsDoc: string; | ||
/** | ||
@@ -113,9 +107,2 @@ * The docComment text string split into an array of ITokenItems. The tokens are essentially either | ||
/** | ||
* Indicates that this definition does not have adequate JSDoc comments. If isMissing=true, | ||
* then this will be noted in the API file produced by ApiFileGenerator. (The JSDoc | ||
* text itself is not included in that report, because documentation changes do not | ||
* require an API review, and thus should not cause a diff for that report.) | ||
*/ | ||
isMissing: boolean; | ||
/** | ||
* An "API Tag" is a custom JSDoc tag which indicates whether this definition | ||
@@ -140,3 +127,3 @@ * is considered Public API for third party developers, as well as its release | ||
isOverride?: boolean; | ||
readonly?: boolean; | ||
hasReadOnlyTag?: boolean; | ||
docItemLoader: DocItemLoader; | ||
@@ -160,4 +147,3 @@ /** | ||
private static parseScopedPackageName(scopedName); | ||
constructor(apiItem: ApiItem, docItemLoader: DocItemLoader, extractor: Extractor, errorLogger: (message: string) => void); | ||
protected _getJsDocs(apiItem: ApiItem): string; | ||
constructor(docComment: string, docItemLoader: DocItemLoader, extractor: Extractor, errorLogger: (message: string) => void); | ||
protected _parseDocs(): void; | ||
@@ -164,0 +150,0 @@ /** |
/* tslint:disable:no-bitwise */ | ||
"use strict"; | ||
var ts = require("typescript"); | ||
var TypeScriptHelpers_1 = require("../TypeScriptHelpers"); | ||
var DocElementParser_1 = require("../DocElementParser"); | ||
var Token_1 = require("../Token"); | ||
var Tokenizer_1 = require("../Tokenizer"); | ||
var ApiPackage_1 = require("./ApiPackage"); | ||
/** | ||
@@ -44,8 +41,7 @@ * An "API Tag" is a custom JSDoc tag which indicates whether an ApiItem definition | ||
var ApiDocumentation = (function () { | ||
function ApiDocumentation(apiItem, docItemLoader, extractor, errorLogger) { | ||
this.apiItem = apiItem; | ||
function ApiDocumentation(docComment, docItemLoader, extractor, errorLogger) { | ||
this.originalJsDoc = docComment; | ||
this.docItemLoader = docItemLoader; | ||
this.extractor = extractor; | ||
this.reportError = errorLogger; | ||
this.docComment = this._getJsDocs(apiItem); | ||
this.parameters = new Map(); | ||
@@ -108,17 +104,4 @@ this._parseDocs(); | ||
}; | ||
ApiDocumentation.prototype._getJsDocs = function (apiItem) { | ||
if (!apiItem.jsdocNode) { | ||
return ''; | ||
} | ||
var jsDoc = TypeScriptHelpers_1.default.getJsDocComments(apiItem.jsdocNode, this.reportError); | ||
// Eliminate tags and then count the English letters. Are there at least 10 letters of text? | ||
// If not, we consider the definition to be "missingDocumentation". | ||
var condensedDocs = jsDoc | ||
.replace(ApiDocumentation._jsdocTagsRegex, '') | ||
.replace(/[^a-z]/gi, ''); | ||
this.isMissing = apiItem.shouldHaveDocumentation() && condensedDocs.length <= 10; | ||
return jsDoc; | ||
}; | ||
ApiDocumentation.prototype._parseDocs = function () { | ||
var tokenizer = new Tokenizer_1.default(this.docComment, this.reportError); | ||
var tokenizer = new Tokenizer_1.default(this.originalJsDoc, this.reportError); | ||
this.summary = DocElementParser_1.default.parse(tokenizer, this.reportError); | ||
@@ -202,3 +185,3 @@ this.returnsMessage = []; | ||
tokenizer.getToken(); | ||
this.readonly = true; | ||
this.hasReadOnlyTag = true; | ||
break; | ||
@@ -255,19 +238,6 @@ case '@betadocumentation': | ||
} | ||
if (this.apiItem instanceof ApiPackage_1.default) { | ||
if (apiTagCount > 0) { | ||
var tag = '@' + ApiTag[this.apiTag].toLowerCase(); | ||
this.reportError("The " + tag + " tag is not allowed on the package, which is always public"); | ||
} | ||
this.apiTag = ApiTag.Public; | ||
if (this.preapproved && this.apiTag !== ApiTag.Internal) { | ||
this.reportError('The @preapproved tag may only be applied to @internal defintions'); | ||
this.preapproved = false; | ||
} | ||
if (this.preapproved) { | ||
if (this.apiTag !== ApiTag.Internal) { | ||
this.reportError('The @preapproved tag may only be applied to @internal defintions'); | ||
this.preapproved = false; | ||
} | ||
else if (!(this.apiItem.getDeclarationSymbol().flags & (ts.SymbolFlags.Interface | ts.SymbolFlags.Class))) { | ||
this.reportError('The @preapproved tag may only be applied to classes and interfaces'); | ||
this.preapproved = false; | ||
} | ||
} | ||
}; | ||
@@ -380,2 +350,7 @@ /** | ||
}()); | ||
/** | ||
* Match JsDoc block tags and inline tags | ||
* Example "@a @b@c d@e @f {whatever} {@link a} { @something } \@g" => ["@a", "@f", "{@link a}", "{ @something }"] | ||
*/ | ||
ApiDocumentation._jsdocTagsRegex = /{\s*@(\\{|\\}|[^{}])*}|(?:^|\s)(\@[a-z_]+)(?=\s|$)/gi; | ||
// For guidance about using these tags, please see this document: | ||
@@ -407,7 +382,2 @@ // https://onedrive.visualstudio.com/DefaultCollection/SPPPlat/_git/sp-client | ||
/** | ||
* Match JsDoc block tags and inline tags | ||
* Example "@a @b@c d@e @f {whatever} {@link a} { @something } \@g" => ["@a", "@f", "{@link a}", "{ @something }"] | ||
*/ | ||
ApiDocumentation._jsdocTagsRegex = /{\s*@(\\{|\\}|[^{}])*}|(?:^|\s)(\@[a-z_]+)(?=\s|$)/gi; | ||
/** | ||
* Splits an API reference expression into two parts, first part is the scopename/packageName and | ||
@@ -414,0 +384,0 @@ * the second part is the exportName.memberName. |
@@ -112,2 +112,10 @@ import * as ts from 'typescript'; | ||
/** | ||
* Indicates that this ApiItem does not have adequate JSDoc comments. If shouldHaveDocumentation()=true, | ||
* and there is less than 10 characters of summary text in the JSDoc, then this will be set to true and | ||
* noted in the API file produced by ApiFileGenerator. | ||
* (The JSDoc text itself is not included in that report, because documentation | ||
* changes do not require an API review, and thus should not cause a diff for that report.) | ||
*/ | ||
needsDocumentation: boolean; | ||
/** | ||
* The Extractor object that acts as the root of the abstract syntax tree that this item belongs to. | ||
@@ -114,0 +122,0 @@ */ |
@@ -6,2 +6,4 @@ /* tslint:disable:no-bitwise */ | ||
var ApiDocumentation_1 = require("./ApiDocumentation"); | ||
var TypeScriptHelpers_1 = require("../TypeScriptHelpers"); | ||
var DocElementParser_1 = require("../DocElementParser"); | ||
/** | ||
@@ -83,4 +85,4 @@ * Indicates the type of definition represented by a ApiItem object. | ||
this.reportError = this.reportError.bind(this); | ||
this.jsdocNode = options.jsdocNode; | ||
this.declaration = options.declaration; | ||
this.jsdocNode = options.jsdocNode; | ||
this._errorNode = options.declaration; | ||
@@ -162,4 +164,23 @@ this._state = ResolveState.Unresolved; | ||
ApiItem.prototype.onResolveReferences = function () { | ||
this.documentation = new ApiDocumentation_1.default(this, this.extractor.docItemLoader, this.extractor, this.reportError); | ||
// TODO: this.collectTypeReferences(this); | ||
var originalJsDoc = ''; | ||
if (this.jsdocNode) { | ||
originalJsDoc = TypeScriptHelpers_1.default.getJsDocComments(this.jsdocNode, this.reportError); | ||
} | ||
this.documentation = new ApiDocumentation_1.default(originalJsDoc, this.extractor.docItemLoader, this.extractor, this.reportError); | ||
// TODO: this.collectTypeReferences(this); | ||
var summaryTextCondensed = DocElementParser_1.default.getAsText(this.documentation.summary, this.reportError).replace(/\s\s/g, ' '); | ||
this.needsDocumentation = this.shouldHaveDocumentation() && summaryTextCondensed.length <= 10; | ||
if (this.kind === ApiItemKind.Package) { | ||
if (this.documentation.apiTag !== ApiDocumentation_1.ApiTag.None) { | ||
var tag = '@' + ApiDocumentation_1.ApiTag[this.documentation.apiTag].toLowerCase(); | ||
this.reportError("The " + tag + " tag is not allowed on the package, which is always public"); | ||
} | ||
this.documentation.apiTag = ApiDocumentation_1.ApiTag.Public; | ||
} | ||
if (this.documentation.preapproved) { | ||
if (!(this.getDeclaration().kind & (ts.SyntaxKind.InterfaceDeclaration | ts.SyntaxKind.ClassDeclaration))) { | ||
this.reportError('The @preapproved tag may only be applied to classes and interfaces'); | ||
this.documentation.preapproved = false; | ||
} | ||
} | ||
}; | ||
@@ -166,0 +187,0 @@ /** |
@@ -12,4 +12,8 @@ import { IApiItemOptions } from './ApiItem'; | ||
constructor(options: IApiItemOptions); | ||
/** | ||
* {@inheritdoc ApiItem.onResolveReferences } | ||
*/ | ||
protected onResolveReferences(): void; | ||
getDeclarationLine(): string; | ||
} | ||
export default ApiProperty; |
@@ -24,2 +24,11 @@ "use strict"; | ||
} | ||
/** | ||
* {@inheritdoc ApiItem.onResolveReferences } | ||
*/ | ||
ApiProperty.prototype.onResolveReferences = function () { | ||
_super.prototype.onResolveReferences.call(this); | ||
if (this.documentation.hasReadOnlyTag) { | ||
this.isReadOnly = true; | ||
} | ||
}; | ||
ApiProperty.prototype.getDeclarationLine = function () { | ||
@@ -26,0 +35,0 @@ return _super.prototype.getDeclarationLine.call(this, { |
/// <reference types="mocha" /> | ||
"use strict"; | ||
var __extends = (this && this.__extends) || function (d, b) { | ||
for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; | ||
function __() { this.constructor = d; } | ||
d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __()); | ||
}; | ||
var chai_1 = require("chai"); | ||
@@ -30,13 +25,2 @@ var ts = require("typescript"); | ||
}); | ||
var myDocumentedClass; | ||
/** | ||
* Dummy class wrapping ApiDocumentation to test its protected methods | ||
*/ | ||
var TestApiDocumentation = (function (_super) { | ||
__extends(TestApiDocumentation, _super); | ||
function TestApiDocumentation() { | ||
return _super.call(this, myDocumentedClass, extractor.docItemLoader, extractor, console.log) || this; | ||
} | ||
return TestApiDocumentation; | ||
}(ApiDocumentation_1.default)); | ||
extractor.loadExternalPackages('./testInputs/external-api-json'); | ||
@@ -47,3 +31,3 @@ // Run the analyzer once to be used by unit tests | ||
}); | ||
myDocumentedClass = extractor.package.getSortedMemberItems() | ||
var myDocumentedClass = extractor.package.getSortedMemberItems() | ||
.filter(function (apiItem) { return apiItem.name === 'MyDocumentedClass'; })[0]; | ||
@@ -53,3 +37,3 @@ describe('ApiDocumentation tests', function () { | ||
describe('ApiDocumentation internal methods', function () { | ||
var apiDoc = new TestApiDocumentation(); | ||
var apiDoc = new ApiDocumentation_1.default('Some summary\n@remarks and some remarks\n@public', extractor.docItemLoader, extractor, console.log); | ||
var apiReferenceExpr; | ||
@@ -56,0 +40,0 @@ var expected; |
@@ -25,2 +25,3 @@ import { IDocElement, IHrefLinkElement, ICodeLinkElement } from './IDocElement'; | ||
private static _hrefRegEx; | ||
static getAsText(collection: IDocElement[], reportError: (message: string) => void): string; | ||
static makeTextElement(text: string): IDocElement; | ||
@@ -27,0 +28,0 @@ static parse(tokenizer: Tokenizer, reportError: (message: string) => void): IDocElement[]; |
@@ -7,2 +7,22 @@ "use strict"; | ||
} | ||
DocElementParser.getAsText = function (collection, reportError) { | ||
var text = ''; | ||
collection.forEach(function (docElement) { | ||
switch (docElement.kind) { | ||
case 'textDocElement': | ||
text += docElement.value + " "; | ||
break; | ||
case 'linkDocElement': | ||
// links don't count towards the summary | ||
break; | ||
case 'seeDocElement': | ||
// see doesn't count towards the summary | ||
break; | ||
default: | ||
reportError('Unexpected item in IDocElement collection'); | ||
break; | ||
} | ||
}); | ||
return text.trim(); | ||
}; | ||
DocElementParser.makeTextElement = function (text) { | ||
@@ -9,0 +29,0 @@ if (!text) { |
@@ -17,2 +17,3 @@ // @public | ||
// (undocumented) | ||
class MyClass { | ||
@@ -19,0 +20,0 @@ // (undocumented) |
@@ -23,2 +23,8 @@ import Extractor from '../Extractor'; | ||
/** | ||
* We don't want to require documentation for any properties that occur | ||
* anywhere within a TypeLiteral. If this value is above 0, then we are | ||
* visiting something within a TypeLiteral. | ||
*/ | ||
private _insideTypeLiteral; | ||
/** | ||
* Compares the contents of two API files that were created using ApiFileGenerator, | ||
@@ -25,0 +31,0 @@ * and returns true if they are equivalent. Note that these files are not normally edited |
@@ -49,2 +49,3 @@ "use strict"; | ||
ApiFileGenerator.prototype.writeApiFile = function (reportFilename, extractor) { | ||
this._insideTypeLiteral = 0; | ||
var fileContent = this.generateApiFileContent(extractor); | ||
@@ -111,3 +112,5 @@ fs.writeFileSync(reportFilename, fileContent); | ||
if (apiMember.typeLiteral) { | ||
this._insideTypeLiteral += 1; | ||
this.visit(apiMember.typeLiteral); | ||
this._insideTypeLiteral -= 1; | ||
} | ||
@@ -156,3 +159,4 @@ }; | ||
} | ||
if (apiItem.documentation.isMissing) { | ||
// If we are anywhere inside a TypeLiteral, _insideTypeLiteral is greater than 0 | ||
if (this._insideTypeLiteral === 0 && apiItem.needsDocumentation) { | ||
if (footer) { | ||
@@ -159,0 +163,0 @@ footer += ' '; |
/** | ||
* The following interfaces represent Doc Elements of a | ||
* documentation block. | ||
* | ||
* @remarks if adding a new 'kind', then it is essential that you update the | ||
* methods within DocElementParser (getasText() and parse()). | ||
*/ | ||
@@ -5,0 +8,0 @@ export interface IBaseDocElement { |
@@ -39,3 +39,3 @@ /// <reference types="mocha" /> | ||
function TestApiDocumentation() { | ||
return _super.call(this, myDocumentedClass, extractor.docItemLoader, extractor, console.log) || this; | ||
return _super.call(this, 'Some summary\n@remarks and some remarks\n@public', extractor.docItemLoader, extractor, console.log) || this; | ||
} | ||
@@ -148,3 +148,3 @@ TestApiDocumentation.prototype.parseParam = function (tokenizer) { | ||
var apiDoc = new TestApiDocumentation(); | ||
// Don't include the "@param" in the doc string, parseParam() expects this to be processed in a | ||
// Don't include the "@param" in the doc string, parseParam() expects this to be processed in a | ||
// previous step. | ||
@@ -151,0 +151,0 @@ var docs = 'x - The height in {@link http://wikipedia.org/pixel_units}'; |
{ | ||
"name": "@microsoft/api-extractor", | ||
"version": "1.1.7", | ||
"version": "1.1.8", | ||
"description": "Validatation, documentation, and auditing for the exported API of a TypeScript package", | ||
@@ -5,0 +5,0 @@ "main": "lib/index.js", |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
531848
6307