Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

@microsoft/tsdoc

Package Overview
Dependencies
Maintainers
2
Versions
49
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@microsoft/tsdoc - npm Package Compare versions

Comparing version 0.8.1 to 0.9.0

CHANGELOG.json
lib/nodes/DocExcerpt.d.ts
lib/nodes/DocExcerpt.js
lib/nodes/DocExcerpt.js.map
lib/nodes/DocInlineTagBase.d.ts
lib/nodes/DocInlineTagBase.js
lib/nodes/DocInlineTagBase.js.map

55

CHANGELOG.md
# Change Log - @microsoft/tsdoc
This log was last generated on Wed, 17 Oct 2018 04:47:19 GMT and should not be manually modified.
## 0.9.0
Wed, 17 Oct 2018 04:47:19 GMT
### Minor changes
- (API change) Change `DocBlock` to have a `DocSection` property rather than inheriting from `DocSection`; this eliminates confusion about which nodes belong to the container
- (API change) Rename `DocParticle` to `DocExcerpt`, and eliminate the `Excerpt` class
- (API change) Eliminate `DocNodeLeaf`, since now `DocExcerpt` is the only class that can represent excerpts
- (API change) Remove `DocNode.updateParameters()` because it is no longer needed
- (API change) Spacing is now represented as a normal `DocExcerpt`, rather than via a special `Excerpt.spacingAfterContent`
- (API change) Simplify `DocNodeTransforms.trimSpacesInParagraph()` to no longer merge/remap excerpts during the transformation. If we need this information, we will track it differently.
## 0.8.1
Sun, 07 Oct 2018 06:30:34 GMT
### Patches
- Improve error reporting for declaration references that are probably missing a `"#"` delimiter

@@ -8,2 +26,6 @@ - Rename `DocCodeFence` to `DocFencedCode`

## 0.8.0
Wed, 03 Oct 2018 02:43:47 GMT
### Minor changes
- Introduce a distinction between "defined" tags (i.e. recognized) versus "supported" tags (i.e. implemented by the tool)

@@ -18,2 +40,6 @@ - The parser optionally reports usage of undefined tags

## 0.7.0
Tue, 02 Oct 2018 02:35:35 GMT
### Minor changes
- Add support for `@defaultValue` tag

@@ -23,2 +49,6 @@ - Add support for `@typeParam` tag

## 0.6.0
Mon, 01 Oct 2018 22:11:24 GMT
### Minor changes
- Add support for `@link` tags using the new declaration reference syntax

@@ -31,2 +61,6 @@ - Add support for `@inheritDoc` tags

## 0.5.0
Tue, 25 Sep 2018 03:04:06 GMT
### Minor changes
- Add a new API `DocNode.updateParameters()` that allows a `DocNode` object to be updated after it was created; the tree nodes are no longer immutable

@@ -37,4 +71,6 @@ - Add `DocNodeTransforms.trimSpacesInParagraphNodes()` for collapsing whitespace inside `DocParagraph` subtrees

## 0.4.1
Mon, 30 Aug 2018
Fri, 31 Aug 2018 03:32:18 GMT
### Patches
- Improve the error location reporting for DocErrorText objects

@@ -44,4 +80,6 @@ - Separate the **api-demo** sample into a "simple" scenario which parses a simple text string, and an "advanced" scenario which uses the TypeScript compiler API to extract comments and parse custom TSDoc tags

## 0.4.0
Mon, 27 Aug 2018
Tue, 28 Aug 2018 03:17:20 GMT
### Minor changes
- Rename `DocCodeSpan.text` to `DocCodeSpan.code` and model the delimiters using particles

@@ -53,4 +91,6 @@ - Add support for code fences (`DocCodeFence`)

## 0.3.0
Fri, 24 Aug 2018
Sat, 25 Aug 2018 05:53:56 GMT
### Minor changes
- Add TextRange.isEmpty()

@@ -61,4 +101,6 @@ - Improve the ModifierTagSet API

## 0.2.0
Thu, 23 Aug 2018
Fri, 24 Aug 2018 01:19:56 GMT
### Minor changes
- Rename `CoreTags` to `StandardTags` so we can include non-core tags in the standard definitions

@@ -71,4 +113,7 @@ - Rename `CoreModifierTagSet` to `StandardModifierTagSet` and convert properties to functions

## 0.1.0
Thu, 16 Aug 2018
Thu, 16 Aug 2018 18:18:02 GMT
### Minor changes
- Initial release of the TSDoc library! :-)

1

lib/index.d.ts

@@ -6,3 +6,2 @@ export { StandardTags } from './details/StandardTags';

export * from './nodes';
export { Excerpt } from './parser/Excerpt';
export { ParserContext } from './parser/ParserContext';

@@ -9,0 +8,0 @@ export { ParserMessage, IParserMessageParameters } from './parser/ParserMessage';

2

lib/index.js

@@ -13,4 +13,2 @@ "use strict";

__export(require("./nodes"));
var Excerpt_1 = require("./parser/Excerpt");
exports.Excerpt = Excerpt_1.Excerpt;
var ParserContext_1 = require("./parser/ParserContext");

@@ -17,0 +15,0 @@ exports.ParserContext = ParserContext_1.ParserContext;

30

lib/nodes/DocBlock.d.ts

@@ -1,3 +0,3 @@

import { DocNodeKind, DocNode } from './DocNode';
import { DocSection, IDocSectionParameters } from './DocSection';
import { DocNodeKind, DocNode, IDocNodeParameters, IDocNodeParsedParameters } from './DocNode';
import { DocSection } from './DocSection';
import { DocBlockTag } from './DocBlockTag';

@@ -7,13 +7,20 @@ /**

*/
export interface IDocBlockParameters extends IDocSectionParameters {
export interface IDocBlockParameters extends IDocNodeParameters {
blockTag: DocBlockTag;
}
/**
* Constructor parameters for {@link DocBlock}.
*/
export interface IDocBlockParsedParameters extends IDocNodeParsedParameters {
blockTag: DocBlockTag;
}
/**
* Represents a section that is introduced by a TSDoc block tag.
* For example, an `@example` block.
*/
export declare class DocBlock extends DocSection {
/** {@inheritDoc} */
export declare class DocBlock extends DocNode {
/** @override */
readonly kind: DocNodeKind;
private _blockTag;
private readonly _blockTag;
private readonly _content;
/**

@@ -23,3 +30,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocBlockParameters);
constructor(parameters: IDocBlockParameters | IDocBlockParsedParameters);
/**

@@ -29,9 +36,8 @@ * The TSDoc tag that introduces this section.

readonly blockTag: DocBlockTag;
/** @override */
updateParameters(parameters: IDocBlockParameters): void;
/**
* {@inheritDoc}
* @override
* The TSDoc tag that introduces this section.
*/
getChildNodes(): ReadonlyArray<DocNode>;
readonly content: DocSection;
/** @override */
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

29

lib/nodes/DocBlock.js

@@ -16,2 +16,3 @@ "use strict";

Object.defineProperty(exports, "__esModule", { value: true });
var DocNode_1 = require("./DocNode");
var DocSection_1 = require("./DocSection");

@@ -30,4 +31,6 @@ /**

var _this = _super.call(this, parameters) || this;
/** {@inheritDoc} */
/** @override */
_this.kind = "Block" /* Block */;
_this._blockTag = parameters.blockTag;
_this._content = new DocSection_1.DocSection({});
return _this;

@@ -45,17 +48,19 @@ }

});
Object.defineProperty(DocBlock.prototype, "content", {
/**
* The TSDoc tag that introduces this section.
*/
get: function () {
return this._content;
},
enumerable: true,
configurable: true
});
/** @override */
DocBlock.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._blockTag = parameters.blockTag;
DocBlock.prototype.onGetChildNodes = function () {
return [this.blockTag, this._content];
};
/**
* {@inheritDoc}
* @override
*/
DocBlock.prototype.getChildNodes = function () {
return [this.blockTag].concat(_super.prototype.getChildNodes.call(this));
};
return DocBlock;
}(DocSection_1.DocSection));
}(DocNode_1.DocNode));
exports.DocBlock = DocBlock;
//# sourceMappingURL=DocBlock.js.map

27

lib/nodes/DocBlockTag.d.ts

@@ -1,17 +0,25 @@

import { DocNodeKind } from './DocNode';
import { DocNodeLeaf, IDocNodeLeafParameters } from './DocNodeLeaf';
import { DocNodeKind, DocNode, IDocNodeParameters, IDocNodeParsedParameters } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';
/**
* Constructor parameters for {@link DocBlockTag}.
*/
export interface IDocBlockTagParameters extends IDocNodeLeafParameters {
export interface IDocBlockTagParameters extends IDocNodeParameters {
tagName: string;
}
/**
* Constructor parameters for {@link DocBlockTag}.
*/
export interface IDocBlockTagParsedParameters extends IDocNodeParsedParameters {
tagName: string;
tagNameExcerpt: TokenSequence;
}
/**
* Represents a TSDoc block tag such as `@param` or `@public`.
*/
export declare class DocBlockTag extends DocNodeLeaf {
/** {@inheritDoc} */
export declare class DocBlockTag extends DocNode {
/** @override */
readonly kind: DocNodeKind;
private _tagName;
private _tagNameWithUpperCase;
private readonly _tagName;
private readonly _tagNameWithUpperCase;
private readonly _tagNameExcerpt;
/**

@@ -21,3 +29,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocBlockTagParameters);
constructor(parameters: IDocBlockTagParameters | IDocBlockTagParsedParameters);
/**

@@ -34,3 +42,4 @@ * The TSDoc tag name. TSDoc tag names start with an at-sign ("@") followed

/** @override */
updateParameters(parameters: IDocBlockTagParameters): void;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
getTokenSequence(): TokenSequence;
}

32

lib/nodes/DocBlockTag.js

@@ -16,4 +16,5 @@ "use strict";

Object.defineProperty(exports, "__esModule", { value: true });
var DocNodeLeaf_1 = require("./DocNodeLeaf");
var DocNode_1 = require("./DocNode");
var StringChecks_1 = require("../parser/StringChecks");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -30,4 +31,13 @@ * Represents a TSDoc block tag such as `@param` or `@public`.

var _this = _super.call(this, parameters) || this;
/** {@inheritDoc} */
/** @override */
_this.kind = "BlockTag" /* BlockTag */;
StringChecks_1.StringChecks.validateTSDocTagName(parameters.tagName);
_this._tagName = parameters.tagName;
_this._tagNameWithUpperCase = parameters.tagName.toUpperCase();
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
_this._tagNameExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "BlockTag" /* BlockTag */,
content: parameters.tagNameExcerpt
});
}
return _this;

@@ -58,11 +68,17 @@ }

/** @override */
DocBlockTag.prototype.updateParameters = function (parameters) {
StringChecks_1.StringChecks.validateTSDocTagName(parameters.tagName);
_super.prototype.updateParameters.call(this, parameters);
this._tagName = parameters.tagName;
this._tagNameWithUpperCase = this.tagName.toUpperCase();
DocBlockTag.prototype.onGetChildNodes = function () {
return [
this._tagNameExcerpt
];
};
DocBlockTag.prototype.getTokenSequence = function () {
if (!this._tagNameExcerpt) {
throw new Error('DocBlockTag.getTokenSequence() failed because this object did not'
+ ' originate from a parsed input');
}
return this._tagNameExcerpt.content;
};
return DocBlockTag;
}(DocNodeLeaf_1.DocNodeLeaf));
}(DocNode_1.DocNode));
exports.DocBlockTag = DocBlockTag;
//# sourceMappingURL=DocBlockTag.js.map

31

lib/nodes/DocCodeSpan.d.ts

@@ -1,3 +0,3 @@

import { DocNodeKind, IDocNodeParameters, DocNode } from './DocNode';
import { Excerpt } from '../parser/Excerpt';
import { DocNodeKind, IDocNodeParameters, DocNode, IDocNodeParsedParameters } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';
/**

@@ -7,8 +7,13 @@ * Constructor parameters for {@link DocCodeSpan}.

export interface IDocCodeSpanParameters extends IDocNodeParameters {
openingDelimiterExcerpt?: Excerpt;
codeExcerpt?: Excerpt;
code: string;
closingDelimiterExcerpt?: Excerpt;
}
/**
* Constructor parameters for {@link DocCodeSpan}.
*/
export interface IDocCodeSpanParsedParameters extends IDocNodeParsedParameters {
openingDelimiterExcerpt: TokenSequence;
codeExcerpt: TokenSequence;
closingDelimiterExcerpt: TokenSequence;
}
/**
* Represents CommonMark-style code span, i.e. code surrounded by

@@ -20,5 +25,6 @@ * backtick characters.

readonly kind: DocNodeKind;
private _openingDelimiterParticle;
private _codeParticle;
private _closingDelimiterParticle;
private readonly _openingDelimiterExcerpt;
private _code;
private readonly _codeExcerpt;
private readonly _closingDelimiterExcerpt;
/**

@@ -28,3 +34,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocCodeSpanParameters);
constructor(parameters: IDocCodeSpanParameters | IDocCodeSpanParsedParameters);
/**

@@ -35,8 +41,3 @@ * The text that should be rendered as code, excluding the backtick delimiters.

/** @override */
updateParameters(parameters: IDocCodeSpanParameters): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

54

lib/nodes/DocCodeSpan.js

@@ -17,3 +17,3 @@ "use strict";

var DocNode_1 = require("./DocNode");
var DocParticle_1 = require("./DocParticle");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -33,2 +33,19 @@ * Represents CommonMark-style code span, i.e. code surrounded by

_this.kind = "CodeSpan" /* CodeSpan */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
_this._openingDelimiterExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "CodeSpan_OpeningDelimiter" /* CodeSpan_OpeningDelimiter */,
content: parameters.openingDelimiterExcerpt
});
_this._codeExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "CodeSpan_Code" /* CodeSpan_Code */,
content: parameters.codeExcerpt
});
_this._closingDelimiterExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "CodeSpan_ClosingDelimiter" /* CodeSpan_ClosingDelimiter */,
content: parameters.closingDelimiterExcerpt
});
}
else {
_this._code = parameters.code;
}
return _this;

@@ -41,3 +58,6 @@ }

get: function () {
return this._codeParticle.content;
if (this._code === undefined) {
this._code = this._codeExcerpt.content.toString();
}
return this._code;
},

@@ -48,29 +68,7 @@ enumerable: true,

/** @override */
DocCodeSpan.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._openingDelimiterParticle = new DocParticle_1.DocParticle({
particleId: 'openingDelimiter',
excerpt: parameters.openingDelimiterExcerpt,
content: '`'
});
this._codeParticle = new DocParticle_1.DocParticle({
particleId: 'code',
excerpt: parameters.codeExcerpt,
content: parameters.code
});
this._closingDelimiterParticle = new DocParticle_1.DocParticle({
particleId: 'closingDelimiter',
excerpt: parameters.closingDelimiterExcerpt,
content: '`'
});
};
/**
* {@inheritDoc}
* @override
*/
DocCodeSpan.prototype.getChildNodes = function () {
DocCodeSpan.prototype.onGetChildNodes = function () {
return [
this._openingDelimiterParticle,
this._codeParticle,
this._closingDelimiterParticle
this._openingDelimiterExcerpt,
this._codeExcerpt,
this._closingDelimiterExcerpt
];

@@ -77,0 +75,0 @@ };

7

lib/nodes/DocComment.d.ts

@@ -94,7 +94,4 @@ import { DocNode, DocNodeKind, IDocNodeParameters } from './DocNode';

appendCustomBlock(block: DocBlock): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
/** @override */
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

11

lib/nodes/DocComment.js

@@ -60,8 +60,5 @@ "use strict";

};
/**
* {@inheritDoc}
* @override
*/
DocComment.prototype.getChildNodes = function () {
return DocNode_1.DocNode.trimUndefinedNodes([
/** @override */
DocComment.prototype.onGetChildNodes = function () {
return [
this.summarySection,

@@ -75,3 +72,3 @@ this.remarksBlock,

this.inheritDocTag
], this.modifierTagSet.nodes));
], this.modifierTagSet.nodes);
};

@@ -78,0 +75,0 @@ return DocComment;

37

lib/nodes/DocDeclarationReference.d.ts

@@ -1,4 +0,4 @@

