@microsoft/api-extractor
Advanced tools
@microsoft/api-extractor - npm Package Compare versions
Comparing version 4.1.2 to 4.2.0
@@ -5,2 +5,24 @@ { | ||
| { | ||
| "version": "4.2.0", | ||
| "tag": "@microsoft/api-extractor_v4.2.0", | ||
| "date": "Wed, 25 Oct 2017 20:03:59 GMT", | ||
| "comments": { | ||
| "minor": [ | ||
| { | ||
| "author": "pgonzal <pgonzal@users.noreply.github.com>", | ||
| "commit": "6cc203e0282130eb7c9a40906c1a8861c763d56c", | ||
| "comment": "Improved the way API JSON represents documentation markup; this is a file format change" | ||
| } | ||
| ], | ||
| "dependency": [ | ||
| { | ||
| "comment": "Updating dependency \"@microsoft/node-core-library\" from `~0.3.9` to `~0.3.10`" | ||
| }, | ||
| { | ||
| "comment": "Updating dependency \"@microsoft/ts-command-line\" from `~2.1.2` to `~2.1.3`" | ||
| } | ||
| ] | ||
| } | ||
| }, | ||
| { | ||
| "version": "4.1.2", | ||
@@ -7,0 +29,0 @@ "tag": "@microsoft/api-extractor_v4.1.2", |
| # Change Log - @microsoft/api-extractor | ||
| This log was last generated on Tue, 24 Oct 2017 18:17:12 GMT and should not be manually modified. | ||
| This log was last generated on Wed, 25 Oct 2017 20:03:59 GMT and should not be manually modified. | ||
| ## 4.2.0 | ||
| Wed, 25 Oct 2017 20:03:59 GMT | ||
| ### Minor changes | ||
| - Improved the way API JSON represents documentation markup; this is a file format change | ||
| ## 4.1.2 | ||
@@ -6,0 +13,0 @@ Tue, 24 Oct 2017 18:17:12 GMT |
| import AstPackage from '../ast/AstPackage'; | ||
| import { IDocElement, ICodeLinkElement } from '../markup/OldMarkup'; | ||
| import ApiDefinitionReference from '../ApiDefinitionReference'; | ||
@@ -9,2 +8,3 @@ import Token from './Token'; | ||
| import { ReleaseTag } from './ReleaseTag'; | ||
| import { MarkupElement, MarkupBasicElement, IMarkupApiLink } from '../markup/MarkupElement'; | ||
| /** | ||
@@ -29,3 +29,3 @@ * A dependency for ApiDocumentation constructor that abstracts away the function | ||
| name: string; | ||
| description: IDocElement[]; | ||
| description: MarkupBasicElement[]; | ||
| } | ||
@@ -63,6 +63,6 @@ export default class ApiDocumentation { | ||
| */ | ||
| summary: IDocElement[]; | ||
| deprecatedMessage: IDocElement[]; | ||
| remarks: IDocElement[]; | ||
| returnsMessage: IDocElement[]; | ||
| summary: MarkupElement[]; | ||
| deprecatedMessage: MarkupBasicElement[]; | ||
| remarks: MarkupElement[]; | ||
| returnsMessage: MarkupBasicElement[]; | ||
| parameters: { | ||
@@ -78,3 +78,3 @@ [name: string]: IAedocParameter; | ||
| */ | ||
| incompleteLinks: ICodeLinkElement[]; | ||
| incompleteLinks: IMarkupApiLink[]; | ||
| /** | ||
@@ -81,0 +81,0 @@ * A list of 'Token' objects that have been recognized as \@inheritdoc tokens that will be processed |
@@ -10,2 +10,3 @@ "use strict"; | ||
| const ReleaseTag_1 = require("./ReleaseTag"); | ||
| const Markup_1 = require("../markup/Markup"); | ||
| class ApiDocumentation { | ||
@@ -44,3 +45,3 @@ constructor(docComment, referenceResolver, context, errorLogger, warnings) { | ||
| const tokenizer = new Tokenizer_1.default(this.originalAedoc, this.reportError); | ||
| this.summary = DocElementParser_1.default.getTrimmedSpan(DocElementParser_1.default.parse(this, tokenizer)); | ||
| this.summary = DocElementParser_1.default.parseAndNormalize(this, tokenizer); | ||
| let releaseTagCount = 0; | ||
@@ -66,3 +67,3 @@ let parsing = true; | ||
| this._checkInheritDocStatus(token.tag); | ||
| this.remarks = DocElementParser_1.default.getTrimmedSpan(DocElementParser_1.default.parse(this, tokenizer)); | ||
| this.remarks = DocElementParser_1.default.parseAndNormalize(this, tokenizer); | ||
| break; | ||
@@ -72,3 +73,3 @@ case '@returns': | ||
| this._checkInheritDocStatus(token.tag); | ||
| this.returnsMessage = DocElementParser_1.default.getTrimmedSpan(DocElementParser_1.default.parse(this, tokenizer)); | ||
| this.returnsMessage = DocElementParser_1.default.parseAndNormalize(this, tokenizer); | ||
| break; | ||
@@ -85,3 +86,3 @@ case '@param': | ||
| tokenizer.getToken(); | ||
| this.deprecatedMessage = DocElementParser_1.default.getTrimmedSpan(DocElementParser_1.default.parse(this, tokenizer)); | ||
| this.deprecatedMessage = DocElementParser_1.default.parseAndNormalize(this, tokenizer); | ||
| if (!this.deprecatedMessage || this.deprecatedMessage.length === 0) { | ||
@@ -192,9 +193,10 @@ this.reportError(`deprecated description required after @deprecated AEDoc tag.`); | ||
| } | ||
| const commentTextElement = DocElementParser_1.default.makeTextElement(comment); | ||
| const commentTextElements = Markup_1.Markup.createTextElements(comment); | ||
| // Full param description may contain additional Tokens (Ex: @link) | ||
| const remainingElements = DocElementParser_1.default.parse(this, tokenizer); | ||
| const descriptionElements = [commentTextElement].concat(remainingElements); | ||
| const descriptionElements = commentTextElements.concat(remainingElements); | ||
| Markup_1.Markup.normalize(descriptionElements); | ||
| const paramDocElement = { | ||
| name: name, | ||
| description: DocElementParser_1.default.getTrimmedSpan(descriptionElements) | ||
| description: descriptionElements | ||
| }; | ||
@@ -212,6 +214,6 @@ return paramDocElement; | ||
| const parts = { | ||
| scopeName: codeLink.scopeName, | ||
| packageName: codeLink.packageName, | ||
| exportName: codeLink.exportName, | ||
| memberName: codeLink.memberName | ||
| scopeName: codeLink.target.scopeName, | ||
| packageName: codeLink.target.packageName, | ||
| exportName: codeLink.target.exportName, | ||
| memberName: codeLink.target.memberName | ||
| }; | ||
@@ -283,3 +285,2 @@ const apiDefinitionRef = ApiDefinitionReference_1.default.createFromParts(parts); | ||
| '@returns', | ||
| '@see', | ||
| '@deprecated', | ||
@@ -286,0 +287,0 @@ '@readonly', |
@@ -7,8 +7,8 @@ { | ||
| //============================================================================================= | ||
| // Documentation Elements | ||
| // Markup Elements | ||
| //============================================================================================= | ||
| //--------------------------------------------------------------------------------------------- | ||
| "textDocElement": { | ||
| "description": "A documentation element representing a block of plain text", | ||
| "markupText": { | ||
| "description": "A block of plain text, possibly with simple formatting such as bold or italics", | ||
| "type": "object", | ||
@@ -18,18 +18,26 @@ | ||
| "kind": { | ||
| "description": "The kind of documentation element", | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "textDocElement" ] | ||
| "enum": [ "text" ] | ||
| }, | ||
| "value": { | ||
| "description": "The text", | ||
| "text": { | ||
| "description": "The text content to display", | ||
| "type": "string" | ||
| }, | ||
| "bold": { | ||
| "description": "Whether the text should be formatted using boldface", | ||
| "type": "boolean" | ||
| }, | ||
| "italics": { | ||
| "description": "Whether the text should be formatted using italics", | ||
| "type": "boolean" | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind", "value" ] | ||
| "required": [ "kind", "text" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "paragraphDocElement": { | ||
| "description": "A documentation element representing a break between paragraphs", | ||
| "markupHighlightedText": { | ||
| "description": "Source code shown in a fixed-width font, with syntax highlighting", | ||
| "type": "object", | ||
@@ -39,50 +47,224 @@ | ||
| "kind": { | ||
| "description": "The kind of documentation element", | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "paragraphDocElement" ] | ||
| "enum": [ "code" ] | ||
| }, | ||
| "text": { | ||
| "description": "The text content to display", | ||
| "type": "string" | ||
| }, | ||
| "highlighter": { | ||
| "description": "The syntax highlighting to be applied to the text", | ||
| "type": "string", | ||
| "enum": [ "javascript", "plain" ] | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind" ] | ||
| "required": [ "kind", "text", "highlighter" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "linkDocElement": { | ||
| "description": "A documentation element representing a hyperlink", | ||
| "markupLinkTextElement": { | ||
| "description": "Represents markup that can be used as the link text for a hyperlink", | ||
| "type": "object", | ||
| "oneOf": [ | ||
| { "$ref": "#/definitions/markupText" }, | ||
| { "$ref": "#/definitions/markupHighlightedText" } | ||
| ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "markupApiLink": { | ||
| "description": "A hyperlink to an API item", | ||
| "type": "object", | ||
| "properties": { | ||
| "kind": { | ||
| "description": "The kind of documentation element", | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "linkDocElement" ] | ||
| "enum": [ "api-link" ] | ||
| }, | ||
| "referenceType": { | ||
| "description": "The link can either refer to a API definition or href", | ||
| "elements": { | ||
| "description": "The link text", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupLinkTextElement" } | ||
| }, | ||
| "target": { | ||
| "description": "The API item that will serve as the hyperlink target", | ||
| "type": "object", | ||
| "properties": { | ||
| "scopeName": { | ||
| "description": "An optional NPM scope for the package name", | ||
| "type": "string" | ||
| }, | ||
| "packageName": { | ||
| "description": "The name of the NPM package being referenced (must be a nonempty string)", | ||
| "type": "string", | ||
| "minLength": 1 | ||
| }, | ||
| "exportName": { | ||
| "description": "The name of the package export", | ||
| "type": "string" | ||
| }, | ||
| "memberName": { | ||
| "description": "An optional name of a member of the package export", | ||
| "type": "string" | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "scopeName", "packageName", "exportName", "memberName" ] | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind", "elements", "target" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "markupWebLink": { | ||
| "description": "A hyperlink to an internet URL", | ||
| "type": "object", | ||
| "properties": { | ||
| "kind": { | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "href", "code" ] | ||
| "enum": [ "web-link" ] | ||
| }, | ||
| "elements": { | ||
| "description": "The link text", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupLinkTextElement" } | ||
| }, | ||
| "targetUrl": { | ||
| "description": "The target URL for the hyperlink", | ||
| "description": "The internet URL that will serve as the hyperlink target", | ||
| "type": "string" | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind", "elements", "targetUrl" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "markupParagraph": { | ||
| "description": "A paragraph separator, similar to the \"<p>\" tag in HTML", | ||
| "type": "object", | ||
| "properties": { | ||
| "kind": { | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "paragraph" ] | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "markupLineBreak": { | ||
| "description": "A line break, similar to the \"<br>\" tag in HTML.", | ||
| "type": "object", | ||
| "properties": { | ||
| "kind": { | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "break" ] | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "markupBasicElement": { | ||
| "description": "Represents basic text consisting of paragraphs and links (without structures such as headers or tables)", | ||
| "type": "object", | ||
| "oneOf": [ | ||
| { "$ref": "#/definitions/markupLinkTextElement" }, | ||
| { "$ref": "#/definitions/markupApiLink" }, | ||
| { "$ref": "#/definitions/markupWebLink" }, | ||
| { "$ref": "#/definitions/markupParagraph" }, | ||
| { "$ref": "#/definitions/markupLineBreak" } | ||
| ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "markupHeading1": { | ||
| "description": "A top-level heading", | ||
| "type": "object", | ||
| "properties": { | ||
| "kind": { | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "heading1" ] | ||
| }, | ||
| "value": { | ||
| "description": "An optional display name to show for a link", | ||
| "text": { | ||
| "description": "The heading title", | ||
| "type": "string" | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind", "text" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "markupHeading2": { | ||
| "description": "A sub heading", | ||
| "type": "object", | ||
| "properties": { | ||
| "kind": { | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "heading2" ] | ||
| }, | ||
| "memberName": { | ||
| "description": "An optional name that specifies the export item", | ||
| "text": { | ||
| "description": "The heading title", | ||
| "type": "string" | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind", "text" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "markupCodeBox": { | ||
| "description": "A box containing source code with syntax highlighting", | ||
| "type": "object", | ||
| "properties": { | ||
| "kind": { | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "code-box" ] | ||
| }, | ||
| "exportName": { | ||
| "description": "A name that is required if the referenceType is code", | ||
| "text": { | ||
| "description": "The text content to display", | ||
| "type": "string" | ||
| }, | ||
| "packageName": { | ||
| "description": "The name of the package being referenced (must be a nonempty string)", | ||
| "highlighter": { | ||
| "description": "The syntax highlighting to be applied to the text", | ||
| "type": "string", | ||
| "minLength": 1 | ||
| "enum": [ "javascript", "plain" ] | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind", "text", "highlighter" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "markupNoteBox": { | ||
| "description": "A call-out box containing an informational note", | ||
| "type": "object", | ||
| "properties": { | ||
| "kind": { | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "note-box" ] | ||
| }, | ||
| "scopeName": { | ||
| "description": "An optional name that scopes the package name", | ||
| "text": { | ||
| "description": "The text content to display", | ||
| "type": "string" | ||
@@ -92,8 +274,8 @@ } | ||
| "additionalProperties": false, | ||
| "required": [ "kind", "referenceType" ] | ||
| "required": [ "kind", "text" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "seeDocElement": { | ||
| "description": "A documentation element representing a see js doc tag", | ||
| "markupTable": { | ||
| "description": "A table, with an optional header row", | ||
| "type": "object", | ||
@@ -103,36 +285,77 @@ | ||
| "kind": { | ||
| "description": "The kind of documentation element", | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "seeDocElement" ] | ||
| "enum": [ "table" ] | ||
| }, | ||
| "seeElements": { | ||
| "description": "The element collection that follows the see js dog tag.", | ||
| "header": { "$ref": "#/definitions/markupTableRow" }, | ||
| "rows": { | ||
| "description": "The table rows", | ||
| "type": "array", | ||
| "items": { | ||
| "oneOf": [ | ||
| { "$ref": "#/definitions/textDocElement" }, | ||
| { "$ref": "#/definitions/paragraphDocElement" }, | ||
| { "$ref": "#/definitions/linkDocElement" } | ||
| ] | ||
| } | ||
| "items": { "$ref": "#/definitions/markupTableRow" } | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind", "seeElements" ] | ||
| "required": [ "kind", "rows" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "docElementCollection": { | ||
| "description": "A block of annotated text, represented as a list of documentation elements", | ||
| "type": "array", | ||
| "items": { | ||
| "oneOf": [ | ||
| { "$ref": "#/definitions/textDocElement" }, | ||
| { "$ref": "#/definitions/paragraphDocElement" }, | ||
| { "$ref": "#/definitions/linkDocElement" }, | ||
| { "$ref": "#/definitions/seeDocElement" } | ||
| ] | ||
| } | ||
| "markupStructuredElement": { | ||
| "description": "Represents structured text that contains headings, tables, and boxes", | ||
| "type": "object", | ||
| "oneOf": [ | ||
| { "$ref": "#/definitions/markupBasicElement" }, | ||
| { "$ref": "#/definitions/markupHeading1" }, | ||
| { "$ref": "#/definitions/markupHeading2" }, | ||
| { "$ref": "#/definitions/markupCodeBox" }, | ||
| { "$ref": "#/definitions/markupNoteBox" }, | ||
| { "$ref": "#/definitions/markupTable" } | ||
| ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "markupTableCell": { | ||
| "description": "A cell inside an table row element", | ||
| "type": "object", | ||
| "properties": { | ||
| "kind": { | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "table-cell" ] | ||
| }, | ||
| "elements": { | ||
| "description": "The cell text", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind", "elements" ] | ||
| }, | ||
| //--------------------------------------------------------------------------------------------- | ||
| "markupTableRow": { | ||
| "description": "A row inside an table element", | ||
| "type": "object", | ||
| "properties": { | ||
| "kind": { | ||
| "description": "The kind of markup element", | ||
| "type": "string", | ||
| "enum": [ "table-row" ] | ||
| }, | ||
| "cells": { | ||
| "description": "The cells comprising this row, ordered from left to right", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupTableCell" } | ||
| } | ||
| }, | ||
| "additionalProperties": false, | ||
| "required": [ "kind", "elements" ] | ||
| }, | ||
| //============================================================================================= | ||
@@ -154,3 +377,5 @@ // API Items | ||
| "summary": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A short description of the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -173,3 +398,5 @@ "signature": { | ||
| "description": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A description of the parameter", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -196,6 +423,10 @@ "isOptional": { | ||
| "remarks": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "Detailed additional notes regarding the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupStructuredElement" } | ||
| }, | ||
| "deprecatedMessage": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "If present, indicates that the item is deprecated and describes the recommended alternative", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
@@ -245,3 +476,5 @@ }, | ||
| "summary": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A short description of the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -251,6 +484,10 @@ | ||
| "remarks": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "Detailed additional notes regarding the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupStructuredElement" } | ||
| }, | ||
| "deprecatedMessage": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "If present, indicates that the item is deprecated and describes the recommended alternative", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
@@ -286,3 +523,5 @@ }, | ||
| "summary": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A short description of the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -296,6 +535,10 @@ "isBeta": { | ||
| "remarks": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "Detailed additional notes regarding the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupStructuredElement" } | ||
| }, | ||
| "deprecatedMessage": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "If present, indicates that the item is deprecated and describes the recommended alternative", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
@@ -351,3 +594,5 @@ }, | ||
| "description": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A description of the parameter", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -380,4 +625,6 @@ "isOptional": { | ||
| "description": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| } | ||
| "description": "A description of the return value", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
| }, | ||
@@ -388,3 +635,5 @@ "additionalProperties": false, | ||
| "summary": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A short description of the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -394,6 +643,10 @@ | ||
| "remarks": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "Detailed additional notes regarding the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupStructuredElement" } | ||
| }, | ||
| "deprecatedMessage": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "If present, indicates that the item is deprecated and describes the recommended alternative", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
@@ -432,3 +685,5 @@ }, | ||
| "description": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A description of the parameter", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -461,3 +716,5 @@ "isOptional": { | ||
| "description": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A description of the return value", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
@@ -469,3 +726,5 @@ }, | ||
| "summary": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A short description of the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -479,6 +738,10 @@ "isBeta": { | ||
| "remarks": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "Detailed additional notes regarding the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupStructuredElement" } | ||
| }, | ||
| "deprecatedMessage": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "If present, indicates that the item is deprecated and describes the recommended alternative", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
@@ -503,3 +766,5 @@ }, | ||
| "summary": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A short description of the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -542,6 +807,10 @@ "members": { | ||
| "remarks": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "Detailed additional notes regarding the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupStructuredElement" } | ||
| }, | ||
| "deprecatedMessage": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "If present, indicates that the item is deprecated and describes the recommended alternative", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
@@ -565,3 +834,5 @@ }, | ||
| "summary": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A short description of the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -584,6 +855,10 @@ "isBeta": { | ||
| "remarks": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "Detailed additional notes regarding the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupStructuredElement" } | ||
| }, | ||
| "deprecatedMessage": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "If present, indicates that the item is deprecated and describes the recommended alternative", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
@@ -607,3 +882,5 @@ }, | ||
| "summary": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A short description of the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -621,6 +898,10 @@ "isBeta": { | ||
| "remarks": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "Detailed additional notes regarding the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupStructuredElement" } | ||
| }, | ||
| "deprecatedMessage": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "If present, indicates that the item is deprecated and describes the recommended alternative", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
@@ -644,3 +925,5 @@ }, | ||
| "summary": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A short description of the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -682,6 +965,10 @@ "members": { | ||
| "remarks": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "Detailed additional notes regarding the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupStructuredElement" } | ||
| }, | ||
| "deprecatedMessage": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "If present, indicates that the item is deprecated and describes the recommended alternative", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
@@ -705,3 +992,5 @@ }, | ||
| "summary": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A short description of the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
@@ -734,6 +1023,10 @@ "exports": { | ||
| "remarks": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "Detailed additional notes regarding the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupStructuredElement" } | ||
| }, | ||
| "deprecatedMessage": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "If present, indicates that the item is deprecated and describes the recommended alternative", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| } | ||
@@ -765,6 +1058,10 @@ }, | ||
| "summary": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "A short description of the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupBasicElement" } | ||
| }, | ||
| "remarks": { | ||
| "$ref": "#/definitions/docElementCollection" | ||
| "description": "Detailed additional notes regarding the item", | ||
| "type": "array", | ||
| "items": { "$ref": "#/definitions/markupStructuredElement" } | ||
| }, | ||
@@ -771,0 +1068,0 @@ "exports": { |
@@ -1,2 +0,2 @@ | ||
| import { IDocElement } from '../markup/OldMarkup'; | ||
| import { MarkupBasicElement, MarkupStructuredElement } from '../markup/MarkupElement'; | ||
| /** | ||
@@ -51,3 +51,3 @@ * Represents a reference to an ApiItem. | ||
| */ | ||
| description: IDocElement[]; | ||
| description: MarkupBasicElement[]; | ||
| /** | ||
@@ -88,3 +88,3 @@ * Whether the parameter is optional | ||
| */ | ||
| description: IDocElement[]; | ||
| description: MarkupBasicElement[]; | ||
| } | ||
@@ -105,5 +105,5 @@ /** | ||
| isBeta: boolean; | ||
| summary: IDocElement[]; | ||
| remarks?: IDocElement[]; | ||
| deprecatedMessage?: IDocElement[]; | ||
| summary: MarkupBasicElement[]; | ||
| remarks: MarkupStructuredElement[]; | ||
| deprecatedMessage?: MarkupBasicElement[]; | ||
| } | ||
@@ -330,6 +330,6 @@ /** | ||
| */ | ||
| isBeta?: boolean; | ||
| summary?: IDocElement[]; | ||
| remarks?: IDocElement[]; | ||
| deprecatedMessage?: IDocElement[]; | ||
| isBeta: boolean; | ||
| summary: MarkupBasicElement[]; | ||
| remarks: MarkupStructuredElement[]; | ||
| deprecatedMessage?: MarkupBasicElement[]; | ||
| } | ||
@@ -353,3 +353,3 @@ /** | ||
| type: string; | ||
| description: IDocElement[]; | ||
| description: MarkupBasicElement[]; | ||
| } |
@@ -0,1 +1,2 @@ | ||
| import { IApiItemReference } from './api/ApiItem'; | ||
| /** | ||
@@ -122,3 +123,4 @@ * An API definition reference that is used to locate the documentation of exported | ||
| toMemberString(): string; | ||
| toApiItemReference(): IApiItemReference; | ||
| private constructor(); | ||
| } |
@@ -120,2 +120,10 @@ "use strict"; | ||
| } | ||
| toApiItemReference() { | ||
| return { | ||
| scopeName: this.scopeName, | ||
| packageName: this.packageName, | ||
| exportName: this.exportName, | ||
| memberName: this.memberName | ||
| }; | ||
| } | ||
| } | ||
@@ -122,0 +130,0 @@ /** |
| import * as ts from 'typescript'; | ||
| import { ExtractorContext } from '../ExtractorContext'; | ||
| import ApiDocumentation from '../aedoc/ApiDocumentation'; | ||
| import { IDocElement } from '../markup/OldMarkup'; | ||
| import { MarkupElement } from '../markup/MarkupElement'; | ||
| import { ReleaseTag } from '../aedoc/ReleaseTag'; | ||
@@ -182,3 +182,3 @@ import AstItemContainer from './AstItemContainer'; | ||
| */ | ||
| inheritedDeprecatedMessage: IDocElement[]; | ||
| inheritedDeprecatedMessage: MarkupElement[]; | ||
| /** | ||
@@ -185,0 +185,0 @@ * The ExtractorContext object provides common contextual information for all of |
@@ -11,3 +11,3 @@ "use strict"; | ||
| const TypeScriptHelpers_1 = require("../TypeScriptHelpers"); | ||
| const DocElementParser_1 = require("../DocElementParser"); | ||
| const Markup_1 = require("../markup/Markup"); | ||
| const ApiDefinitionReference_1 = require("../ApiDefinitionReference"); | ||
@@ -322,3 +322,3 @@ /** | ||
| // TODO: this.visitTypeReferencesForNode(this); | ||
| const summaryTextCondensed = DocElementParser_1.default.getAsText(this.documentation.summary, this.reportError).replace(/\s\s/g, ' '); | ||
| const summaryTextCondensed = Markup_1.Markup.extractTextContent(this.documentation.summary).replace(/\s\s/g, ' '); | ||
| this.needsDocumentation = this.shouldHaveDocumentation() && summaryTextCondensed.length <= 10; | ||
@@ -325,0 +325,0 @@ this.supportedName = (this.kind === AstItemKind.Package) || AstItem._allowedNameRegex.test(this.name); |
@@ -10,2 +10,3 @@ "use strict"; | ||
| const TypeScriptHelpers_1 = require("../TypeScriptHelpers"); | ||
| const Markup_1 = require("../markup/Markup"); | ||
| const ApiDefinitionReference_1 = require("../ApiDefinitionReference"); | ||
@@ -63,20 +64,12 @@ /** | ||
| if (this.documentation.summary.length === 0) { | ||
| this.documentation.summary.push({ | ||
| kind: 'textDocElement', | ||
| value: 'Constructs a new instance of the ' | ||
| }); | ||
| this.documentation.summary.push(...Markup_1.Markup.createTextElements('Constructs a new instance of the ')); | ||
| const scopedPackageName = ApiDefinitionReference_1.default | ||
| .parseScopedPackageName(this.context.package.name); | ||
| this.documentation.summary.push({ | ||
| kind: 'linkDocElement', | ||
| referenceType: 'code', | ||
| this.documentation.summary.push(Markup_1.Markup.createApiLinkFromText(this.parentContainer.name, { | ||
| scopeName: scopedPackageName.scope, | ||
| packageName: scopedPackageName.package, | ||
| exportName: this.parentContainer.name, | ||
| value: this.parentContainer.name | ||
| }); | ||
| this.documentation.summary.push({ | ||
| kind: 'textDocElement', | ||
| value: ' class' | ||
| }); | ||
| memberName: '' | ||
| })); | ||
| this.documentation.summary.push(...Markup_1.Markup.createTextElements(' class')); | ||
| } | ||
@@ -83,0 +76,0 @@ this.needsDocumentation = false; |
@@ -8,2 +8,3 @@ "use strict"; | ||
| const ReleaseTag_1 = require("../aedoc/ReleaseTag"); | ||
| const Markup_1 = require("../markup/Markup"); | ||
| const AstMethod_1 = require("./AstMethod"); | ||
@@ -136,9 +137,4 @@ const AstProperty_1 = require("./AstProperty"); | ||
| // Add a boilerplate notice for classes with internal constructors | ||
| this.documentation.remarks.unshift({ | ||
| kind: 'textDocElement', | ||
| value: `The constructor for this class is marked as internal. Third-party code` | ||
| + ` should not extend subclasses of the ${this.name} class or instantiate it directly.` | ||
| }, { | ||
| kind: 'paragraphDocElement' | ||
| }); | ||
| this.documentation.remarks.unshift(...Markup_1.Markup.createTextElements(`The constructor for this class is marked as internal. Third-party code` | ||
| + ` should not call the constructor directly or create subclasses that extend the ${this.name} class.`), Markup_1.Markup.PARAGRAPH); | ||
| } | ||
@@ -145,0 +141,0 @@ } |
@@ -1,2 +0,2 @@ | ||
| import { IDocElement, IHrefLinkElement, ICodeLinkElement } from './markup/OldMarkup'; | ||
| import { MarkupBasicElement } from './markup/MarkupElement'; | ||
| import ApiDocumentation from './aedoc/ApiDocumentation'; | ||
@@ -27,8 +27,7 @@ import Token from './aedoc/Token'; | ||
| private static _hrefRegEx; | ||
| static getAsText(collection: IDocElement[], reportError: (message: string) => void): string; | ||
| static makeTextElement(text: string): IDocElement; | ||
| static parse(documentation: ApiDocumentation, tokenizer: Tokenizer): IDocElement[]; | ||
| static parse(documentation: ApiDocumentation, tokenizer: Tokenizer): MarkupBasicElement[]; | ||
| static parseAndNormalize(documentation: ApiDocumentation, tokenizer: Tokenizer): MarkupBasicElement[]; | ||
| /** | ||
| * This method parses the semantic information in an \@link JSDoc tag, creates and returns a | ||
| * linkDocElement with the corresponding information. If the corresponding inline tag \@link is | ||
| * MarkupElement with the corresponding information. If the corresponding inline tag \@link is | ||
| * not formatted correctly an error will be reported. | ||
@@ -45,3 +44,3 @@ * | ||
| */ | ||
| static parseLinkTag(documentation: ApiDocumentation, tokenItem: Token): IHrefLinkElement | ICodeLinkElement; | ||
| static parseLinkTag(documentation: ApiDocumentation, tokenItem: Token): MarkupBasicElement; | ||
| /** | ||
@@ -56,8 +55,2 @@ * This method parses the semantic information in an \@inheritdoc JSDoc tag and sets | ||
| static parseInheritDoc(documentation: ApiDocumentation, token: Token, warnings: string[]): void; | ||
| /** | ||
| * For a span that will not be displayed adjacent to another span, this cleans it up: | ||
| * 1. Remove leading/trailing white space | ||
| * 2. Remove leading/trailing paragraph separators | ||
| */ | ||
| static getTrimmedSpan(docElements: IDocElement[]): IDocElement[]; | ||
| } |
@@ -5,2 +5,3 @@ "use strict"; | ||
| Object.defineProperty(exports, "__esModule", { value: true }); | ||
| const Markup_1 = require("./markup/Markup"); | ||
| const ApiDefinitionReference_1 = require("./ApiDefinitionReference"); | ||
@@ -10,36 +11,4 @@ const AstItem_1 = require("./ast/AstItem"); | ||
| class DocElementParser { | ||
| static getAsText(collection, reportError) { | ||
| let text = ''; | ||
| collection.forEach(docElement => { | ||
| switch (docElement.kind) { | ||
| case 'textDocElement': | ||
| text += `${docElement.value} `; | ||
| break; | ||
| case 'paragraphDocElement': | ||
| text += '\n\n'; | ||
| break; | ||
| case 'linkDocElement': | ||
| // links don't count towards the summary | ||
| break; | ||
| case 'seeDocElement': | ||
| // see doesn't count towards the summary | ||
| break; | ||
| default: | ||
| reportError('Unexpected item in IDocElement collection'); | ||
| break; | ||
| } | ||
| }); | ||
| return text.trim(); | ||
| } | ||
| static makeTextElement(text) { | ||
| if (!text) { | ||
| return; | ||
| } | ||
| return { | ||
| kind: 'textDocElement', | ||
| value: text.replace(/\s+/g, ' ') | ||
| }; | ||
| } | ||
| static parse(documentation, tokenizer) { | ||
| const docElements = []; | ||
| const markupElements = []; | ||
| let parsing = true; | ||
@@ -54,14 +23,3 @@ let token; | ||
| if (token.type === Token_1.TokenType.BlockTag) { | ||
| switch (token.tag) { | ||
| case '@see': | ||
| tokenizer.getToken(); | ||
| docElements.push({ | ||
| kind: 'seeDocElement', | ||
| seeElements: this.parse(documentation, tokenizer) | ||
| }); | ||
| break; | ||
| default: | ||
| parsing = false; // end of summary tokens | ||
| break; | ||
| } | ||
| parsing = false; // end of summary tokens | ||
| } | ||
@@ -72,3 +30,3 @@ else if (token.type === Token_1.TokenType.InlineTag) { | ||
| tokenizer.getToken(); | ||
| if (docElements.length > 0 || documentation.summary.length > 0) { | ||
| if (markupElements.length > 0 || documentation.summary.length > 0) { | ||
| documentation.reportError('A summary block is not allowed here,' | ||
@@ -81,8 +39,8 @@ + ' because the @inheritdoc target provides the summary'); | ||
| case '@link': | ||
| const linkDocElement = this.parseLinkTag(documentation, token); | ||
| if (linkDocElement) { | ||
| // Push to docElements to retain position in the documentation | ||
| docElements.push(linkDocElement); | ||
| if (linkDocElement.referenceType === 'code') { | ||
| documentation.incompleteLinks.push(linkDocElement); | ||
| const linkMarkupElement = this.parseLinkTag(documentation, token); | ||
| if (linkMarkupElement) { | ||
| // Push to linkMarkupElement to retain position in the documentation | ||
| markupElements.push(linkMarkupElement); | ||
| if (linkMarkupElement.kind === 'api-link') { | ||
| documentation.incompleteLinks.push(linkMarkupElement); | ||
| } | ||
@@ -99,18 +57,3 @@ } | ||
| tokenizer.getToken(); | ||
| let firstLoop = true; | ||
| for (const paragraph of token.text.split(/\n\s*\n/g)) { | ||
| if (!firstLoop) { | ||
| docElements.push({ | ||
| kind: 'paragraphDocElement' | ||
| }); | ||
| } | ||
| firstLoop = false; | ||
| const normalizedParagraph = paragraph.replace(/\s+/g, ' ').trim(); | ||
| if (normalizedParagraph) { | ||
| docElements.push({ | ||
| kind: 'textDocElement', | ||
| value: ' ' + normalizedParagraph + ' ' | ||
| }); | ||
| } | ||
| } | ||
| markupElements.push(...Markup_1.Markup.createTextParagraphs(token.text)); | ||
| } | ||
@@ -121,7 +64,12 @@ else { | ||
| } | ||
| return docElements; | ||
| return markupElements; | ||
| } | ||
| static parseAndNormalize(documentation, tokenizer) { | ||
| const markupElements = DocElementParser.parse(documentation, tokenizer); | ||
| Markup_1.Markup.normalize(markupElements); | ||
| return markupElements; | ||
| } | ||
| /** | ||
| * This method parses the semantic information in an \@link JSDoc tag, creates and returns a | ||
| * linkDocElement with the corresponding information. If the corresponding inline tag \@link is | ||
| * MarkupElement with the corresponding information. If the corresponding inline tag \@link is | ||
| * not formatted correctly an error will be reported. | ||
@@ -155,4 +103,20 @@ * | ||
| const displayTextPart = pipeSplitContent.length > 1 ? pipeSplitContent[1] : ''; | ||
| let displayTextElements; | ||
| // If a display name is given, ensure it only contains characters for words. | ||
| if (displayTextPart) { | ||
| const match = this._displayTextBadCharacterRegEx.exec(displayTextPart); | ||
| if (match) { | ||
| documentation.reportError(`The {@link} tag\'s display text contains an unsupported` | ||
| + ` character: "${match[0]}"`); | ||
| return undefined; | ||
| } | ||
| // Full match is valid text | ||
| displayTextElements = Markup_1.Markup.createTextElements(displayTextPart); | ||
| } | ||
| else { | ||
| // If the display text is not explicitly provided, then use the address as the display text | ||
| displayTextElements = Markup_1.Markup.createTextElements(addressPart); | ||
| } | ||
| // Try to guess if the tokenContent is a link or API definition reference | ||
| let linkDocElement; | ||
| let linkMarkupElement; | ||
| if (this._hrefRegEx.test(addressPart)) { | ||
@@ -165,8 +129,3 @@ // Make sure only a single URL is given | ||
| } | ||
| linkDocElement = { | ||
| kind: 'linkDocElement', | ||
| referenceType: 'href', | ||
| targetUrl: addressPart | ||
| // ("value" will be assigned below) | ||
| }; | ||
| linkMarkupElement = Markup_1.Markup.createWebLink(displayTextElements, addressPart); | ||
| } | ||
@@ -180,12 +139,4 @@ else { | ||
| } | ||
| linkDocElement = { | ||
| kind: 'linkDocElement', | ||
| referenceType: 'code', | ||
| scopeName: apiDefitionRef.scopeName, | ||
| packageName: apiDefitionRef.packageName, | ||
| exportName: apiDefitionRef.exportName, | ||
| memberName: apiDefitionRef.memberName | ||
| // ("value" will be assigned below) | ||
| }; | ||
| if (!linkDocElement.packageName) { | ||
| const normalizedApiLink = apiDefitionRef.toApiItemReference(); | ||
| if (!normalizedApiLink.packageName) { | ||
| if (!documentation.context.packageName) { | ||
@@ -196,22 +147,8 @@ throw new Error('Unable to resolve API reference without a package name'); | ||
| const scopePackageName = ApiDefinitionReference_1.default.parseScopedPackageName(documentation.context.packageName); | ||
| linkDocElement.scopeName = scopePackageName.scope; | ||
| linkDocElement.packageName = scopePackageName.package; | ||
| normalizedApiLink.scopeName = scopePackageName.scope; | ||
| normalizedApiLink.packageName = scopePackageName.package; | ||
| } | ||
| linkMarkupElement = Markup_1.Markup.createApiLink(displayTextElements, normalizedApiLink); | ||
| } | ||
| // If a display name is given, ensure it only contains characters for words. | ||
| if (displayTextPart) { | ||
| const match = this._displayTextBadCharacterRegEx.exec(displayTextPart); | ||
| if (match) { | ||
| documentation.reportError(`The {@link} tag\'s display text contains an unsupported` | ||
| + ` character: "${match[0]}"`); | ||
| return undefined; | ||
| } | ||
| // Full match is valid text | ||
| linkDocElement.value = displayTextPart; | ||
| } | ||
| else { | ||
| // If the display text is not explicitly provided, then use the address as the display text | ||
| linkDocElement.value = addressPart; | ||
| } | ||
| return linkDocElement; | ||
| return linkMarkupElement; | ||
| } | ||
@@ -247,5 +184,3 @@ /** | ||
| if (!resolvedAstItem) { | ||
| documentation.summary = [ | ||
| this.makeTextElement(`See documentation for ${tokenChunks[0]}`) | ||
| ]; | ||
| documentation.summary = Markup_1.Markup.createTextElements(`See documentation for ${tokenChunks[0]}`); | ||
| return; | ||
@@ -285,30 +220,2 @@ } | ||
| } | ||
| /** | ||
| * For a span that will not be displayed adjacent to another span, this cleans it up: | ||
| * 1. Remove leading/trailing white space | ||
| * 2. Remove leading/trailing paragraph separators | ||
| */ | ||
| static getTrimmedSpan(docElements) { | ||
| const span = []; | ||
| span.push(...docElements); | ||
| // Pop leading/trailing paragraph separators | ||
| while (span.length && span[0].kind === 'paragraphDocElement') { | ||
| span.shift(); | ||
| } | ||
| while (span.length && span[span.length - 1].kind === 'paragraphDocElement') { | ||
| span.pop(); | ||
| } | ||
| // Trim leading/trailing white space | ||
| if (span.length) { | ||
| const first = span[0]; | ||
| if (first.kind === 'textDocElement') { | ||
| first.value = first.value.replace(/^\s+/, ''); // trim left | ||
| } | ||
| const last = span[span.length - 1]; | ||
| if (last.kind === 'textDocElement') { | ||
| last.value = last.value.replace(/\s+$/, ''); // trim right | ||
| } | ||
| } | ||
| return span; | ||
| } | ||
| } | ||
@@ -315,0 +222,0 @@ /** |
@@ -8,2 +8,2 @@ export { default as ExternalApiHelper } from './ExternalApiHelper'; | ||
| export * from './markup/MarkupElement'; | ||
| export * from './markup/OldMarkup'; | ||
| export { Markup, IMarkupCreateTextOptions } from './markup/Markup'; |
@@ -11,3 +11,5 @@ "use strict"; | ||
| exports.ApiJsonFile = ApiJsonFile_1.ApiJsonFile; | ||
| var Markup_1 = require("./markup/Markup"); | ||
| exports.Markup = Markup_1.Markup; | ||
| //# sourceMappingURL=index.js.map |
@@ -5,5 +5,6 @@ import { IApiItemReference } from '../api/ApiItem'; | ||
| * | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export interface IMarkupText { | ||
| /** The kind of markup element */ | ||
| kind: 'text'; | ||
@@ -17,3 +18,9 @@ /** | ||
| text: string; | ||
| /** | ||
| * Whether the text should be formatted using boldface | ||
| */ | ||
| bold?: boolean; | ||
| /** | ||
| * Whether the text should be formatted using italics | ||
| */ | ||
| italics?: boolean; | ||
@@ -25,3 +32,3 @@ } | ||
| * | ||
| * @alpha | ||
| * @public | ||
| */ | ||
@@ -33,5 +40,6 @@ export declare type MarkupHighlighter = 'javascript' | 'plain'; | ||
| * NOTE: IMarkupHighlightedText is just a span of text, whereas IMarkupCodeBox is a box showing a larger code sample. | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export interface IMarkupHighlightedText { | ||
| /** The kind of markup element */ | ||
| kind: 'code'; | ||
@@ -45,33 +53,41 @@ /** | ||
| text: string; | ||
| /** Indicates the syntax highlighting that will be applied to this text */ | ||
| highlighter: MarkupHighlighter; | ||
| } | ||
| /** | ||
| * Represents markup that can be used as the text for a hyperlink. | ||
| * Represents markup that can be used as the link text for a hyperlink | ||
| * | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export declare type MarkupLinkTextElement = IMarkupText | IMarkupHighlightedText; | ||
| /** | ||
| * A block of plain text, possibly with simple formatting. | ||
| * @alpha | ||
| * A hyperlink to an API item | ||
| * @public | ||
| */ | ||
| export interface IMarkupApiLink { | ||
| /** The kind of markup element */ | ||
| kind: 'api-link'; | ||
| /** The link text */ | ||
| elements: MarkupLinkTextElement[]; | ||
| /** The API item that will serve as the hyperlink target */ | ||
| target: IApiItemReference; | ||
| } | ||
| /** | ||
| * A hyperlink to a web page. | ||
| * @alpha | ||
| * A hyperlink to an internet URL | ||
| * @public | ||
| */ | ||
| export interface IMarkupWebLink { | ||
| /** The kind of markup element */ | ||
| kind: 'web-link'; | ||
| /** The link text */ | ||
| elements: MarkupLinkTextElement[]; | ||
| /** The internet URL that will serve as the hyperlink target */ | ||
| targetUrl: string; | ||
| } | ||
| /** | ||
| * A paragraph separator, similar to the "<p>" tag in HTML. | ||
| * @alpha | ||
| * A paragraph separator, similar to the "<p>" tag in HTML | ||
| * @public | ||
| */ | ||
| export interface IMarkupParagraph { | ||
| /** The kind of markup element */ | ||
| kind: 'paragraph'; | ||
@@ -81,5 +97,6 @@ } | ||
| * A line break, similar to the "<br>" tag in HTML. | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export interface IMarkupLineBreak { | ||
| /** The kind of markup element */ | ||
| kind: 'break'; | ||
@@ -90,3 +107,3 @@ } | ||
| * | ||
| * @alpha | ||
| * @public | ||
| */ | ||
@@ -96,8 +113,9 @@ export declare type MarkupBasicElement = MarkupLinkTextElement | IMarkupApiLink | IMarkupWebLink | IMarkupParagraph | IMarkupLineBreak; | ||
| * A top-level heading | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export interface IMarkupHeading1 { | ||
| /** The kind of markup element */ | ||
| kind: 'heading1'; | ||
| /** | ||
| * The text for the heading. | ||
| * The heading title | ||
| * @remarks | ||
@@ -111,5 +129,6 @@ * Formatting such as bold/italics are not supported in headings. | ||
| * A sub heading | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export interface IMarkupHeading2 { | ||
| /** The kind of markup element */ | ||
| kind: 'heading2'; | ||
@@ -120,8 +139,9 @@ /** {@inheritdoc IMarkupHeading1.text} */ | ||
| /** | ||
| * A box containing source code with syntax highlighting. | ||
| * A box containing source code with syntax highlighting | ||
| * @remarks | ||
| * NOTE: IMarkupHighlightedText is just a span of text, whereas IMarkupCodeBox is a box showing a larger code sample. | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export interface IMarkupCodeBox { | ||
| /** The kind of markup element */ | ||
| kind: 'code-box'; | ||
@@ -133,6 +153,7 @@ /** {@inheritdoc IMarkupHighlightedText.text} */ | ||
| /** | ||
| * A call-out box containing an informational note. | ||
| * @alpha | ||
| * A call-out box containing an informational note | ||
| * @public | ||
| */ | ||
| export interface IMarkupNoteBox { | ||
| /** The kind of markup element */ | ||
| kind: 'note-box'; | ||
@@ -142,6 +163,7 @@ elements: MarkupBasicElement[]; | ||
| /** | ||
| * A table, with an optional header row. | ||
| * @alpha | ||
| * A table, with an optional header row | ||
| * @public | ||
| */ | ||
| export interface IMarkupTable { | ||
| /** The kind of markup element */ | ||
| kind: 'table'; | ||
@@ -155,20 +177,23 @@ header?: IMarkupTableRow; | ||
| * | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export declare type MarkupStructuredElement = MarkupBasicElement | IMarkupHeading1 | IMarkupHeading2 | IMarkupCodeBox | IMarkupNoteBox | IMarkupTable; | ||
| /** | ||
| * A cell inside an IMarkupTable object. | ||
| * A cell inside an IMarkupTableRow element. | ||
| * | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export interface IMarkupTableCell { | ||
| /** The kind of markup element */ | ||
| kind: 'table-cell'; | ||
| /** The text content for the table cell */ | ||
| elements: MarkupBasicElement[]; | ||
| } | ||
| /** | ||
| * A row inside an IMarkupTable object. | ||
| * A row inside an IMarkupTable element. | ||
| * | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export interface IMarkupTableRow { | ||
| /** The kind of markup element */ | ||
| kind: 'table-row'; | ||
@@ -180,5 +205,6 @@ cells: IMarkupTableCell[]; | ||
| * | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export interface IMarkupPage { | ||
| /** The kind of markup element */ | ||
| kind: 'page'; | ||
@@ -193,4 +219,4 @@ breadcrumb: MarkupBasicElement[]; | ||
| * | ||
| * @alpha | ||
| * @public | ||
| */ | ||
| export declare type MarkupElement = MarkupStructuredElement | IMarkupTableCell | IMarkupTableRow | IMarkupPage; |
| import AstItem, { AstItemKind } from './ast/AstItem'; | ||
| import { ReleaseTag } from './aedoc/ReleaseTag'; | ||
| import { IDocElement } from './markup/OldMarkup'; | ||
| import { MarkupElement, MarkupBasicElement } from './markup/MarkupElement'; | ||
| import { ApiItem } from './api/ApiItem'; | ||
@@ -12,5 +12,5 @@ import { IAedocParameter } from './aedoc/ApiDocumentation'; | ||
| kind: AstItemKind; | ||
| summary: IDocElement[]; | ||
| remarks: IDocElement[]; | ||
| deprecatedMessage: IDocElement[]; | ||
| summary: MarkupElement[]; | ||
| remarks: MarkupElement[]; | ||
| deprecatedMessage: MarkupBasicElement[]; | ||
| releaseTag: ReleaseTag; | ||
@@ -21,3 +21,3 @@ isBeta: boolean; | ||
| }; | ||
| returnsMessage: IDocElement[]; | ||
| returnsMessage: MarkupBasicElement[]; | ||
| /** | ||
@@ -24,0 +24,0 @@ * This property will either be an AstItem or undefined. |
| { | ||
| "name": "@microsoft/api-extractor", | ||
| "version": "4.1.2", | ||
| "version": "4.2.0", | ||
| "description": "Validate, document, and review the exported API for a TypeScript library", | ||
@@ -33,4 +33,4 @@ "keywords": [ | ||
| "dependencies": { | ||
| "@microsoft/node-core-library": "~0.3.9", | ||
| "@microsoft/ts-command-line": "~2.1.2", | ||
| "@microsoft/node-core-library": "~0.3.10", | ||
| "@microsoft/ts-command-line": "~2.1.3", | ||
| "@types/fs-extra": "0.0.37", | ||
@@ -37,0 +37,0 @@ "@types/node": "6.0.88", |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by5.48%
779185
- Lines of code
- increased by6.72%
9609