import { DocNode, DocNodeKind, IDocNodeParameters } from './DocNode';
import { DocNode, DocNodeKind, IDocNodeParameters, IDocNodeParsedParameters } from './DocNode';
import { DocMemberReference } from './DocMemberReference';
import { Excerpt } from '../parser/Excerpt';
import { TokenSequence } from '../parser/TokenSequence';
/**

@@ -8,10 +8,17 @@ * Constructor parameters for {@link DocDeclarationReference}.

export interface IDocDeclarationReferenceParameters extends IDocNodeParameters {
packageNameExcerpt?: Excerpt;
packageName?: string;
importPathExcerpt?: Excerpt;
importPath?: string;
importHashExcerpt?: Excerpt;
memberReferences?: DocMemberReference[];
}
/**
* Constructor parameters for {@link DocDeclarationReference}.
*/
export interface IDocDeclarationReferenceParsedParameters extends IDocNodeParsedParameters {
packageNameExcerpt?: TokenSequence;
importPathExcerpt?: TokenSequence;
importHashExcerpt?: TokenSequence;
spacingAfterImportHashExcerpt?: TokenSequence;
memberReferences?: DocMemberReference[];
}
/**
* Represents a declaration reference.

@@ -26,6 +33,9 @@ *

readonly kind: DocNodeKind;
private _packageNameParticle;
private _importPathParticle;
private _importHashParticle;
private _memberReferences;
private _packageName;
private readonly _packageNameExcerpt;
private _importPath;
private readonly _importPathExcerpt;
private readonly _importHashExcerpt;
private readonly _spacingAfterImportHashExcerpt;
private readonly _memberReferences;
/**

@@ -35,3 +45,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocDeclarationReferenceParameters);
constructor(parameters: IDocDeclarationReferenceParameters | IDocDeclarationReferenceParsedParameters);
/**

@@ -60,8 +70,3 @@ * The optional package name, which may optionally include an NPM scope.

/** @override */
updateParameters(parameters: IDocDeclarationReferenceParameters): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

102

lib/nodes/DocDeclarationReference.js

@@ -17,3 +17,3 @@ "use strict";

var DocNode_1 = require("./DocNode");
var DocParticle_1 = require("./DocParticle");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -33,5 +33,40 @@ * Represents a declaration reference.

function DocDeclarationReference(parameters) {
var _a;
var _this = _super.call(this, parameters) || this;
/** {@inheritDoc} */
_this.kind = "DeclarationReference" /* DeclarationReference */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
if (parameters.packageNameExcerpt) {
_this._packageNameExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "DeclarationReference_PackageName" /* DeclarationReference_PackageName */,
content: parameters.packageNameExcerpt
});
}
if (parameters.importPathExcerpt) {
_this._importPathExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "DeclarationReference_ImportPath" /* DeclarationReference_ImportPath */,
content: parameters.importPathExcerpt
});
}
if (parameters.importHashExcerpt) {
_this._importHashExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "DeclarationReference_ImportHash" /* DeclarationReference_ImportHash */,
content: parameters.importHashExcerpt
});
}
if (parameters.spacingAfterImportHashExcerpt) {
_this._spacingAfterImportHashExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterImportHashExcerpt
});
}
}
else {
_this._packageName = parameters.packageName;
_this._importPath = parameters.importPath;
}
_this._memberReferences = [];
if (parameters.memberReferences) {
(_a = _this._memberReferences).push.apply(_a, parameters.memberReferences);
}
return _this;

@@ -46,8 +81,8 @@ }

get: function () {
if (this._packageNameParticle) {
return this._packageNameParticle.content;
if (this._packageName === undefined) {
if (this._packageNameExcerpt !== undefined) {
this._packageName = this._packageNameExcerpt.content.toString();
}
}
else {
return undefined;
}
return this._packageName;
},

@@ -68,8 +103,8 @@ enumerable: true,

get: function () {
if (this._importPathParticle) {
return this._importPathParticle.content;
if (this._importPath === undefined) {
if (this._importPathExcerpt !== undefined) {
this._importPath = this._importPathExcerpt.content.toString();
}
}
else {
return undefined;
}
return this._importPath;
},

@@ -92,41 +127,10 @@ enumerable: true,

/** @override */
DocDeclarationReference.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._packageNameParticle = undefined;
this._importPathParticle = undefined;
this._importHashParticle = undefined;
if (parameters.packageName) {
this._packageNameParticle = new DocParticle_1.DocParticle({
particleId: 'packageName',
content: parameters.packageName,
excerpt: parameters.packageNameExcerpt
});
}
if (parameters.importPath) {
this._importPathParticle = new DocParticle_1.DocParticle({
particleId: 'importPath',
content: parameters.importPath || '',
excerpt: parameters.importPathExcerpt
});
}
if ((parameters.packageName && this._importPathParticle) || parameters.importHashExcerpt) {
this._importHashParticle = new DocParticle_1.DocParticle({
particleId: 'importHash',
content: '#',
excerpt: parameters.importHashExcerpt
});
}
this._memberReferences = parameters.memberReferences || [];
DocDeclarationReference.prototype.onGetChildNodes = function () {
return [
this._packageNameExcerpt,
this._importPathExcerpt,
this._importHashExcerpt,
this._spacingAfterImportHashExcerpt
].concat(this._memberReferences);
};
/**
* {@inheritDoc}
* @override
*/
DocDeclarationReference.prototype.getChildNodes = function () {
return DocNode_1.DocNode.trimUndefinedNodes([
this._packageNameParticle,
this._importPathParticle,
this._importHashParticle
].concat(this._memberReferences));
};
return DocDeclarationReference;

@@ -133,0 +137,0 @@ }(DocNode_1.DocNode));

19

lib/nodes/DocErrorText.d.ts

@@ -1,3 +0,2 @@

import { DocNodeKind } from './DocNode';
import { DocNodeLeaf, IDocNodeLeafParameters } from './DocNodeLeaf';
import { DocNodeKind, DocNode, IDocNodeParsedParameters } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';

@@ -7,4 +6,4 @@ /**

*/
export interface IDocErrorTextParameters extends IDocNodeLeafParameters {
text: string;
export interface IDocErrorTextParsedParameters extends IDocNodeParsedParameters {
textExcerpt: TokenSequence;
errorMessage: string;

@@ -17,8 +16,9 @@ errorLocation: TokenSequence;

*/
export declare class DocErrorText extends DocNodeLeaf {
export declare class DocErrorText extends DocNode {
/** {@inheritDoc} */
readonly kind: DocNodeKind;
private _text;
private _errorMessage;
private _errorLocation;
private readonly _textExcerpt;
private readonly _errorMessage;
private readonly _errorLocation;
/**

@@ -28,3 +28,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocErrorTextParameters);
constructor(parameters: IDocErrorTextParsedParameters);
/**

@@ -35,2 +35,3 @@ * The characters that should be rendered as plain text because they

readonly text: string;
readonly textExcerpt: TokenSequence | undefined;
/**

@@ -51,3 +52,3 @@ * A description of why the character could not be parsed.

/** @override */
updateParameters(parameters: IDocErrorTextParameters): void;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

35

lib/nodes/DocErrorText.js

@@ -16,3 +16,4 @@ "use strict";

Object.defineProperty(exports, "__esModule", { value: true });
var DocNodeLeaf_1 = require("./DocNodeLeaf");
var DocNode_1 = require("./DocNode");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -32,2 +33,8 @@ * Represents a span of text that contained invalid markup.

_this.kind = "ErrorText" /* ErrorText */;
_this._textExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "ErrorText" /* ErrorText */,
content: parameters.textExcerpt
});
_this._errorMessage = parameters.errorMessage;
_this._errorLocation = parameters.errorLocation;
return _this;

@@ -41,2 +48,5 @@ }

get: function () {
if (this._text === undefined) {
this._text = this._textExcerpt.toString();
}
return this._text;

@@ -47,2 +57,14 @@ },

});
Object.defineProperty(DocErrorText.prototype, "textExcerpt", {
get: function () {
if (this._textExcerpt) {
return this._textExcerpt.content;
}
else {
return undefined;
}
},
enumerable: true,
configurable: true
});
Object.defineProperty(DocErrorText.prototype, "errorMessage", {

@@ -75,11 +97,10 @@ /**

/** @override */
DocErrorText.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._text = parameters.text;
this._errorMessage = parameters.errorMessage;
this._errorLocation = parameters.errorLocation;
DocErrorText.prototype.onGetChildNodes = function () {
return [
this._textExcerpt
];
};
return DocErrorText;
}(DocNodeLeaf_1.DocNodeLeaf));
}(DocNode_1.DocNode));
exports.DocErrorText = DocErrorText;
//# sourceMappingURL=DocErrorText.js.map

29

lib/nodes/DocEscapedText.d.ts

@@ -1,9 +0,10 @@

import { DocNodeKind } from './DocNode';
import { DocNodeLeaf, IDocNodeLeafParameters } from './DocNodeLeaf';
import { DocNodeKind, IDocNodeParsedParameters, DocNode } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';
/**
* Constructor parameters for {@link DocEscapedText}.
*/
export interface IDocEscapedTextParameters extends IDocNodeLeafParameters {
export interface IDocEscapedTextParsedParameters extends IDocNodeParsedParameters {
escapeStyle: EscapeStyle;
text: string;
encodedTextExcerpt: TokenSequence;
decodedText: string;
}

@@ -26,7 +27,9 @@ /**

*/
export declare class DocEscapedText extends DocNodeLeaf {
export declare class DocEscapedText extends DocNode {
/** {@inheritDoc} */
readonly kind: DocNodeKind;
private _escapeStyle;
private _text;
private readonly _escapeStyle;
private _encodedText;
private readonly _encodedTextExcerpt;
private readonly _decodedText;
/**

@@ -36,3 +39,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocEscapedTextParameters);
constructor(parameters: IDocEscapedTextParsedParameters);
/**

@@ -43,7 +46,11 @@ * The style of escaping to be performed.

/**
* The text content to be escaped.
* The text sequence including escapes.
*/
readonly text: string;
readonly encodedText: string;
/**
* The text without escaping.
*/
readonly decodedText: string;
/** @override */
updateParameters(parameters: IDocEscapedTextParameters): void;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

38

lib/nodes/DocEscapedText.js

@@ -16,3 +16,4 @@ "use strict";

Object.defineProperty(exports, "__esModule", { value: true });
var DocNodeLeaf_1 = require("./DocNodeLeaf");
var DocNode_1 = require("./DocNode");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -45,2 +46,8 @@ * The style of escaping to be used with DocEscapedText.

_this.kind = "EscapedText" /* EscapedText */;
_this._escapeStyle = parameters.escapeStyle;
_this._encodedTextExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "EscapedText" /* EscapedText */,
content: parameters.encodedTextExcerpt
});
_this._decodedText = parameters.decodedText;
return _this;

@@ -58,8 +65,11 @@ }

});
Object.defineProperty(DocEscapedText.prototype, "text", {
Object.defineProperty(DocEscapedText.prototype, "encodedText", {
/**
* The text content to be escaped.
* The text sequence including escapes.
*/
get: function () {
return this._text;
if (this._encodedText === undefined) {
this._encodedText = this._encodedTextExcerpt.content.toString();
}
return this._encodedText;
},

@@ -69,11 +79,21 @@ enumerable: true,

});
Object.defineProperty(DocEscapedText.prototype, "decodedText", {
/**
* The text without escaping.
*/
get: function () {
return this._decodedText;
},
enumerable: true,
configurable: true
});
/** @override */
DocEscapedText.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._escapeStyle = parameters.escapeStyle;
this._text = parameters.text;
DocEscapedText.prototype.onGetChildNodes = function () {
return [
this._encodedTextExcerpt
];
};
return DocEscapedText;
}(DocNodeLeaf_1.DocNodeLeaf));
}(DocNode_1.DocNode));
exports.DocEscapedText = DocEscapedText;
//# sourceMappingURL=DocEscapedText.js.map

46

lib/nodes/DocFencedCode.d.ts

@@ -1,3 +0,3 @@

import { DocNodeKind, IDocNodeParameters, DocNode } from './DocNode';
import { Excerpt } from '../parser/Excerpt';
import { DocNodeKind, IDocNodeParameters, DocNode, IDocNodeParsedParameters } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';
/**

@@ -7,10 +7,19 @@ * Constructor parameters for {@link DocFencedCode}.

export interface IDocFencedCodeParameters extends IDocNodeParameters {
openingDelimiterExcerpt?: Excerpt;
languageExcerpt?: Excerpt;
language?: string | 'ts' | '';
codeExcerpt?: Excerpt;
language: string;
code: string;
closingDelimiterExcerpt?: Excerpt;
}
/**
* Constructor parameters for {@link DocFencedCode}.
*/
export interface IDocFencedCodeParsedParameters extends IDocNodeParsedParameters {
openingFenceExcerpt: TokenSequence;
spacingAfterOpeningFenceExcerpt?: TokenSequence;
languageExcerpt?: TokenSequence;
spacingAfterLanguageExcerpt?: TokenSequence;
codeExcerpt: TokenSequence;
spacingBeforeClosingFenceExcerpt?: TokenSequence;
closingFenceExcerpt: TokenSequence;
spacingAfterClosingFenceExcerpt?: TokenSequence;
}
/**
* Represents CommonMark-style code fence, i.e. a block of program code that

@@ -23,6 +32,12 @@ * starts and ends with a line comprised of three backticks. The opening delimiter

readonly kind: DocNodeKind;
private _openingDelimiterParticle;
private _languageParticle;
private _codeParticle;
private _closingDelimiterParticle;
private readonly _openingFenceExcerpt;
private readonly _spacingAfterOpeningFenceExcerpt;
private _language;
private readonly _languageExcerpt;
private readonly _spacingAfterLanguageExcerpt;
private _code;
private readonly _codeExcerpt;
private readonly _spacingBeforeClosingFenceExcerpt;
private readonly _closingFenceExcerpt;
private readonly _spacingAfterClosingFenceExcerpt;
/**

@@ -32,3 +47,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocFencedCodeParameters);
constructor(parameters: IDocFencedCodeParameters | IDocFencedCodeParsedParameters);
/**

@@ -55,8 +70,3 @@ * A name that can optionally be included after the opening code fence delimiter,

/** @override */
updateParameters(parameters: IDocFencedCodeParameters): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

108

lib/nodes/DocFencedCode.js

@@ -17,3 +17,3 @@ "use strict";

var DocNode_1 = require("./DocNode");
var DocParticle_1 = require("./DocParticle");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -34,2 +34,50 @@ * Represents CommonMark-style code fence, i.e. a block of program code that

_this.kind = "FencedCode" /* FencedCode */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
_this._openingFenceExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "FencedCode_OpeningFence" /* FencedCode_OpeningFence */,
content: parameters.openingFenceExcerpt
});
if (parameters.spacingAfterOpeningFenceExcerpt) {
_this._spacingAfterOpeningFenceExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterOpeningFenceExcerpt
});
}
if (parameters.languageExcerpt) {
_this._languageExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "FencedCode_Language" /* FencedCode_Language */,
content: parameters.languageExcerpt
});
}
if (parameters.spacingAfterLanguageExcerpt) {
_this._spacingAfterLanguageExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterLanguageExcerpt
});
}
_this._codeExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "FencedCode_Code" /* FencedCode_Code */,
content: parameters.codeExcerpt
});
if (parameters.spacingBeforeClosingFenceExcerpt) {
_this._spacingBeforeClosingFenceExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingBeforeClosingFenceExcerpt
});
}
_this._closingFenceExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "FencedCode_ClosingFence" /* FencedCode_ClosingFence */,
content: parameters.closingFenceExcerpt
});
if (parameters.spacingAfterClosingFenceExcerpt) {
_this._spacingAfterClosingFenceExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterClosingFenceExcerpt
});
}
}
else {
_this._code = parameters.code;
_this._language = parameters.language;
}
return _this;

@@ -54,3 +102,11 @@ }

get: function () {
return this._languageParticle.content;
if (this._language === undefined) {
if (this._languageExcerpt !== undefined) {
this._language = this._languageExcerpt.content.toString();
}
else {
this._language = '';
}
}
return this.language;
},

@@ -65,3 +121,8 @@ enumerable: true,

get: function () {
return this._codeParticle.content;
if (this._code === undefined) {
if (this._codeExcerpt !== undefined) {
this._code = this._codeExcerpt.content.toString();
}
}
return this._code;
},

@@ -72,35 +133,12 @@ enumerable: true,

/** @override */
DocFencedCode.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._openingDelimiterParticle = new DocParticle_1.DocParticle({
particleId: 'openingDelimiter',
excerpt: parameters.openingDelimiterExcerpt,
content: '```'
});
this._languageParticle = new DocParticle_1.DocParticle({
particleId: 'language',
excerpt: parameters.languageExcerpt,
content: parameters.language || ''
});
this._codeParticle = new DocParticle_1.DocParticle({
particleId: 'code',
excerpt: parameters.codeExcerpt,
content: parameters.code
});
this._closingDelimiterParticle = new DocParticle_1.DocParticle({
particleId: 'closingDelimiter',
excerpt: parameters.closingDelimiterExcerpt,
content: '```'
});
};
/**
* {@inheritDoc}
* @override
*/
DocFencedCode.prototype.getChildNodes = function () {
DocFencedCode.prototype.onGetChildNodes = function () {
return [
this._openingDelimiterParticle,
this._languageParticle,
this._codeParticle,
this._closingDelimiterParticle
this._openingFenceExcerpt,
this._spacingAfterOpeningFenceExcerpt,
this._languageExcerpt,
this._spacingAfterLanguageExcerpt,
this._codeExcerpt,
this._spacingBeforeClosingFenceExcerpt,
this._closingFenceExcerpt,
this._spacingAfterClosingFenceExcerpt
];

@@ -107,0 +145,0 @@ };

59

lib/nodes/DocHtmlAttribute.d.ts

@@ -1,3 +0,3 @@

import { DocNode, DocNodeKind, IDocNodeParameters } from './DocNode';
import { Excerpt } from '../parser/Excerpt';
import { DocNode, DocNodeKind, IDocNodeParameters, IDocNodeParsedParameters } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';
/**

@@ -7,12 +7,20 @@ * Constructor parameters for {@link DocHtmlAttribute}.

export interface IDocHtmlAttributeParameters extends IDocNodeParameters {
attributeNameExcerpt?: Excerpt;
attributeName: string;
spacingAfterAttributeName: string | undefined;
equalsExcerpt?: Excerpt;
spacingAfterEquals: string | undefined;
attributeValueExcerpt?: Excerpt;
attributeValue: string;
spacingAfterAttributeValue: string | undefined;
name: string;
spacingAfterName?: string;
spacingAfterEquals?: string;
value: string;
spacingAfterValue?: string;
}
/**
* Constructor parameters for {@link DocHtmlAttribute}.
*/
export interface IDocHtmlAttributeParsedParameters extends IDocNodeParsedParameters {
nameExcerpt: TokenSequence;
spacingAfterNameExcerpt?: TokenSequence;
equalsExcerpt: TokenSequence;
spacingAfterEqualsExcerpt?: TokenSequence;
valueExcerpt: TokenSequence;
spacingAfterValueExcerpt?: TokenSequence;
}
/**
* Represents an HTML attribute inside a DocHtmlStartTag or DocHtmlEndTag.

@@ -25,5 +33,13 @@ *

readonly kind: DocNodeKind;
private _attributeNameParticle;
private _equalsParticle;
private _attributeValueParticle;
private _name;
private readonly _nameExcerpt;
private _spacingAfterName;
private readonly _spacingAfterNameExcerpt;
private readonly _equalsExcerpt;
private _spacingAfterEquals;
private readonly _spacingAfterEqualsExcerpt;
private _value;
private readonly _valueExcerpt;
private _spacingAfterValue;
private readonly _spacingAfterValueExcerpt;
/**

@@ -33,7 +49,7 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocHtmlAttributeParameters);
constructor(parameters: IDocHtmlAttributeParameters | IDocHtmlAttributeParsedParameters);
/**
* The HTML attribute name.
*/
readonly attributeName: string;
readonly name: string;
/**

@@ -43,3 +59,3 @@ * Explicit whitespace that a renderer should insert after the HTML attribute name.

*/
readonly spacingAfterAttributeName: string | undefined;
readonly spacingAfterName: string | undefined;
/**

@@ -53,3 +69,3 @@ * Explicit whitespace that a renderer should insert after the "=".

*/
readonly attributeValue: string;
readonly value: string;
/**

@@ -59,10 +75,5 @@ * Explicit whitespace that a renderer should insert after the HTML attribute name.

*/
readonly spacingAfterAttributeValue: string | undefined;
readonly spacingAfterValue: string | undefined;
/** @override */
updateParameters(parameters: IDocHtmlAttributeParameters): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

116

lib/nodes/DocHtmlAttribute.js

@@ -17,3 +17,3 @@ "use strict";

var DocNode_1 = require("./DocNode");
var DocParticle_1 = require("./DocParticle");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -34,5 +34,44 @@ * Represents an HTML attribute inside a DocHtmlStartTag or DocHtmlEndTag.

_this.kind = "HtmlAttribute" /* HtmlAttribute */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
_this._nameExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "HtmlAttribute_Name" /* HtmlAttribute_Name */,
content: parameters.nameExcerpt
});
if (parameters.spacingAfterNameExcerpt) {
_this._spacingAfterNameExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterNameExcerpt
});
}
_this._equalsExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "HtmlAttribute_Equals" /* HtmlAttribute_Equals */,
content: parameters.equalsExcerpt
});
if (parameters.spacingAfterEqualsExcerpt) {
_this._spacingAfterEqualsExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterEqualsExcerpt
});
}
_this._valueExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "HtmlAttribute_Value" /* HtmlAttribute_Value */,
content: parameters.valueExcerpt
});
if (parameters.spacingAfterValueExcerpt) {
_this._spacingAfterValueExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterValueExcerpt
});
}
}
else {
_this._name = parameters.name;
_this._spacingAfterName = parameters.spacingAfterName;
_this._spacingAfterEquals = parameters.spacingAfterEquals;
_this._value = parameters.value;
_this._spacingAfterValue = parameters.spacingAfterValue;
}
return _this;
}
Object.defineProperty(DocHtmlAttribute.prototype, "attributeName", {
Object.defineProperty(DocHtmlAttribute.prototype, "name", {
/**

@@ -42,3 +81,6 @@ * The HTML attribute name.

get: function () {
return this._attributeNameParticle.content;
if (this._name === undefined) {
this._name = this._nameExcerpt.content.toString();
}
return this._name;
},

@@ -48,3 +90,3 @@ enumerable: true,

});
Object.defineProperty(DocHtmlAttribute.prototype, "spacingAfterAttributeName", {
Object.defineProperty(DocHtmlAttribute.prototype, "spacingAfterName", {
/**

@@ -55,3 +97,8 @@ * Explicit whitespace that a renderer should insert after the HTML attribute name.

get: function () {
return this._attributeNameParticle.spacingAfterContent;
if (this._spacingAfterName === undefined) {
if (this._spacingAfterNameExcerpt !== undefined) {
this._spacingAfterName = this._spacingAfterNameExcerpt.content.toString();
}
}
return this._spacingAfterName;
},

@@ -67,3 +114,8 @@ enumerable: true,

get: function () {
return this._equalsParticle.spacingAfterContent;
if (this._spacingAfterEquals === undefined) {
if (this._spacingAfterEqualsExcerpt !== undefined) {
this._spacingAfterEquals = this._spacingAfterEqualsExcerpt.content.toString();
}
}
return this._spacingAfterEquals;
},

@@ -73,3 +125,3 @@ enumerable: true,

});
Object.defineProperty(DocHtmlAttribute.prototype, "attributeValue", {
Object.defineProperty(DocHtmlAttribute.prototype, "value", {
/**

@@ -79,3 +131,6 @@ * The HTML attribute value.

get: function () {
return this._attributeValueParticle.content;
if (this._value === undefined) {
this._value = this._valueExcerpt.content.toString();
}
return this._value;
},

@@ -85,3 +140,3 @@ enumerable: true,

});
Object.defineProperty(DocHtmlAttribute.prototype, "spacingAfterAttributeValue", {
Object.defineProperty(DocHtmlAttribute.prototype, "spacingAfterValue", {
/**

@@ -92,3 +147,8 @@ * Explicit whitespace that a renderer should insert after the HTML attribute name.

get: function () {
return this._attributeValueParticle.spacingAfterContent;
if (this._spacingAfterValue === undefined) {
if (this._spacingAfterValueExcerpt !== undefined) {
this._spacingAfterValue = this._spacingAfterValueExcerpt.content.toString();
}
}
return this._spacingAfterValue;
},

@@ -99,30 +159,12 @@ enumerable: true,

/** @override */
DocHtmlAttribute.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._attributeNameParticle = new DocParticle_1.DocParticle({
particleId: 'attributeName',
excerpt: parameters.attributeNameExcerpt,
content: parameters.attributeName,
spacingAfterContent: parameters.spacingAfterAttributeName
});
this._equalsParticle = new DocParticle_1.DocParticle({
particleId: 'equals',
excerpt: parameters.equalsExcerpt,
content: '=',
spacingAfterContent: parameters.spacingAfterEquals
});
this._attributeValueParticle = new DocParticle_1.DocParticle({
particleId: 'attributeValue',
excerpt: parameters.attributeValueExcerpt,
content: parameters.attributeValue,
spacingAfterContent: parameters.spacingAfterAttributeValue
});
DocHtmlAttribute.prototype.onGetChildNodes = function () {
return [
this._nameExcerpt,
this._spacingAfterNameExcerpt,
this._equalsExcerpt,
this._spacingAfterEqualsExcerpt,
this._valueExcerpt,
this._spacingAfterValueExcerpt
];
};
/**
* {@inheritDoc}
* @override
*/
DocHtmlAttribute.prototype.getChildNodes = function () {
return [this._attributeNameParticle, this._equalsParticle, this._attributeValueParticle];
};
return DocHtmlAttribute;

@@ -129,0 +171,0 @@ }(DocNode_1.DocNode));

37

lib/nodes/DocHtmlEndTag.d.ts

@@ -1,3 +0,3 @@

import { DocNode, DocNodeKind, IDocNodeParameters } from './DocNode';
import { Excerpt } from '../parser/Excerpt';
import { DocNode, DocNodeKind, IDocNodeParameters, IDocNodeParsedParameters } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';
/**

@@ -7,8 +7,14 @@ * Constructor parameters for {@link DocHtmlEndTag}.

export interface IDocHtmlEndTagParameters extends IDocNodeParameters {
openingDelimiterExcerpt?: Excerpt;
elementNameExcerpt?: Excerpt;
elementName: string;
closingDelimiterExcerpt?: Excerpt;
name: string;
}
/**
* Constructor parameters for {@link DocHtmlEndTag}.
*/
export interface IDocHtmlEndTagParsedParameters extends IDocNodeParsedParameters {
openingDelimiterExcerpt: TokenSequence;
nameExcerpt: TokenSequence;
spacingAfterNameExcerpt?: TokenSequence;
closingDelimiterExcerpt: TokenSequence;
}
/**
* Represents an HTML end tag. Example: `</a>`

@@ -19,5 +25,7 @@ */

readonly kind: DocNodeKind;
private _openingDelimiterParticle;
private _elementNameParticle;
private _closingDelimiterParticle;
private readonly _openingDelimiterExcerpt;
private _name;
private readonly _nameExcerpt;
private readonly _spacingAfterNameExcerpt;
private readonly _closingDelimiterExcerpt;
/**

@@ -27,14 +35,9 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocHtmlEndTagParameters);
constructor(parameters: IDocHtmlEndTagParameters | IDocHtmlEndTagParsedParameters);
/**
* The HTML element name.
*/
readonly elementName: string;
readonly name: string;
/** @override */
updateParameters(parameters: IDocHtmlEndTagParameters): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

63

lib/nodes/DocHtmlEndTag.js

@@ -17,3 +17,3 @@ "use strict";

var DocNode_1 = require("./DocNode");
var DocParticle_1 = require("./DocParticle");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -32,5 +32,28 @@ * Represents an HTML end tag. Example: `</a>`

_this.kind = "HtmlEndTag" /* HtmlEndTag */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
_this._openingDelimiterExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "HtmlEndTag_OpeningDelimiter" /* HtmlEndTag_OpeningDelimiter */,
content: parameters.openingDelimiterExcerpt
});
_this._nameExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "HtmlEndTag_Name" /* HtmlEndTag_Name */,
content: parameters.nameExcerpt
});
if (parameters.spacingAfterNameExcerpt) {
_this._spacingAfterNameExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterNameExcerpt
});
}
_this._closingDelimiterExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "HtmlEndTag_ClosingDelimiter" /* HtmlEndTag_ClosingDelimiter */,
content: parameters.closingDelimiterExcerpt
});
}
else {
_this._name = parameters.name;
}
return _this;
}
Object.defineProperty(DocHtmlEndTag.prototype, "elementName", {
Object.defineProperty(DocHtmlEndTag.prototype, "name", {
/**

@@ -40,3 +63,6 @@ * The HTML element name.

get: function () {
return this._elementNameParticle.content;
if (this._name === undefined) {
this._name = this._nameExcerpt.content.toString();
}
return this._name;
},

@@ -47,29 +73,8 @@ enumerable: true,

/** @override */
DocHtmlEndTag.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._openingDelimiterParticle = new DocParticle_1.DocParticle({
particleId: 'openingDelimiter',
excerpt: parameters.openingDelimiterExcerpt,
content: '</'
});
this._elementNameParticle = new DocParticle_1.DocParticle({
particleId: 'elementName',
excerpt: parameters.elementNameExcerpt,
content: parameters.elementName
});
this._closingDelimiterParticle = new DocParticle_1.DocParticle({
particleId: 'closingDelimiter',
excerpt: parameters.closingDelimiterExcerpt,
content: '>'
});
};
/**
* {@inheritDoc}
* @override
*/
DocHtmlEndTag.prototype.getChildNodes = function () {
DocHtmlEndTag.prototype.onGetChildNodes = function () {
return [
this._openingDelimiterParticle,
this._elementNameParticle,
this._closingDelimiterParticle
this._openingDelimiterExcerpt,
this._nameExcerpt,
this._spacingAfterNameExcerpt,
this._closingDelimiterExcerpt
];

@@ -76,0 +81,0 @@ };

48

lib/nodes/DocHtmlStartTag.d.ts

@@ -1,4 +0,4 @@

import { DocNode, DocNodeKind, IDocNodeParameters } from './DocNode';
import { DocNode, DocNodeKind, IDocNodeParameters, IDocNodeParsedParameters } from './DocNode';
import { DocHtmlAttribute } from './DocHtmlAttribute';
import { Excerpt } from '../parser/Excerpt';
import { TokenSequence } from '../parser/TokenSequence';
/**

@@ -8,11 +8,19 @@ * Constructor parameters for {@link DocHtmlStartTag}.

export interface IDocHtmlStartTagParameters extends IDocNodeParameters {
openingDelimiterExcerpt?: Excerpt;
elementNameExcerpt?: Excerpt;
elementName: string;
spacingAfterElementName?: string;
name: string;
spacingAfterName?: string;
htmlAttributes: DocHtmlAttribute[];
selfClosingTag: boolean;
closingDelimiterExcerpt?: Excerpt;
}
/**
* Constructor parameters for {@link DocHtmlStartTag}.
*/
export interface IDocHtmlStartTagParsedParameters extends IDocNodeParsedParameters {
openingDelimiterExcerpt: TokenSequence;
nameExcerpt: TokenSequence;
spacingAfterNameExcerpt?: TokenSequence;
htmlAttributes: DocHtmlAttribute[];
selfClosingTag: boolean;
closingDelimiterExcerpt: TokenSequence;
}
/**
* Represents an HTML start tag, which may or may not be self-closing.

@@ -25,7 +33,10 @@ *

readonly kind: DocNodeKind;
private _openingDelimiterParticle;
private _elementNameParticle;
private _htmlAttributes;
private _selfClosingTag;
private _closingDelimiterParticle;
private readonly _openingDelimiterExcerpt;
private _name;
private readonly _nameExcerpt;
private _spacingAfterName;
private readonly _spacingAfterNameExcerpt;
private readonly _htmlAttributes;
private readonly _selfClosingTag;
private readonly _closingDelimiterExcerpt;
/**

@@ -35,7 +46,7 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocHtmlStartTagParameters);
constructor(parameters: IDocHtmlStartTagParameters | IDocHtmlStartTagParsedParameters);
/**
* The HTML element name.
*/
readonly elementName: string;
readonly name: string;
/**

@@ -53,10 +64,5 @@ * The HTML attributes belonging to this HTML element.

*/
readonly spacingAfterElementName: string | undefined;
readonly spacingAfterName: string | undefined;
/** @override */
updateParameters(parameters: IDocHtmlStartTagParameters): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

80

lib/nodes/DocHtmlStartTag.js

@@ -17,3 +17,3 @@ "use strict";

var DocNode_1 = require("./DocNode");
var DocParticle_1 = require("./DocParticle");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -31,8 +31,36 @@ * Represents an HTML start tag, which may or may not be self-closing.

function DocHtmlStartTag(parameters) {
var _a;
var _this = _super.call(this, parameters) || this;
/** {@inheritDoc} */
_this.kind = "HtmlStartTag" /* HtmlStartTag */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
_this._openingDelimiterExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "HtmlStartTag_OpeningDelimiter" /* HtmlStartTag_OpeningDelimiter */,
content: parameters.openingDelimiterExcerpt
});
_this._nameExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "HtmlStartTag_Name" /* HtmlStartTag_Name */,
content: parameters.nameExcerpt
});
if (parameters.spacingAfterNameExcerpt) {
_this._spacingAfterNameExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterNameExcerpt
});
}
_this._closingDelimiterExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "HtmlStartTag_ClosingDelimiter" /* HtmlStartTag_ClosingDelimiter */,
content: parameters.closingDelimiterExcerpt
});
}
else {
_this._name = parameters.name;
_this._spacingAfterName = parameters.spacingAfterName;
}
_this._htmlAttributes = [];
(_a = _this._htmlAttributes).push.apply(_a, parameters.htmlAttributes);
_this._selfClosingTag = parameters.selfClosingTag;
return _this;
}
Object.defineProperty(DocHtmlStartTag.prototype, "elementName", {
Object.defineProperty(DocHtmlStartTag.prototype, "name", {
/**

@@ -42,3 +70,6 @@ * The HTML element name.

get: function () {
return this._elementNameParticle.content;
if (this._name === undefined) {
this._name = this._nameExcerpt.content.toString();
}
return this._name;
},

@@ -68,3 +99,3 @@ enumerable: true,

});
Object.defineProperty(DocHtmlStartTag.prototype, "spacingAfterElementName", {
Object.defineProperty(DocHtmlStartTag.prototype, "spacingAfterName", {
/**

@@ -75,3 +106,8 @@ * Explicit whitespace that a renderer should insert after the HTML element name.

get: function () {
return this._elementNameParticle.spacingAfterContent;
if (this._spacingAfterName === undefined) {
if (this._spacingAfterNameExcerpt !== undefined) {
this._spacingAfterName = this._spacingAfterNameExcerpt.content.toString();
}
}
return this._spacingAfterName;
},

@@ -82,33 +118,9 @@ enumerable: true,

/** @override */
DocHtmlStartTag.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._openingDelimiterParticle = new DocParticle_1.DocParticle({
particleId: 'openingDelimiter',
excerpt: parameters.openingDelimiterExcerpt,
content: '<'
});
this._elementNameParticle = new DocParticle_1.DocParticle({
particleId: 'elementName',
excerpt: parameters.elementNameExcerpt,
content: parameters.elementName,
spacingAfterContent: parameters.spacingAfterElementName
});
this._htmlAttributes = parameters.htmlAttributes;
this._selfClosingTag = parameters.selfClosingTag;
this._closingDelimiterParticle = new DocParticle_1.DocParticle({
particleId: 'closingDelimiter',
excerpt: parameters.closingDelimiterExcerpt,
content: parameters.selfClosingTag ? '/>' : '>'
});
};
/**
* {@inheritDoc}
* @override
*/
DocHtmlStartTag.prototype.getChildNodes = function () {
DocHtmlStartTag.prototype.onGetChildNodes = function () {
return [
this._openingDelimiterParticle,
this._elementNameParticle
this._openingDelimiterExcerpt,
this._nameExcerpt,
this._spacingAfterNameExcerpt
].concat(this._htmlAttributes, [
this._closingDelimiterParticle
this._closingDelimiterExcerpt
]);

@@ -115,0 +127,0 @@ };

23

lib/nodes/DocInheritDocTag.d.ts
import { DocNodeKind, DocNode } from './DocNode';
import { DocInlineTag, IDocInlineTagParameters } from './DocInlineTag';
import { DocDeclarationReference } from './DocDeclarationReference';
import { DocInlineTagBase, IDocInlineTagBaseParsedParameters, IDocInlineTagBaseParameters } from './DocInlineTagBase';
/**
* Constructor parameters for {@link DocInheritDocTag}.
*/
export interface IDocInheritDocTagParameters extends IDocInlineTagParameters {
export interface IDocInheritDocTagParameters extends IDocInlineTagBaseParameters {
declarationReference?: DocDeclarationReference;
}
/**
* Constructor parameters for {@link DocInheritDocTag}.
*/
export interface IDocInheritDocTagParsedParameters extends IDocInlineTagBaseParsedParameters {
declarationReference?: DocDeclarationReference;
}
/**
* Represents an `{@inheritDoc}` tag.
*/
export declare class DocInheritDocTag extends DocInlineTag {
export declare class DocInheritDocTag extends DocInlineTagBase {
/** {@inheritDoc} */
readonly kind: DocNodeKind;
private _declarationReference;
private readonly _declarationReference;
/**

@@ -21,3 +27,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocInheritDocTagParameters);
constructor(parameters: IDocInheritDocTagParameters | IDocInheritDocTagParsedParameters);
/**

@@ -29,8 +35,3 @@ * The declaration that the documentation will be inherited from.

/** @override */
updateParameters(parameters: IDocInheritDocTagParameters): void;
/**
* {@inheritDoc}
* @override
*/
protected getChildNodesForContent(): ReadonlyArray<DocNode>;
protected getChildNodesForContent(): ReadonlyArray<DocNode | undefined>;
}

34

lib/nodes/DocInheritDocTag.js

@@ -16,4 +16,3 @@ "use strict";

Object.defineProperty(exports, "__esModule", { value: true });
var DocNode_1 = require("./DocNode");
var DocInlineTag_1 = require("./DocInlineTag");
var DocInlineTagBase_1 = require("./DocInlineTagBase");
/**

@@ -32,2 +31,6 @@ * Represents an `{@inheritDoc}` tag.

_this.kind = "InheritDocTag" /* InheritDocTag */;
if (_this.tagNameWithUpperCase !== '@INHERITDOC') {
throw new Error('DocInheritDocTag requires the tag name to be "{@inheritDoc}"');
}
_this._declarationReference = parameters.declarationReference;
return _this;

@@ -47,29 +50,10 @@ }

/** @override */
DocInheritDocTag.prototype.updateParameters = function (parameters) {
if (parameters.tagName.toUpperCase() !== '@INHERITDOC') {
throw new Error('DocInheritDocTag requires the tag name to be "{@inheritDoc}"');
}
_super.prototype.updateParameters.call(this, parameters);
this._declarationReference = parameters.declarationReference;
};
/**
* {@inheritDoc}
* @override
*/
DocInheritDocTag.prototype.getChildNodesForContent = function () {
if (this.tagContentParticle.excerpt) {
// If the parser associated the inline tag input with the tagContentExcerpt (e.g. because
// second stage parsing encountered an error), then fall back to the base class's representation
return _super.prototype.getChildNodesForContent.call(this);
}
else {
// Otherwise return the detailed structure
return DocNode_1.DocNode.trimUndefinedNodes([
this._declarationReference
]);
}
return [
this._declarationReference
];
};
return DocInheritDocTag;
}(DocInlineTag_1.DocInlineTag));
}(DocInlineTagBase_1.DocInlineTagBase));
exports.DocInheritDocTag = DocInheritDocTag;
//# sourceMappingURL=DocInheritDocTag.js.map

63

lib/nodes/DocInlineTag.d.ts

@@ -1,25 +0,31 @@

import { DocNodeKind, IDocNodeParameters, DocNode } from './DocNode';
import { DocParticle } from './DocParticle';
import { Excerpt } from '../parser/Excerpt';
import { DocNodeKind, DocNode } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';
import { IDocInlineTagBaseParameters, IDocInlineTagBaseParsedParameters, DocInlineTagBase } from './DocInlineTagBase';
/**
* Constructor parameters for {@link DocInlineTag}.
*/
export interface IDocInlineTagParameters extends IDocNodeParameters {
openingDelimiterExcerpt?: Excerpt;
tagNameExcerpt?: Excerpt;
tagName: string;
tagContentExcerpt?: Excerpt;
export interface IDocInlineTagParameters extends IDocInlineTagBaseParameters {
tagContent: string;
closingDelimiterExcerpt?: Excerpt;
}
/**
* Represents a TSDoc inline tag such as `{@inheritDoc}` or `{@link}`.
* Constructor parameters for {@link DocInlineTag}.
*/
export declare class DocInlineTag extends DocNode {
export interface IDocInlineTagParsedParameters extends IDocInlineTagBaseParsedParameters {
tagContentExcerpt?: TokenSequence;
}
/**
* Represents a generic TSDoc inline tag, including custom tags.
*
* @remarks
* NOTE: Certain tags such as `{@link}` and `{@inheritDoc}` have specialized structures and parser rules,
* and thus are represented using {@link DocLinkTag} or {@link DocInheritDocTag} instead. However, if the
* specialized parser rule encounters a syntax error, but the outer framing is correct, then the parser constructs
* a generic `DocInlineTag` instead of `DocErrorText`. This means, for example, that it is possible sometimes for
* `DocInlineTag.tagName` to be `"@link"`.
*/
export declare class DocInlineTag extends DocInlineTagBase {
/** {@inheritDoc} */
readonly kind: DocNodeKind;
private _openingDelimiterParticle;
private _tagNameParticle;
private _tagContentParticle;
private _closingDelimiterParticle;
private _tagContent;
private readonly _tagContentExcerpt;
/**

@@ -29,29 +35,12 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocInlineTagParameters);
constructor(parameters: IDocInlineTagParameters | IDocInlineTagParsedParameters);
/**
* The TSDoc tag name.
* For example, if the inline tag is `{@link Guid.toString | the toString() method}`
* then the tag name would be `@link`.
*/
readonly tagName: string;
/**
* The tag content.
* For example, if the inline tag is `{@link Guid.toString | the toString() method}`
* then the tag content would be `Guid.toString | the toString() method`.
* @remarks
* For example, if the tag is `{@myTag x=12.34 y=56.78 }` then the tag content
* would be `x=12.34 y=56.78 `, including the trailing space but not the leading space.
*/
readonly tagContent: string;
/** @override */
updateParameters(parameters: IDocInlineTagParameters): void;
/**
* {@inheritDoc}
* @override @sealed
*/
getChildNodes(): ReadonlyArray<DocNode>;
/**
* Allows child classes to replace the tagContentParticle with a more detailed
* set of nodes.
* @virtual
*/
protected getChildNodesForContent(): ReadonlyArray<DocNode>;
protected readonly tagContentParticle: DocParticle;
protected getChildNodesForContent(): ReadonlyArray<DocNode | undefined>;
}

103

lib/nodes/DocInlineTag.js

@@ -17,6 +17,13 @@ "use strict";

var DocNode_1 = require("./DocNode");
var StringChecks_1 = require("../parser/StringChecks");
var DocParticle_1 = require("./DocParticle");
var DocExcerpt_1 = require("./DocExcerpt");
var DocInlineTagBase_1 = require("./DocInlineTagBase");
/**
* Represents a TSDoc inline tag such as `{@inheritDoc}` or `{@link}`.
* Represents a generic TSDoc inline tag, including custom tags.
*
* @remarks
* NOTE: Certain tags such as `{@link}` and `{@inheritDoc}` have specialized structures and parser rules,
* and thus are represented using {@link DocLinkTag} or {@link DocInheritDocTag} instead. However, if the
* specialized parser rule encounters a syntax error, but the outer framing is correct, then the parser constructs
* a generic `DocInlineTag` instead of `DocErrorText`. This means, for example, that it is possible sometimes for
* `DocInlineTag.tagName` to be `"@link"`.
*/

@@ -33,24 +40,32 @@ var DocInlineTag = /** @class */ (function (_super) {

_this.kind = "InlineTag" /* InlineTag */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
if (parameters.tagContentExcerpt) {
_this._tagContentExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "InlineTag_TagContent" /* InlineTag_TagContent */,
content: parameters.tagContentExcerpt
});
}
}
else {
_this._tagContent = parameters.tagContent;
}
return _this;
}
Object.defineProperty(DocInlineTag.prototype, "tagName", {
/**
* The TSDoc tag name.
* For example, if the inline tag is `{@link Guid.toString | the toString() method}`
* then the tag name would be `@link`.
*/
get: function () {
return this._tagNameParticle.content;
},
enumerable: true,
configurable: true
});
Object.defineProperty(DocInlineTag.prototype, "tagContent", {
/**
* The tag content.
* For example, if the inline tag is `{@link Guid.toString | the toString() method}`
* then the tag content would be `Guid.toString | the toString() method`.
* @remarks
* For example, if the tag is `{@myTag x=12.34 y=56.78 }` then the tag content
* would be `x=12.34 y=56.78 `, including the trailing space but not the leading space.
*/
get: function () {
return this._tagContentParticle.content;
if (this._tagContent === undefined) {
if (this._tagContentExcerpt) {
this._tagContent = this._tagContentExcerpt.content.toString();
}
else {
return '';
}
}
return this._tagContent;
},

@@ -61,58 +76,10 @@ enumerable: true,

/** @override */
DocInlineTag.prototype.updateParameters = function (parameters) {
StringChecks_1.StringChecks.validateTSDocTagName(parameters.tagName);
_super.prototype.updateParameters.call(this, parameters);
this._openingDelimiterParticle = new DocParticle_1.DocParticle({
particleId: 'openingDelimiter',
excerpt: parameters.openingDelimiterExcerpt,
content: '{'
});
this._tagNameParticle = new DocParticle_1.DocParticle({
particleId: 'tagName',
excerpt: parameters.tagNameExcerpt,
content: parameters.tagName
});
this._tagContentParticle = new DocParticle_1.DocParticle({
particleId: 'tagContent',
excerpt: parameters.tagContentExcerpt,
content: parameters.tagContent
});
this._closingDelimiterParticle = new DocParticle_1.DocParticle({
particleId: 'closingDelimiter',
excerpt: parameters.closingDelimiterExcerpt,
content: '}'
});
};
/**
* {@inheritDoc}
* @override @sealed
*/
DocInlineTag.prototype.getChildNodes = function () {
return [
this._openingDelimiterParticle,
this._tagNameParticle
].concat(this.getChildNodesForContent(), [
this._closingDelimiterParticle
]);
};
/**
* Allows child classes to replace the tagContentParticle with a more detailed
* set of nodes.
* @virtual
*/
DocInlineTag.prototype.getChildNodesForContent = function () {
return [
this._tagContentParticle
this._tagContentExcerpt
];
};
Object.defineProperty(DocInlineTag.prototype, "tagContentParticle", {
get: function () {
return this._tagContentParticle;
},
enumerable: true,
configurable: true
});
return DocInlineTag;
}(DocNode_1.DocNode));
}(DocInlineTagBase_1.DocInlineTagBase));
exports.DocInlineTag = DocInlineTag;
//# sourceMappingURL=DocInlineTag.js.map

41

lib/nodes/DocLinkTag.d.ts
import { DocNodeKind, DocNode } from './DocNode';
import { DocInlineTag, IDocInlineTagParameters } from './DocInlineTag';
import { DocDeclarationReference } from './DocDeclarationReference';
import { Excerpt } from '../parser/Excerpt';
import { DocInlineTagBase, IDocInlineTagBaseParsedParameters, IDocInlineTagBaseParameters } from './DocInlineTagBase';
import { TokenSequence } from '../parser/TokenSequence';
/**
* Constructor parameters for {@link DocLinkTag}.
*/
export interface IDocLinkTagParameters extends IDocInlineTagParameters {
export interface IDocLinkTagParameters extends IDocInlineTagBaseParameters {
codeDestination?: DocDeclarationReference;
urlDestinationExcerpt?: Excerpt;
urlDestination?: string;
pipeExcerpt?: Excerpt;
linkTextExcerpt?: Excerpt;
linkText?: string;
}
/**
* Constructor parameters for {@link DocLinkTag}.
*/
export interface IDocLinkTagParsedParameters extends IDocInlineTagBaseParsedParameters {
codeDestination?: DocDeclarationReference;
urlDestinationExcerpt?: TokenSequence;
spacingAfterDestinationExcerpt?: TokenSequence;
pipeExcerpt?: TokenSequence;
linkTextExcerpt?: TokenSequence;
}
/**
* Represents an `{@link}` tag.
*/
export declare class DocLinkTag extends DocInlineTag {
export declare class DocLinkTag extends DocInlineTagBase {
/** {@inheritDoc} */
readonly kind: DocNodeKind;
private _codeDestination;
private _urlDestinationParticle;
private _pipeParticle;
private _linkTextParticle;
private readonly _codeDestination;
private _urlDestination;
private readonly _urlDestinationExcerpt;
private readonly _spacingAfterDestinationExcerpt;
private readonly _pipeExcerpt;
private _linkText;
private readonly _linkTextExcerpt;
/**

@@ -30,3 +40,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocLinkTagParameters);
constructor(parameters: IDocLinkTagParameters | IDocLinkTagParsedParameters);
/**

@@ -53,8 +63,3 @@ * If the link tag refers to a declaration, this returns the declaration reference object;

/** @override */
updateParameters(parameters: IDocLinkTagParameters): void;
/**
* {@inheritDoc}
* @override
*/
protected getChildNodesForContent(): ReadonlyArray<DocNode>;
protected getChildNodesForContent(): ReadonlyArray<DocNode | undefined>;
}

133

lib/nodes/DocLinkTag.js

@@ -17,4 +17,4 @@ "use strict";

var DocNode_1 = require("./DocNode");
var DocInlineTag_1 = require("./DocInlineTag");
var DocParticle_1 = require("./DocParticle");
var DocInlineTagBase_1 = require("./DocInlineTagBase");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -33,2 +33,42 @@ * Represents an `{@link}` tag.

_this.kind = "LinkTag" /* LinkTag */;
if (_this.tagNameWithUpperCase !== '@LINK') {
throw new Error('DocLinkTag requires the tag name to be "{@link}"');
}
_this._codeDestination = parameters.codeDestination;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
if (parameters.codeDestination !== undefined && parameters.urlDestinationExcerpt !== undefined) {
throw new Error('Either the codeDestination or the urlDestination may be specified, but not both');
}
if (parameters.urlDestinationExcerpt) {
_this._urlDestinationExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "LinkTag_UrlDestination" /* LinkTag_UrlDestination */,
content: parameters.urlDestinationExcerpt
});
}
if (parameters.spacingAfterDestinationExcerpt) {
_this._spacingAfterDestinationExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterDestinationExcerpt
});
}
if (parameters.pipeExcerpt) {
_this._pipeExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "LinkTag_Pipe" /* LinkTag_Pipe */,
content: parameters.pipeExcerpt
});
}
if (parameters.linkTextExcerpt) {
_this._linkTextExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "LinkTag_LinkText" /* LinkTag_LinkText */,
content: parameters.linkTextExcerpt
});
}
}
else {
if (parameters.codeDestination !== undefined && parameters.urlDestination !== undefined) {
throw new Error('Either the codeDestination or the urlDestination may be specified, but not both');
}
_this._urlDestination = parameters.urlDestination;
_this._linkText = parameters.linkText;
}
return _this;

@@ -57,3 +97,8 @@ }

get: function () {
return this._urlDestinationParticle ? this._urlDestinationParticle.content : undefined;
if (this._urlDestination === undefined) {
if (this._urlDestinationExcerpt !== undefined) {
this._urlDestination = this._urlDestinationExcerpt.content.toString();
}
}
return this._urlDestination;
},

@@ -70,8 +115,8 @@ enumerable: true,

get: function () {
if (this._linkTextParticle) {
return this._linkTextParticle.content;
if (this._linkText === undefined) {
if (this._linkTextExcerpt !== undefined) {
this._linkText = this._linkTextExcerpt.content.toString();
}
}
else {
return undefined;
}
return this._linkText;
},

@@ -82,70 +127,14 @@ enumerable: true,

/** @override */
DocLinkTag.prototype.updateParameters = function (parameters) {
if (parameters.tagName.toUpperCase() !== '@LINK') {
throw new Error('DocLinkTag requires the tag name to be "{@link}"');
}
if (parameters.codeDestination !== undefined) {
if (parameters.urlDestination !== undefined) {
throw new Error('Either the codeLink or the documentLink may be specified, but not both');
}
}
if (parameters.tagContentExcerpt !== undefined) {
if (parameters.codeDestination || parameters.urlDestinationExcerpt || parameters.linkTextExcerpt) {
// This would violate the TokenCoverageChecker properties
throw new Error('The input cannot be associated with tagContentExcerpt and also the detail excerpts');
}
}
_super.prototype.updateParameters.call(this, parameters);
this._codeDestination = undefined;
this._urlDestinationParticle = undefined;
this._pipeParticle = undefined;
this._linkTextParticle = undefined;
if (parameters.codeDestination) {
this._codeDestination = parameters.codeDestination;
}
else if (parameters.urlDestination !== undefined) {
this._urlDestinationParticle = new DocParticle_1.DocParticle({
particleId: 'urlDestination',
excerpt: parameters.urlDestinationExcerpt,
content: parameters.urlDestination
});
}
if (parameters.linkTextExcerpt || parameters.linkText || parameters.pipeExcerpt) {
this._pipeParticle = new DocParticle_1.DocParticle({
particleId: 'pipe',
excerpt: parameters.pipeExcerpt,
content: '|'
});
}
if (parameters.linkText !== undefined) {
this._linkTextParticle = new DocParticle_1.DocParticle({
particleId: 'linkText',
excerpt: parameters.linkTextExcerpt,
content: parameters.linkText
});
}
};
/**
* {@inheritDoc}
* @override
*/
DocLinkTag.prototype.getChildNodesForContent = function () {
if (this.tagContentParticle.excerpt) {
// If the parser associated the inline tag input with the tagContentExcerpt (e.g. because
// second stage parsing encountered an error), then fall back to the base class's representation
return _super.prototype.getChildNodesForContent.call(this);
}
else {
// Otherwise return the detailed structure
return DocNode_1.DocNode.trimUndefinedNodes([
this._urlDestinationParticle,
this._codeDestination,
this._pipeParticle,
this._linkTextParticle
]);
}
return [
this._codeDestination,
this._urlDestinationExcerpt,
this._spacingAfterDestinationExcerpt,
this._pipeExcerpt,
this._linkTextExcerpt
];
};
return DocLinkTag;
}(DocInlineTag_1.DocInlineTag));
}(DocInlineTagBase_1.DocInlineTagBase));
exports.DocLinkTag = DocLinkTag;
//# sourceMappingURL=DocLinkTag.js.map

31

lib/nodes/DocMemberIdentifier.d.ts

@@ -1,3 +0,3 @@

import { DocNodeKind, DocNode, IDocNodeParameters } from './DocNode';
import { Excerpt } from '../parser/Excerpt';
import { DocNodeKind, DocNode, IDocNodeParameters, IDocNodeParsedParameters } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';
/**

@@ -7,8 +7,13 @@ * Constructor parameters for {@link DocMemberIdentifier}.

export interface IDocMemberIdentifierParameters extends IDocNodeParameters {
leftQuoteExcerpt?: Excerpt | undefined;
identifierExcerpt?: Excerpt | undefined;
identifier: string;
rightQuoteExcerpt?: Excerpt | undefined;
}
/**
* Constructor parameters for {@link DocMemberIdentifier}.
*/
export interface IDocMemberIdentifierParsedParameters extends IDocNodeParsedParameters {
leftQuoteExcerpt?: TokenSequence;
identifierExcerpt: TokenSequence;
rightQuoteExcerpt?: TokenSequence;
}
/**
* A member identifier is part of a {@link DocMemberReference}.

@@ -19,5 +24,6 @@ */

readonly kind: DocNodeKind;
private _leftQuoteParticle;
private _identifierParticle;
private _rightQuoteParticle;
private readonly _leftQuoteExcerpt;
private _identifier;
private readonly _identifierExcerpt;
private readonly _rightQuoteExcerpt;
/**

@@ -33,3 +39,3 @@ * Returns true if the specified string is a valid TypeScript

*/
constructor(parameters: IDocMemberIdentifierParameters);
constructor(parameters: IDocMemberIdentifierParameters | IDocMemberIdentifierParsedParameters);
/**

@@ -50,8 +56,3 @@ * The identifier string without any quote encoding.

/** @override */
updateParameters(parameters: IDocMemberIdentifierParameters): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

76

lib/nodes/DocMemberIdentifier.js

@@ -17,4 +17,4 @@ "use strict";

var DocNode_1 = require("./DocNode");
var DocParticle_1 = require("./DocParticle");
var StringChecks_1 = require("../parser/StringChecks");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -33,2 +33,23 @@ * A member identifier is part of a {@link DocMemberReference}.

_this.kind = "MemberIdentifier" /* MemberIdentifier */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
if (parameters.leftQuoteExcerpt) {
_this._leftQuoteExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "MemberIdentifier_LeftQuote" /* MemberIdentifier_LeftQuote */,
content: parameters.leftQuoteExcerpt
});
}
_this._identifierExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "MemberIdentifier_Identifier" /* MemberIdentifier_Identifier */,
content: parameters.identifierExcerpt
});
if (parameters.rightQuoteExcerpt) {
_this._rightQuoteExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "MemberIdentifier_RightQuote" /* MemberIdentifier_RightQuote */,
content: parameters.rightQuoteExcerpt
});
}
}
else {
_this._identifier = parameters.identifier;
}
return _this;

@@ -53,3 +74,6 @@ }

get: function () {
return this._identifierParticle.content;
if (this._identifier === undefined) {
this._identifier = this._identifierExcerpt.content.toString();
}
return this._identifier;
},

@@ -66,3 +90,8 @@ enumerable: true,

get: function () {
return !!this._leftQuoteParticle;
if (this._identifierExcerpt) {
return !!this._leftQuoteExcerpt;
}
else {
return !DocMemberIdentifier.isValidIdentifier(this.identifier);
}
},

@@ -73,38 +102,9 @@ enumerable: true,

/** @override */
DocMemberIdentifier.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._leftQuoteParticle = undefined;
this._identifierParticle = undefined;
this._rightQuoteParticle = undefined;
if (parameters.leftQuoteExcerpt || !DocMemberIdentifier.isValidIdentifier(parameters.identifier)) {
this._leftQuoteParticle = new DocParticle_1.DocParticle({
particleId: 'leftQuote',
excerpt: parameters.leftQuoteExcerpt,
content: '"'
});
}
this._identifierParticle = new DocParticle_1.DocParticle({
particleId: 'identifier',
excerpt: parameters.identifierExcerpt,
content: parameters.identifier
});
if (this._leftQuoteParticle) {
this._rightQuoteParticle = new DocParticle_1.DocParticle({
particleId: 'rightQuote',
excerpt: parameters.rightQuoteExcerpt,
content: '"'
});
}
DocMemberIdentifier.prototype.onGetChildNodes = function () {
return [
this._leftQuoteExcerpt,
this._identifierExcerpt,
this._rightQuoteExcerpt
];
};
/**
* {@inheritDoc}
* @override
*/
DocMemberIdentifier.prototype.getChildNodes = function () {
return DocNode_1.DocNode.trimUndefinedNodes([
this._leftQuoteParticle,
this._identifierParticle,
this._rightQuoteParticle
]);
};
return DocMemberIdentifier;

@@ -111,0 +111,0 @@ }(DocNode_1.DocNode));

56

lib/nodes/DocMemberReference.d.ts

@@ -1,6 +0,6 @@

import { DocNode, DocNodeKind, IDocNodeParameters } from './DocNode';
import { Excerpt } from '../parser/Excerpt';
import { DocNode, DocNodeKind, IDocNodeParameters, IDocNodeParsedParameters } from './DocNode';
import { DocMemberIdentifier } from './DocMemberIdentifier';
import { DocMemberSymbol } from './DocMemberSymbol';
import { DocMemberSelector } from './DocMemberSelector';
import { TokenSequence } from '../parser/TokenSequence';
/**

@@ -11,11 +11,25 @@ * Constructor parameters for {@link DocMemberReference}.

hasDot: boolean;
dotExcerpt?: Excerpt;
leftParenthesisExcerpt?: Excerpt;
memberIdentifier?: DocMemberIdentifier;
memberSymbol?: DocMemberSymbol;
colonExcerpt?: Excerpt;
selector?: DocMemberSelector;
rightParenthesisExcerpt?: Excerpt;
}
/**
* Constructor parameters for {@link DocMemberReference}.
*/
export interface IDocMemberReferenceParsedParameters extends IDocNodeParsedParameters {
dotExcerpt?: TokenSequence;
spacingAfterDotExcerpt?: TokenSequence;
leftParenthesisExcerpt?: TokenSequence;
spacingAfterLeftParenthesisExcerpt?: TokenSequence;
memberIdentifier?: DocMemberIdentifier;
memberSymbol?: DocMemberSymbol;
spacingAfterMemberExcerpt?: TokenSequence;
colonExcerpt?: TokenSequence;
spacingAfterColonExcerpt?: TokenSequence;
selector?: DocMemberSelector;
spacingAfterSelectorExcerpt?: TokenSequence;
rightParenthesisExcerpt?: TokenSequence;
spacingAfterRightParenthesisExcerpt?: TokenSequence;
}
/**
* A {@link DocDeclarationReference | declaration reference} includes a chain of

@@ -32,9 +46,16 @@ * member references represented using `DocMemberReference` nodes.

readonly kind: DocNodeKind;
private _dotParticle;
private _leftParenthesisParticle;
private _memberIdentifier;
private _memberSymbol;
private _colonParticle;
private _selector;
private _rightParenthesisParticle;
private readonly _hasDot;
private readonly _dotExcerpt;
private readonly _spacingAfterDotExcerpt;
private readonly _leftParenthesisExcerpt;
private readonly _spacingAfterLeftParenthesisExcerpt;
private readonly _memberIdentifier;
private readonly _memberSymbol;
private readonly _spacingAfterMemberExcerpt;
private readonly _colonExcerpt;
private readonly _spacingAfterColonExcerpt;
private readonly _selector;
private readonly _spacingAfterSelectorExcerpt;
private readonly _rightParenthesisExcerpt;
private readonly _spacingAfterRightParenthesisExcerpt;
/**

@@ -44,3 +65,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocMemberReferenceParameters);
constructor(parameters: IDocMemberReferenceParameters | IDocMemberReferenceParsedParameters);
/**

@@ -70,8 +91,3 @@ * True if this member reference is preceded by a dot (".") token.

/** @override */
updateParameters(parameters: IDocMemberReferenceParameters): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

139

lib/nodes/DocMemberReference.js

@@ -17,3 +17,3 @@ "use strict";

var DocNode_1 = require("./DocNode");
var DocParticle_1 = require("./DocParticle");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -38,2 +38,71 @@ * A {@link DocDeclarationReference | declaration reference} includes a chain of

_this.kind = "MemberReference" /* MemberReference */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
_this._hasDot = !!parameters.dotExcerpt;
if (parameters.dotExcerpt) {
_this._dotExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "MemberReference_Dot" /* MemberReference_Dot */,
content: parameters.dotExcerpt
});
}
if (parameters.spacingAfterDotExcerpt) {
_this._spacingAfterDotExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterDotExcerpt
});
}
if (parameters.leftParenthesisExcerpt) {
_this._leftParenthesisExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "MemberReference_LeftParenthesis" /* MemberReference_LeftParenthesis */,
content: parameters.leftParenthesisExcerpt
});
}
if (parameters.spacingAfterLeftParenthesisExcerpt) {
_this._spacingAfterLeftParenthesisExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterLeftParenthesisExcerpt
});
}
if (parameters.spacingAfterMemberExcerpt) {
_this._spacingAfterMemberExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterMemberExcerpt
});
}
if (parameters.colonExcerpt) {
_this._colonExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "MemberReference_Colon" /* MemberReference_Colon */,
content: parameters.colonExcerpt
});
}
if (parameters.spacingAfterColonExcerpt) {
_this._spacingAfterColonExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterColonExcerpt
});
}
if (parameters.spacingAfterSelectorExcerpt) {
_this._spacingAfterSelectorExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterSelectorExcerpt
});
}
if (parameters.rightParenthesisExcerpt) {
_this._rightParenthesisExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "MemberReference_RightParenthesis" /* MemberReference_RightParenthesis */,
content: parameters.rightParenthesisExcerpt
});
}
if (parameters.spacingAfterRightParenthesisExcerpt) {
_this._spacingAfterRightParenthesisExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterRightParenthesisExcerpt
});
}
}
else {
_this._hasDot = parameters.hasDot;
}
_this._memberIdentifier = parameters.memberIdentifier;
_this._memberSymbol = parameters.memberSymbol;
_this._selector = parameters.selector;
return _this;

@@ -47,3 +116,3 @@ }

get: function () {
return !!this._dotParticle;
return this._hasDot;
},

@@ -90,58 +159,18 @@ enumerable: true,

/** @override */
DocMemberReference.prototype.updateParameters = function (parameters) {
if (parameters.memberIdentifier && parameters.memberSymbol) {
throw new Error('"memberIdentifier" or "memberSymbol" may be specified, but not both');
}
_super.prototype.updateParameters.call(this, parameters);
this._dotParticle = undefined;
this._leftParenthesisParticle = undefined;
this._colonParticle = undefined;
this._selector = undefined;
this._rightParenthesisParticle = undefined;
if (parameters.hasDot || parameters.dotExcerpt) {
this._dotParticle = new DocParticle_1.DocParticle({
particleId: 'dot',
excerpt: parameters.dotExcerpt,
content: '.'
});
}
if (parameters.leftParenthesisExcerpt || parameters.selector) {
this._leftParenthesisParticle = new DocParticle_1.DocParticle({
particleId: 'leftParenthesis',
excerpt: parameters.leftParenthesisExcerpt,
content: '('
});
}
this._memberIdentifier = parameters.memberIdentifier;
this._memberSymbol = parameters.memberSymbol;
if (parameters.colonExcerpt || parameters.selector) {
this._colonParticle = new DocParticle_1.DocParticle({
particleId: 'colon',
excerpt: parameters.colonExcerpt,
content: ':'
});
}
this._selector = parameters.selector;
if (this._leftParenthesisParticle) {
this._rightParenthesisParticle = new DocParticle_1.DocParticle({
particleId: 'rightParenthesis',
excerpt: parameters.rightParenthesisExcerpt,
content: ')'
});
}
};
/**
* {@inheritDoc}
* @override
*/
DocMemberReference.prototype.getChildNodes = function () {
return DocNode_1.DocNode.trimUndefinedNodes([
this._dotParticle,
this._leftParenthesisParticle,
DocMemberReference.prototype.onGetChildNodes = function () {
return [
this._dotExcerpt,
this._spacingAfterDotExcerpt,
this._leftParenthesisExcerpt,
this._spacingAfterLeftParenthesisExcerpt,
this._memberIdentifier,
this._memberSymbol,
this._colonParticle,
this._spacingAfterMemberExcerpt,
this._colonExcerpt,
this._spacingAfterColonExcerpt,
this._selector,
this._rightParenthesisParticle
]);
this._spacingAfterSelectorExcerpt,
this._rightParenthesisExcerpt,
this._spacingAfterRightParenthesisExcerpt
];
};

@@ -148,0 +177,0 @@ return DocMemberReference;

35

lib/nodes/DocMemberSelector.d.ts

@@ -1,10 +0,4 @@

import { DocNodeKind } from './DocNode';
import { DocNodeLeaf, IDocNodeLeafParameters } from './DocNodeLeaf';
import { DocNodeKind, DocNode, IDocNodeParsedParameters, IDocNodeParameters } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';
/**
* Constructor parameters for {@link DocMemberSelector}.
*/
export interface IDocMemberSelectorParameters extends IDocNodeLeafParameters {
selector: string;
}
/**
* Kinds of TSDoc selectors.

@@ -41,4 +35,16 @@ */

/**
* Constructor parameters for {@link DocMemberSelector}.
*/
export declare class DocMemberSelector extends DocNodeLeaf {
export interface IDocMemberSelectorParameters extends IDocNodeParameters {
selector: string;
}
/**
* Constructor parameters for {@link DocMemberSelector}.
*/
export interface IDocMemberSelectorParsedParameters extends IDocNodeParsedParameters {
selectorExcerpt: TokenSequence;
}
/**
*/
export declare class DocMemberSelector extends DocNode {
private static readonly _likeIndexSelectorRegExp;

@@ -51,5 +57,6 @@ private static readonly _indexSelectorRegExp;

readonly kind: DocNodeKind;
private _selector;
private _selectorKind;
private _errorMessage;
private readonly _selector;
private _selectorExcerpt;
private readonly _selectorKind;
private readonly _errorMessage;
/**

@@ -59,3 +66,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocMemberSelectorParameters);
constructor(parameters: IDocMemberSelectorParameters | IDocMemberSelectorParsedParameters);
/**

@@ -80,3 +87,3 @@ * The text representation of the selector.

/** @override */
updateParameters(parameters: IDocMemberSelectorParameters): void;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

100

lib/nodes/DocMemberSelector.js

@@ -16,4 +16,5 @@ "use strict";

Object.defineProperty(exports, "__esModule", { value: true });
var DocNodeLeaf_1 = require("./DocNodeLeaf");
var DocNode_1 = require("./DocNode");
var StringChecks_1 = require("../parser/StringChecks");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -31,2 +32,51 @@ */

_this.kind = "MemberSelector" /* MemberSelector */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
_this._selectorExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "MemberSelector" /* MemberSelector */,
content: parameters.selectorExcerpt
});
_this._selector = parameters.selectorExcerpt.toString();
}
else {
_this._selector = parameters.selector;
}
_this._selectorKind = "error" /* Error */;
_this._errorMessage = undefined;
// The logic below will always either (1) assign selectorKind or (2) else assign an errorMessage
if (_this._selector.length === 0) {
_this._errorMessage = 'The selector cannot be an empty string';
}
else if (DocMemberSelector._likeIndexSelectorRegExp.test(_this._selector)) {
// It looks like an index selector
if (DocMemberSelector._indexSelectorRegExp.test(_this._selector)) {
_this._selectorKind = "index" /* Index */;
}
else {
_this._errorMessage = 'If the selector begins with a number, it must be a positive integer value';
}
}
else if (DocMemberSelector._likeLabelSelectorRegExp.test(_this._selector)) {
// It looks like a label selector
if (DocMemberSelector._labelSelectorRegExp.test(_this._selector)) {
_this._selectorKind = "label" /* Label */;
}
else {
_this._errorMessage = 'A label selector must be comprised of upper case letters, numbers,'
+ ' and underscores and must not start with a number';
}
}
else {
if (StringChecks_1.StringChecks.isSystemSelector(_this._selector)) {
_this._selectorKind = "system" /* System */;
}
else if (DocMemberSelector._likeSystemSelectorRegExp.test(_this._selector)) {
// It looks like a system selector, but is not
_this._errorMessage = "The selector " + JSON.stringify(_this._selector)
+ " is not a recognized TSDoc system selector name";
}
else {
// It doesn't look like anything we recognize
_this._errorMessage = 'Invalid syntax for selector';
}
}
return _this;

@@ -71,44 +121,6 @@ }

/** @override */
DocMemberSelector.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._selector = parameters.selector;
this._selectorKind = "error" /* Error */;
this._errorMessage = undefined;
// The logic below will always either (1) assign selectorKind or (2) else assign an errorMessage
if (this._selector.length === 0) {
this._errorMessage = 'The selector cannot be an empty string';
}
else if (DocMemberSelector._likeIndexSelectorRegExp.test(this._selector)) {
// It looks like an index selector
if (DocMemberSelector._indexSelectorRegExp.test(this._selector)) {
this._selectorKind = "index" /* Index */;
}
else {
this._errorMessage = 'If the selector begins with a number, it must be a positive integer value';
}
}
else if (DocMemberSelector._likeLabelSelectorRegExp.test(this._selector)) {
// It looks like a label selector
if (DocMemberSelector._labelSelectorRegExp.test(this._selector)) {
this._selectorKind = "label" /* Label */;
}
else {
this._errorMessage = 'A label selector must be comprised of upper case letters, numbers,'
+ ' and underscores and must not start with a number';
}
}
else {
if (StringChecks_1.StringChecks.isSystemSelector(this._selector)) {
this._selectorKind = "system" /* System */;
}
else if (DocMemberSelector._likeSystemSelectorRegExp.test(this._selector)) {
// It looks like a system selector, but is not
this._errorMessage = "The selector " + JSON.stringify(this._selector)
+ " is not a recognized TSDoc system selector name";
}
else {
// It doesn't look like anything we recognize
this._errorMessage = 'Invalid syntax for selector';
}
}
DocMemberSelector.prototype.onGetChildNodes = function () {
return [
this._selectorExcerpt
];
};

@@ -121,4 +133,4 @@ DocMemberSelector._likeIndexSelectorRegExp = /^[0-9]/;

return DocMemberSelector;
}(DocNodeLeaf_1.DocNodeLeaf));
}(DocNode_1.DocNode));
exports.DocMemberSelector = DocMemberSelector;
//# sourceMappingURL=DocMemberSelector.js.map

33

lib/nodes/DocMemberSymbol.d.ts

@@ -1,4 +0,4 @@

import { DocNodeKind, DocNode, IDocNodeParameters } from './DocNode';
import { DocNodeKind, DocNode, IDocNodeParameters, IDocNodeParsedParameters } from './DocNode';
import { DocDeclarationReference } from './DocDeclarationReference';
import { Excerpt } from '../parser/Excerpt';
import { TokenSequence } from '../parser/TokenSequence';
/**

@@ -8,7 +8,14 @@ * Constructor parameters for {@link DocMemberSymbol}.

export interface IDocMemberSymbolParameters extends IDocNodeParameters {
leftBracketExcerpt?: Excerpt;
symbolReference: DocDeclarationReference | undefined;
rightBracketExcerpt?: Excerpt;
symbolReference: DocDeclarationReference;
}
/**
* Constructor parameters for {@link DocMemberSymbol}.
*/
export interface IDocMemberSymbolParsedParameters extends IDocNodeParsedParameters {
leftBracketExcerpt: TokenSequence;
spacingAfterLeftBracketExcerpt?: TokenSequence;
symbolReference: DocDeclarationReference;
rightBracketExcerpt: TokenSequence;
}
/**
* Represents a reference to an ECMAScript 6 symbol that is used

@@ -26,5 +33,6 @@ * to identify a member declaration.

readonly kind: DocNodeKind;
private _leftBracketParticle;
private _symbolReference;
private _rightBracketParticle;
private readonly _leftBracketExcerpt;
private readonly _spacingAfterLeftBracketExcerpt;
private readonly _symbolReference;
private readonly _rightBracketExcerpt;
/**

@@ -34,3 +42,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocMemberSymbolParameters);
constructor(parameters: IDocMemberSymbolParameters | IDocMemberSymbolParsedParameters);
/**

@@ -42,8 +50,3 @@ * The declaration reference for the ECMAScript 6 symbol that will act as

/** @override */
updateParameters(parameters: IDocMemberSymbolParameters): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

44

lib/nodes/DocMemberSymbol.js

@@ -17,3 +17,3 @@ "use strict";

var DocNode_1 = require("./DocNode");
var DocParticle_1 = require("./DocParticle");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -39,2 +39,19 @@ * Represents a reference to an ECMAScript 6 symbol that is used

_this.kind = "MemberSymbol" /* MemberSymbol */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
_this._leftBracketExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "DocMemberSymbol_LeftBracket" /* DocMemberSymbol_LeftBracket */,
content: parameters.leftBracketExcerpt
});
if (parameters.spacingAfterLeftBracketExcerpt) {
_this._spacingAfterLeftBracketExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterLeftBracketExcerpt
});
}
_this._rightBracketExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "DocMemberSymbol_RightBracket" /* DocMemberSymbol_RightBracket */,
content: parameters.rightBracketExcerpt
});
}
_this._symbolReference = parameters.symbolReference;
return _this;

@@ -54,25 +71,8 @@ }

/** @override */
DocMemberSymbol.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._leftBracketParticle = new DocParticle_1.DocParticle({
particleId: 'leftBracket',
excerpt: parameters.leftBracketExcerpt,
content: '['
});
this._symbolReference = parameters.symbolReference;
this._rightBracketParticle = new DocParticle_1.DocParticle({
particleId: 'rightBracket',
excerpt: parameters.rightBracketExcerpt,
content: ']'
});
};
/**
* {@inheritDoc}
* @override
*/
DocMemberSymbol.prototype.getChildNodes = function () {
DocMemberSymbol.prototype.onGetChildNodes = function () {
return [
this._leftBracketParticle,
this._leftBracketExcerpt,
this._spacingAfterLeftBracketExcerpt,
this._symbolReference,
this._rightBracketParticle
this._rightBracketExcerpt
];

@@ -79,0 +79,0 @@ };

50

lib/nodes/DocNode.d.ts

@@ -7,2 +7,3 @@ /**

BlockTag = "BlockTag",
Excerpt = "Excerpt",
FencedCode = "FencedCode",

@@ -24,3 +25,2 @@ CodeSpan = "CodeSpan",

MemberSymbol = "MemberSymbol",
Particle = "Particle",
Paragraph = "Paragraph",

@@ -34,2 +34,8 @@ ParamBlock = "ParamBlock",

* Constructor parameters for {@link DocNode}.
*
* @remarks
* There are two scenarios for constructing `DocNode` objects. The "builder scenario" constructs the object based on
* literal strings, does NOT create DocExcerpt child nodes, and generally uses the `IDocNodeParameters`
* hierarchy for its constructor parameters. The "parser scenario" constructs the object by parsing a TypeScript
* source file, does create DocExcerpt child nodes, and generally uses the {@link IDocNodeParsedParameters} hierarchy.
*/

@@ -39,6 +45,21 @@ export interface IDocNodeParameters {

/**
* Constructor parameters for {@link DocNode}.
*
* @remarks
* There are two scenarios for constructing `DocNode` objects. The "builder scenario" constructs the object based on
* literal strings, does NOT create DocExcerpt child nodes, and generally uses the {@link IDocNodeParameters}
* hierarchy for its constructor parameters. The "parser scenario" constructs the object by parsing a TypeScript
* source file, does create DocExcerpt child nodes, and generally uses the `IDocNodeParsedParameters` hierarchy.
*/
export interface IDocNodeParsedParameters {
/**
* This is a marker used by {@link DocNode.isParsedParameters} to determine whether the constructor was
* invoked using `IDocNodeParameters` (builder scenario) or `IDocNodeParsedParameters` (parser scenario).
*/
parsed: true;
}
/**
* The base class for the parser's Abstract Syntax Tree nodes.
*/
export declare abstract class DocNode {
private static _badSpacingRegExp;
/**

@@ -48,17 +69,24 @@ * Indicates the kind of DocNode.

abstract readonly kind: DocNodeKind;
constructor(parameters: IDocNodeParameters | IDocNodeParsedParameters);
/**
* Returns the array with any undefined elements removed.
*/
protected static trimUndefinedNodes(nodes: ReadonlyArray<DocNode | undefined>): ReadonlyArray<DocNode>;
protected static validateSpacing(spacing: string | undefined, parameterName: string): void;
constructor(parameters: IDocNodeParameters);
/** @virtual */
updateParameters(parameters: IDocNodeParameters): void;
/**
* Returns the list of child nodes for this node. This is useful for visitors that want
* to scan the tree looking for nodes of a specific type, without having to process
* intermediary nodes.
*/
getChildNodes(): ReadonlyArray<DocNode>;
/**
* Overridden by child classes to implement {@link DocNode.getChildNodes}.
* @virtual
*/
getChildNodes(): ReadonlyArray<DocNode>;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
/**
* A type guard that returns true if the input uses the `IDocNodeParsedParameters` (parser scenario).
*
* @remarks
* There are two scenarios for constructing `DocNode` objects. The "builder scenario" constructs the object based on
* literal strings, does NOT create DocExcerpt child nodes, and generally uses the {@link IDocNodeParameters}
* hierarchy for its constructor parameters. The "parser scenario" constructs the object by parsing a TypeScript
* source file, does create DocExcerpt child nodes, and generally uses the {@link IDocNodeParsedParameters} hierarchy.
*/
static isParsedParameters(parameters: IDocNodeParameters | IDocNodeParsedParameters): parameters is IDocNodeParsedParameters;
}

42

lib/nodes/DocNode.js

@@ -8,33 +8,31 @@ "use strict";

function DocNode(parameters) {
this.updateParameters(parameters);
// (abstract)
}
/**
* Returns the array with any undefined elements removed.
* Returns the list of child nodes for this node. This is useful for visitors that want
* to scan the tree looking for nodes of a specific type, without having to process
* intermediary nodes.
*/
DocNode.trimUndefinedNodes = function (nodes) {
return nodes.filter(function (x) { return x; });
DocNode.prototype.getChildNodes = function () {
return this.onGetChildNodes().filter(function (x) { return x !== undefined; });
};
DocNode.validateSpacing = function (spacing, parameterName) {
if (spacing) {
var match = DocNode._badSpacingRegExp.exec(spacing);
if (match) {
var badCharacter = match[0];
throw new Error("The \"" + parameterName + "\" value contains a non-whitespace character \"" + badCharacter + "\"");
}
}
};
/** @virtual */
DocNode.prototype.updateParameters = function (parameters) {
// (virtual)
};
/**
* Returns the list of child nodes for this node. This is useful for visitors that want
* to scan the tree looking for nodes of a specific type, without having to process
* intermediary nodes.
* Overridden by child classes to implement {@link DocNode.getChildNodes}.
* @virtual
*/
DocNode.prototype.getChildNodes = function () {
DocNode.prototype.onGetChildNodes = function () {
return [];
};
DocNode._badSpacingRegExp = /\S/;
/**
* A type guard that returns true if the input uses the `IDocNodeParsedParameters` (parser scenario).
*
* @remarks
* There are two scenarios for constructing `DocNode` objects. The "builder scenario" constructs the object based on
* literal strings, does NOT create DocExcerpt child nodes, and generally uses the {@link IDocNodeParameters}
* hierarchy for its constructor parameters. The "parser scenario" constructs the object by parsing a TypeScript
* source file, does create DocExcerpt child nodes, and generally uses the {@link IDocNodeParsedParameters} hierarchy.
*/
DocNode.isParsedParameters = function (parameters) {
return parameters.parsed === true;
};
return DocNode;

@@ -41,0 +39,0 @@ }());

29

lib/nodes/DocNodeContainer.d.ts

@@ -1,2 +0,2 @@

import { DocNode, IDocNodeParameters } from './DocNode';
import { DocNode, IDocNodeParameters, IDocNodeParsedParameters } from './DocNode';
/**

@@ -8,2 +8,7 @@ * Constructor parameters for {@link DocNodeContainer}.

/**
* Constructor parameters for {@link DocNodeContainer}.
*/
export interface IDocNodeContainerParsedParameters extends IDocNodeParsedParameters {
}
/**
* DocNodeContainer is the base class for DocNode classes that act as a simple container

@@ -13,3 +18,3 @@ * for other child nodes. The child classes are {@link DocParagraph} and {@link DocSection}.

export declare abstract class DocNodeContainer extends DocNode {
private _nodes;
private readonly _nodes;
/**

@@ -19,16 +24,8 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocNodeContainerParameters);
constructor(parameters: IDocNodeContainerParameters | IDocNodeContainerParsedParameters);
/**
* The child nodes. Note that for subclasses {@link getChildNodes()} may enumerate
* additional nodes that are not part of this collection.
* The nodes that were added to this container.
*/
readonly nodes: ReadonlyArray<DocNode>;
/** @override */
updateParameters(parameters: IDocNodeContainerParameters): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
/**
* Returns true if the specified `docNode` is allowed to be added as a child node.

@@ -42,13 +39,15 @@ * The {@link appendNode()} and {@link appendNodes()} functions use this to validate their

/**
* Append a node to the collection.
* Append a node to the container.
*/
appendNode(docNode: DocNode): void;
/**
* Append nodes to the collection.
* Append nodes to the container.
*/
appendNodes(docNodes: ReadonlyArray<DocNode>): void;
/**
* Remove all nodes from the collection.
* Remove all nodes from the container.
*/
clearNodes(): void;
/** @override */
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

31

lib/nodes/DocNodeContainer.js

@@ -28,8 +28,9 @@ "use strict";

function DocNodeContainer(parameters) {
return _super.call(this, parameters) || this;
var _this = _super.call(this, parameters) || this;
_this._nodes = [];
return _this;
}
Object.defineProperty(DocNodeContainer.prototype, "nodes", {
/**
* The child nodes. Note that for subclasses {@link getChildNodes()} may enumerate
* additional nodes that are not part of this collection.
* The nodes that were added to this container.
*/

@@ -42,17 +43,3 @@ get: function () {

});
/** @override */
DocNodeContainer.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
if (this._nodes === undefined) {
this._nodes = [];
}
};
/**
* {@inheritDoc}
* @override
*/
DocNodeContainer.prototype.getChildNodes = function () {
return this._nodes;
};
/**
* Returns true if the specified `docNode` is allowed to be added as a child node.

@@ -68,3 +55,3 @@ * The {@link appendNode()} and {@link appendNodes()} functions use this to validate their

/**
* Append a node to the collection.
* Append a node to the container.
*/

@@ -78,3 +65,3 @@ DocNodeContainer.prototype.appendNode = function (docNode) {

/**
* Append nodes to the collection.
* Append nodes to the container.
*/

@@ -88,3 +75,3 @@ DocNodeContainer.prototype.appendNodes = function (docNodes) {

/**
* Remove all nodes from the collection.
* Remove all nodes from the container.
*/

@@ -94,2 +81,6 @@ DocNodeContainer.prototype.clearNodes = function () {

};
/** @override */
DocNodeContainer.prototype.onGetChildNodes = function () {
return this._nodes;
};
return DocNodeContainer;

@@ -96,0 +87,0 @@ }(DocNode_1.DocNode));

34

lib/nodes/DocParamBlock.d.ts
import { DocNodeKind, DocNode } from './DocNode';
import { DocBlock, IDocBlockParameters } from './DocBlock';
import { Excerpt } from '../parser/Excerpt';
import { DocBlock, IDocBlockParameters, IDocBlockParsedParameters } from './DocBlock';
import { TokenSequence } from '../parser/TokenSequence';
/**

@@ -8,7 +8,16 @@ * Constructor parameters for {@link DocParamBlock}.

export interface IDocParamBlockParameters extends IDocBlockParameters {
parameterNameExcerpt?: Excerpt;
parameterName: string;
hyphenExcerpt?: Excerpt;
}
/**
* Constructor parameters for {@link DocParamBlock}.
*/
export interface IDocParamBlockParsedParameters extends IDocBlockParsedParameters {
spacingBeforeParameterNameExcerpt?: TokenSequence;
parameterNameExcerpt: TokenSequence;
parameterName: string;
spacingAfterParameterNameExcerpt?: TokenSequence;
hyphenExcerpt: TokenSequence;
spacingAfterHyphenExcerpt?: TokenSequence;
}
/**
* Represents a parsed `@param` or `@typeParam` block, which provides a description for a

@@ -20,4 +29,8 @@ * function parameter.

readonly kind: DocNodeKind;
private _parameterNameParticle;
private _hyphenParticle;
private readonly _spacingBeforeParameterNameExcerpt;
private readonly _parameterName;
private readonly _parameterNameExcerpt;
private readonly _spacingAfterParameterNameExcerpt;
private readonly _hyphenExcerpt;
private readonly _spacingAfterHyphenExcerpt;
/**

@@ -27,3 +40,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocParamBlockParameters);
constructor(parameters: IDocParamBlockParameters | IDocParamBlockParsedParameters);
/**

@@ -35,8 +48,3 @@ * The name of the parameter that is being documented.

/** @override */
updateParameters(parameters: IDocParamBlockParameters): void;
/**
* {@inheritDoc}
* @override
*/
getChildNodes(): ReadonlyArray<DocNode>;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

63

lib/nodes/DocParamBlock.js

@@ -16,4 +16,5 @@ "use strict";

Object.defineProperty(exports, "__esModule", { value: true });
var DocNode_1 = require("./DocNode");
var DocBlock_1 = require("./DocBlock");
var DocParticle_1 = require("./DocParticle");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -33,2 +34,31 @@ * Represents a parsed `@param` or `@typeParam` block, which provides a description for a

_this.kind = "ParamBlock" /* ParamBlock */;
_this._parameterName = parameters.parameterName;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
if (parameters.spacingBeforeParameterNameExcerpt) {
_this._spacingBeforeParameterNameExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingBeforeParameterNameExcerpt
});
}
_this._parameterNameExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "ParamBlock_ParameterName" /* ParamBlock_ParameterName */,
content: parameters.parameterNameExcerpt
});
if (parameters.spacingAfterParameterNameExcerpt) {
_this._spacingAfterParameterNameExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterParameterNameExcerpt
});
}
_this._hyphenExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "ParamBlock_Hyphen" /* ParamBlock_Hyphen */,
content: parameters.hyphenExcerpt
});
if (parameters.spacingAfterHyphenExcerpt) {
_this._spacingAfterHyphenExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "Spacing" /* Spacing */,
content: parameters.spacingAfterHyphenExcerpt
});
}
}
return _this;

@@ -42,3 +72,3 @@ }

get: function () {
return this._parameterNameParticle.content;
return this._parameterName;
},

@@ -49,25 +79,12 @@ enumerable: true,

/** @override */
DocParamBlock.prototype.updateParameters = function (parameters) {
_super.prototype.updateParameters.call(this, parameters);
this._parameterNameParticle = new DocParticle_1.DocParticle({
particleId: 'parameterName',
excerpt: parameters.parameterNameExcerpt,
content: parameters.parameterName
});
this._hyphenParticle = new DocParticle_1.DocParticle({
particleId: 'hyphen',
excerpt: parameters.hyphenExcerpt,
content: '-'
});
};
/**
* {@inheritDoc}
* @override
*/
DocParamBlock.prototype.getChildNodes = function () {
DocParamBlock.prototype.onGetChildNodes = function () {
return [
this.blockTag,
this._parameterNameParticle,
this._hyphenParticle
].concat(this.nodes);
this._spacingBeforeParameterNameExcerpt,
this._parameterNameExcerpt,
this._spacingAfterParameterNameExcerpt,
this._hyphenExcerpt,
this._spacingAfterHyphenExcerpt,
this.content
];
};

@@ -74,0 +91,0 @@ return DocParamBlock;

20

lib/nodes/DocPlainText.d.ts

@@ -1,10 +0,16 @@

import { DocNodeKind } from './DocNode';
import { DocNodeLeaf, IDocNodeLeafParameters } from './DocNodeLeaf';
import { DocNodeKind, IDocNodeParameters, IDocNodeParsedParameters, DocNode } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';
/**
* Constructor parameters for {@link DocPlainText}.
*/
export interface IDocPlainTextParameters extends IDocNodeLeafParameters {
export interface IDocPlainTextParameters extends IDocNodeParameters {
text: string;
}
/**
* Constructor parameters for {@link DocPlainText}.
*/
export interface IDocPlainTextParsedParameters extends IDocNodeParsedParameters {
textExcerpt: TokenSequence;
}
/**
* Represents a span of comment text that is considered by the parser

@@ -17,3 +23,3 @@ * to contain no special symbols or meaning.

*/
export declare class DocPlainText extends DocNodeLeaf {
export declare class DocPlainText extends DocNode {
private static readonly _newlineCharacterRegExp;

@@ -23,2 +29,3 @@ /** {@inheritDoc} */

private _text;
private readonly _textExcerpt;
/**

@@ -28,3 +35,3 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocPlainTextParameters);
constructor(parameters: IDocPlainTextParameters | IDocPlainTextParsedParameters);
/**

@@ -34,4 +41,5 @@ * The text content.

readonly text: string;
readonly textExcerpt: TokenSequence | undefined;
/** @override */
updateParameters(parameters: IDocPlainTextParameters): void;
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

44

lib/nodes/DocPlainText.js

@@ -16,3 +16,4 @@ "use strict";

Object.defineProperty(exports, "__esModule", { value: true });
var DocNodeLeaf_1 = require("./DocNodeLeaf");
var DocNode_1 = require("./DocNode");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -36,2 +37,15 @@ * Represents a span of comment text that is considered by the parser

_this.kind = "PlainText" /* PlainText */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
_this._textExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "PlainText" /* PlainText */,
content: parameters.textExcerpt
});
}
else {
if (DocPlainText._newlineCharacterRegExp.test(parameters.text)) {
// Use DocSoftBreak to represent manual line splitting
throw new Error('The DocPlainText content must not contain newline characters');
}
_this._text = parameters.text;
}
return _this;

@@ -44,2 +58,5 @@ }

get: function () {
if (this._text === undefined) {
this._text = this._textExcerpt.content.toString();
}
return this._text;

@@ -50,10 +67,19 @@ },

});
Object.defineProperty(DocPlainText.prototype, "textExcerpt", {
get: function () {
if (this._textExcerpt) {
return this._textExcerpt.content;
}
else {
return undefined;
}
},
enumerable: true,
configurable: true
});
/** @override */
DocPlainText.prototype.updateParameters = function (parameters) {
if (DocPlainText._newlineCharacterRegExp.test(parameters.text)) {
// Use DocSoftBreak to represent manual line splitting
throw new Error('The DocPlainText content must not contain newline characters');
}
_super.prototype.updateParameters.call(this, parameters);
this._text = parameters.text;
DocPlainText.prototype.onGetChildNodes = function () {
return [
this._textExcerpt
];
};

@@ -64,4 +90,4 @@ // TODO: We should also prohibit "\r", but this requires updating LineExtractor

return DocPlainText;
}(DocNodeLeaf_1.DocNodeLeaf));
}(DocNode_1.DocNode));
exports.DocPlainText = DocPlainText;
//# sourceMappingURL=DocPlainText.js.map

12

lib/nodes/DocSection.d.ts
import { DocNode, DocNodeKind } from './DocNode';
import { DocNodeContainer, IDocNodeContainerParameters } from './DocNodeContainer';
import { DocNodeContainer, IDocNodeContainerParameters, IDocNodeContainerParsedParameters } from './DocNodeContainer';
/**

@@ -9,5 +9,9 @@ * Constructor parameters for {@link DocSection}.

/**
* Represents a general block of rich text. DocSection is the base class for DocNode classes that
* act as a simple container for other child nodes.
* Constructor parameters for {@link DocSection}.
*/
export interface IDocSectionParsedParameters extends IDocNodeContainerParsedParameters {
}
/**
* Represents a general block of rich text.
*/
export declare class DocSection extends DocNodeContainer {

@@ -20,3 +24,3 @@ /** {@inheritDoc} */

*/
constructor(parameters: IDocSectionParameters);
constructor(parameters: IDocSectionParameters | IDocSectionParsedParameters);
/**

@@ -23,0 +27,0 @@ * {@inheritDoc}

3

lib/nodes/DocSection.js

@@ -19,4 +19,3 @@ "use strict";

/**
* Represents a general block of rich text. DocSection is the base class for DocNode classes that
* act as a simple container for other child nodes.
* Represents a general block of rich text.
*/

@@ -23,0 +22,0 @@ var DocSection = /** @class */ (function (_super) {

19

lib/nodes/DocSoftBreak.d.ts

@@ -1,9 +0,15 @@

import { DocNodeKind } from './DocNode';
import { DocNodeLeaf, IDocNodeLeafParameters } from './DocNodeLeaf';
import { DocNodeKind, IDocNodeParameters, DocNode, IDocNodeParsedParameters } from './DocNode';
import { TokenSequence } from '../parser/TokenSequence';
/**
* Constructor parameters for {@link DocSoftBreak}.
*/
export interface IDocSoftBreakParameters extends IDocNodeLeafParameters {
export interface IDocSoftBreakParameters extends IDocNodeParameters {
}
/**
* Constructor parameters for {@link DocSoftBreak}.
*/
export interface IDocSoftBreakParsedParameters extends IDocNodeParsedParameters {
softBreakExcerpt: TokenSequence;
}
/**
* Instructs a renderer to insert an explicit newline in the output.

@@ -21,5 +27,6 @@ * (Normally the renderer uses a formatting rule to determine where

*/
export declare class DocSoftBreak extends DocNodeLeaf {
export declare class DocSoftBreak extends DocNode {
/** {@inheritDoc} */
readonly kind: DocNodeKind;
private readonly _softBreakExcerpt;
/**

@@ -29,3 +36,5 @@ * Don't call this directly. Instead use {@link TSDocParser}

*/
constructor(parameters: IDocSoftBreakParameters);
constructor(parameters: IDocSoftBreakParameters | IDocSoftBreakParsedParameters);
/** @override */
protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
}

17

lib/nodes/DocSoftBreak.js

@@ -16,3 +16,4 @@ "use strict";

Object.defineProperty(exports, "__esModule", { value: true });
var DocNodeLeaf_1 = require("./DocNodeLeaf");
var DocNode_1 = require("./DocNode");
var DocExcerpt_1 = require("./DocExcerpt");
/**

@@ -41,7 +42,19 @@ * Instructs a renderer to insert an explicit newline in the output.

_this.kind = "SoftBreak" /* SoftBreak */;
if (DocNode_1.DocNode.isParsedParameters(parameters)) {
_this._softBreakExcerpt = new DocExcerpt_1.DocExcerpt({
excerptKind: "SoftBreak" /* SoftBreak */,
content: parameters.softBreakExcerpt
});
}
return _this;
}
/** @override */
DocSoftBreak.prototype.onGetChildNodes = function () {
return [
this._softBreakExcerpt
];
};
return DocSoftBreak;
}(DocNodeLeaf_1.DocNodeLeaf));
}(DocNode_1.DocNode));
exports.DocSoftBreak = DocSoftBreak;
//# sourceMappingURL=DocSoftBreak.js.map

8

lib/nodes/index.d.ts
export * from './DocBlock';
export * from './DocBlockTag';
export * from './DocFencedCode';
export * from './DocCodeSpan';

@@ -9,7 +8,10 @@ export * from './DocComment';

export * from './DocEscapedText';
export * from './DocExcerpt';
export * from './DocFencedCode';
export * from './DocHtmlAttribute';
export * from './DocHtmlEndTag';
export * from './DocHtmlStartTag';
export * from './DocInheritDocTag';
export * from './DocInlineTag';
export * from './DocInheritDocTag';
export * from './DocInlineTagBase';
export * from './DocLinkTag';

@@ -22,8 +24,6 @@ export * from './DocMemberIdentifier';

export * from './DocNodeContainer';
export * from './DocNodeLeaf';
export * from './DocParagraph';
export * from './DocParamBlock';
export * from './DocParticle';
export * from './DocPlainText';
export * from './DocSection';
export * from './DocSoftBreak';

8

lib/nodes/index.js

@@ -8,3 +8,2 @@ "use strict";

__export(require("./DocBlockTag"));
__export(require("./DocFencedCode"));
__export(require("./DocCodeSpan"));

@@ -15,7 +14,10 @@ __export(require("./DocComment"));

__export(require("./DocEscapedText"));
__export(require("./DocExcerpt"));
__export(require("./DocFencedCode"));
__export(require("./DocHtmlAttribute"));
__export(require("./DocHtmlEndTag"));
__export(require("./DocHtmlStartTag"));
__export(require("./DocInheritDocTag"));
__export(require("./DocInlineTag"));
__export(require("./DocInheritDocTag"));
__export(require("./DocInlineTagBase"));
__export(require("./DocLinkTag"));

@@ -28,6 +30,4 @@ __export(require("./DocMemberIdentifier"));

__export(require("./DocNodeContainer"));
__export(require("./DocNodeLeaf"));
__export(require("./DocParagraph"));
__export(require("./DocParamBlock"));
__export(require("./DocParticle"));
__export(require("./DocPlainText"));

@@ -34,0 +34,0 @@ __export(require("./DocSection"));

3

lib/parser/NodeParser.d.ts

@@ -6,3 +6,2 @@ import { ParserContext } from './ParserContext';

export declare class NodeParser {
private static readonly htmlNameRegExp;
private readonly _parserContext;

@@ -42,3 +41,3 @@ private _currentSection;

private _parseCodeSpan;
private _readSpacingAndNewlines;
private _tryReadSpacingAndNewlines;
/**

@@ -45,0 +44,0 @@ * Read the next token, and report it as a DocErrorText node.

4

lib/parser/ParserMessageLog.js

@@ -52,5 +52,5 @@ "use strict";

var tokenSequence;
if (docErrorText.excerpt) {
if (docErrorText.textExcerpt) {
// If there is an excerpt directly associated with the DocErrorText, highlight that:
tokenSequence = docErrorText.excerpt.content;
tokenSequence = docErrorText.textExcerpt;
}

@@ -57,0 +57,0 @@ else {

9

lib/parser/StringChecks.d.ts

@@ -8,2 +8,3 @@ /**

private static readonly _urlSchemeAfterRegExp;
private static readonly _htmlNameRegExp;
private static readonly _identifierNotWordCharRegExp;

@@ -31,2 +32,10 @@ private static readonly _identifierNumberStartRegExp;

/**
* Tests whether the input string is a valid HTML element or attribute name.
*/
static explainIfInvalidHtmlName(htmlName: string): string | undefined;
/**
* Throws an exception if the input string is a not valid HTML element or attribute name.
*/
static validateHtmlName(htmlName: string): void;
/**
* Tests whether the input string is a valid NPM package name.

@@ -33,0 +42,0 @@ */

21

lib/parser/StringChecks.js

@@ -52,2 +52,20 @@ "use strict";

/**
* Tests whether the input string is a valid HTML element or attribute name.
*/
StringChecks.explainIfInvalidHtmlName = function (htmlName) {
if (!StringChecks._htmlNameRegExp.test(htmlName)) {
return 'An HTML name must be a sequence of letters separated by hyphens';
}
return undefined;
};
/**
* Throws an exception if the input string is a not valid HTML element or attribute name.
*/
StringChecks.validateHtmlName = function (htmlName) {
var explanation = StringChecks.explainIfInvalidHtmlName(htmlName);
if (explanation) {
throw new Error(explanation);
}
};
/**
* Tests whether the input string is a valid NPM package name.

@@ -115,2 +133,5 @@ */

StringChecks._urlSchemeAfterRegExp = /^[a-z][a-z0-9]*\:\/\/./i;
// https://www.w3.org/TR/html5/syntax.html#tag-name
// https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
StringChecks._htmlNameRegExp = /^[a-z]+(\-[a-z]+)*$/i;
StringChecks._identifierNotWordCharRegExp = /\W/u;

@@ -117,0 +138,0 @@ StringChecks._identifierNumberStartRegExp = /^[0-9]/u;

10

lib/renderers/PlainTextRenderer.js

@@ -30,8 +30,6 @@ "use strict";

}
if (node instanceof nodes_1.DocNodeContainer) {
for (var _a = 0, _b = node.getChildNodes(); _a < _b.length; _a++) {
var childNode = _b[_a];
if (this.hasAnyTextContent(childNode)) {
return true;
}
for (var _a = 0, _b = node.getChildNodes(); _a < _b.length; _a++) {
var childNode = _b[_a];
if (this.hasAnyTextContent(childNode)) {
return true;
}

@@ -38,0 +36,0 @@ }

2

lib/transforms/TrimSpacesTransform.d.ts

@@ -7,4 +7,2 @@ import { DocParagraph } from '../nodes';

static transform(docParagraph: DocParagraph): DocParagraph;
private static _canMergeExcerpts;
private static _mergeExcerpts;
}

102

lib/transforms/TrimSpacesTransform.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
var nodes_1 = require("../nodes");
var Excerpt_1 = require("../parser/Excerpt");
/**

@@ -16,3 +15,4 @@ * Implementation of DocNodeTransforms.trimSpacesInParagraphNodes()

// The DocPlainText node that we're currently accumulating
var accumulatedPlainTextNode = undefined;
var accumulatedTextChunks = [];
var accumulatedNodes = [];
// We always trim leading whitespace for a paragraph. This flag gets set to true

@@ -26,5 +26,6 @@ // as soon as nonempty content is encountered.

var docPlainText = node;
var startedWithSpace = /^\s/.test(docPlainText.text);
var endedWithSpace = /\s$/.test(docPlainText.text);
var collapsedText = docPlainText.text.replace(/\s+/g, ' ').trim();
var text = docPlainText.text;
var startedWithSpace = /^\s/.test(text);
var endedWithSpace = /\s$/.test(text);
var collapsedText = text.replace(/\s+/g, ' ').trim();
if (startedWithSpace && finishedSkippingLeadingSpaces) {

@@ -34,22 +35,8 @@ pendingSpace = true;

if (collapsedText.length > 0) {
if (accumulatedPlainTextNode) {
// If this node can't be merged, then eject it
if (!TrimSpacesTransform._canMergeExcerpts(accumulatedPlainTextNode.excerpt, docPlainText.excerpt)) {
transformedNodes.push(new nodes_1.DocPlainText(accumulatedPlainTextNode));
accumulatedPlainTextNode = undefined;
}
}
// If we haven't started an accumulatedPlainTextNode, create it now
if (!accumulatedPlainTextNode) {
accumulatedPlainTextNode = {
excerpt: undefined,
text: ''
};
}
if (pendingSpace) {
accumulatedPlainTextNode.text += ' ';
accumulatedTextChunks.push(' ');
pendingSpace = false;
}
accumulatedPlainTextNode.text += collapsedText;
accumulatedPlainTextNode.excerpt = TrimSpacesTransform._mergeExcerpts(accumulatedPlainTextNode.excerpt, docPlainText.excerpt);
accumulatedTextChunks.push(collapsedText);
accumulatedNodes.push(node);
finishedSkippingLeadingSpaces = true;

@@ -65,19 +52,18 @@ }

}
accumulatedNodes.push(node);
break;
default:
if (pendingSpace) {
// If we haven't started an accumulatedPlainTextNode, create it now
if (!accumulatedPlainTextNode) {
accumulatedPlainTextNode = {
excerpt: undefined,
text: ''
};
}
accumulatedPlainTextNode.text += ' ';
accumulatedTextChunks.push(' ');
pendingSpace = false;
}
// Push the accumulated text
if (accumulatedPlainTextNode) {
transformedNodes.push(new nodes_1.DocPlainText(accumulatedPlainTextNode));
accumulatedPlainTextNode = undefined;
if (accumulatedTextChunks.length > 0) {
// TODO: We should probably track the accumulatedNodes somehow, e.g. so we can map them back to the
// original excerpts. But we need a developer scenario before we can design this API.
transformedNodes.push(new nodes_1.DocPlainText({
text: accumulatedTextChunks.join('')
}));
accumulatedTextChunks.length = 0;
accumulatedNodes.length = 0;
}

@@ -89,5 +75,8 @@ transformedNodes.push(node);

// Push the accumulated text
if (accumulatedPlainTextNode) {
transformedNodes.push(new nodes_1.DocPlainText(accumulatedPlainTextNode));
accumulatedPlainTextNode = undefined;
if (accumulatedTextChunks.length > 0) {
transformedNodes.push(new nodes_1.DocPlainText({
text: accumulatedTextChunks.join('')
}));
accumulatedTextChunks.length = 0;
accumulatedNodes.length = 0;
}

@@ -98,43 +87,2 @@ var transformedParagraph = new nodes_1.DocParagraph({});

};
TrimSpacesTransform._canMergeExcerpts = function (currentExcerpt, followingExcerpt) {
if (currentExcerpt === undefined || followingExcerpt === undefined) {
return true;
}
if (!currentExcerpt.spacingAfterContent.isEmpty()
|| !followingExcerpt.spacingAfterContent.isEmpty()) {
return false;
}
var currentSequence = currentExcerpt.content;
var followingSequence = followingExcerpt.content;
if (currentSequence.parserContext !== followingSequence.parserContext) {
return false;
}
return currentSequence.endIndex === followingSequence.startIndex;
};
TrimSpacesTransform._mergeExcerpts = function (currentExcerpt, followingExcerpt) {
if (currentExcerpt === undefined) {
return followingExcerpt;
}
if (followingExcerpt === undefined) {
return currentExcerpt;
}
if (!currentExcerpt.spacingAfterContent.isEmpty()
|| !followingExcerpt.spacingAfterContent.isEmpty()) {
// This would be a program bug
throw new Error('mergeExcerpts(): Cannot merge excerpts with spacingAfterContent');
}
var currentSequence = currentExcerpt.content;
var followingSequence = followingExcerpt.content;
if (currentSequence.parserContext !== followingSequence.parserContext) {
// This would be a program bug
throw new Error('mergeExcerpts(): Cannot merge excerpts with incompatible parser contexts');
}
if (currentSequence.endIndex !== followingSequence.startIndex) {
// This would be a program bug
throw new Error('mergeExcerpts(): Cannot merge excerpts that are not adjacent');
}
return new Excerpt_1.Excerpt({
content: currentSequence.getNewSequence(currentSequence.startIndex, followingSequence.endIndex)
});
};
return TrimSpacesTransform;

@@ -141,0 +89,0 @@ }());

6

package.json
{
"name": "@microsoft/tsdoc",
"version": "0.8.1",
"version": "0.9.0",
"description": "A parser for the TypeScript doc comment syntax",

@@ -30,6 +30,6 @@ "keywords": [

"tslint-microsoft-contrib": "~5.2.1",
"typescript": "~3.1.1"
"typescript": "~3.1.2"
},
"scripts": {
"build": "rimraf ./lib/ && echo -- TYPESCRIPT -- && tsc && echo -- TSLINT -- && tslint --config tslint.json --project . --rules-dir node_modules/tslint-microsoft-contrib",
"build": "node ./build.js",
"test": "jest",

@@ -36,0 +36,0 @@ "watch": "jest --watch"

6

README.md

@@ -29,6 +29,10 @@ # @microsoft/tsdoc

## Give it a try!
Check out the [TSDoc Playground](https://microsoft.github.io/tsdoc/) for a cool live demo of our parser!
## Get involved
The **TSDoc** project is under active development and evolving. For up to date documentation and other background, please visit the project site:
The **TSDoc** project is actively evolving. Please visit our GitHub project for the latest documentation, instructions for building/debugging the projects, and other resources:
https://github.com/Microsoft/tsdoc
lib/nodes/DocNodeLeaf.d.ts
lib/nodes/DocNodeLeaf.js
lib/nodes/DocNodeLeaf.js.map
lib/nodes/DocParticle.d.ts
lib/nodes/DocParticle.js
lib/nodes/DocParticle.js.map
lib/parser/Excerpt.d.ts
lib/parser/Excerpt.js
lib/parser/Excerpt.js.map
lib/index.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocBlock.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocBlockTag.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocCodeSpan.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocComment.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocDeclarationReference.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocErrorText.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocEscapedText.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocFencedCode.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocHtmlAttribute.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocHtmlEndTag.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocHtmlStartTag.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocInheritDocTag.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocInlineTag.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocLinkTag.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocMemberIdentifier.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocMemberReference.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocMemberSelector.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocMemberSymbol.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocNode.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocNodeContainer.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocParamBlock.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocPlainText.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocSection.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/DocSoftBreak.js.map

Sorry, the diff of this file is not supported yet

lib/nodes/index.js.map

Sorry, the diff of this file is not supported yet

lib/parser/NodeParser.js

Sorry, the diff of this file is too big to display

lib/parser/NodeParser.js.map

Sorry, the diff of this file is not supported yet

lib/parser/ParserMessageLog.js.map

Sorry, the diff of this file is not supported yet

lib/parser/StringChecks.js.map

Sorry, the diff of this file is not supported yet

lib/renderers/PlainTextRenderer.js.map

Sorry, the diff of this file is not supported yet

lib/transforms/TrimSpacesTransform.js.map

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc