type2docfx
Version:
A tool to convert json format output from TypeDoc to schema driven reference model for DocFx to consume.
406 lines (405 loc) • 17.4 kB
JavaScript
"use strict";
var __assign = (this && this.__assign) || function () {
__assign = Object.assign || function(t) {
for (var s, i = 1, n = arguments.length; i < n; i++) {
s = arguments[i];
for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
t[p] = s[p];
}
return t;
};
return __assign.apply(this, arguments);
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.AbstractConverter = void 0;
var idResolver_1 = require("../idResolver");
var linkConvertHelper_1 = require("../helpers/linkConvertHelper");
var AbstractConverter = /** @class */ (function () {
function AbstractConverter(references) {
this.references = references;
}
AbstractConverter.prototype.convert = function (node, context) {
var _this = this;
var models = this.generate(node, context) || [];
models.forEach(function (model, i) {
model.summary = linkConvertHelper_1.convertLinkToGfm(model.summary);
model.package = context.PackageName;
if (node.comment || (node.signatures && node.signatures.length && node.signatures[i].comment)) {
_this.setCustomModuleName(model, node.comment);
var comment = node.comment ? node.comment : node.signatures[i].comment;
_this.setDeprecated(model, comment);
_this.setPreviewState(model, comment);
_this.setRemarks(model, comment);
_this.setInherits(model, comment);
}
});
return models;
};
AbstractConverter.prototype.setDeprecated = function (model, comment) {
var deprecated = this.extractTextFromComment('deprecated', comment);
if (deprecated != null) {
model.deprecated = {
content: linkConvertHelper_1.convertLinkToGfm(deprecated)
};
}
};
AbstractConverter.prototype.setPreviewState = function (model, comment) {
if (comment && comment.tags) {
for (var _i = 0, _a = comment.tags; _i < _a.length; _i++) {
var tag = _a[_i];
if (tag.tag === 'alpha') {
model.previewState = 'alpha';
break; // select 'alpha' if both 'alpha' and 'beta' tags are present.
}
else if (tag.tag === 'beta') {
model.previewState = 'beta';
}
}
}
};
AbstractConverter.prototype.setRemarks = function (model, comment) {
var remarks = this.extractTextFromComment('remarks', comment);
if (remarks != null) {
model.remarks = linkConvertHelper_1.convertLinkToGfm(remarks);
}
};
AbstractConverter.prototype.setCustomModuleName = function (model, comment) {
var customModuleName = this.extractTextFromComment('module', comment);
if (customModuleName) {
model.module = customModuleName;
}
};
AbstractConverter.prototype.setInherits = function (model, comment) {
var inherits = this.extractTextFromComment('inherits', comment);
if (inherits != null) {
var tokens = linkConvertHelper_1.getTextAndLink(inherits);
if (tokens.length === 2) {
model.extends = {
name: tokens[0],
href: tokens[1]
};
}
}
};
AbstractConverter.prototype.extractTextFromComment = function (infoName, comment) {
if (comment && comment.tags) {
for (var _i = 0, _a = comment.tags; _i < _a.length; _i++) {
var tag = _a[_i];
if (tag.tag === infoName) {
return tag.text.trim();
}
}
}
return null;
};
AbstractConverter.prototype.getGenericType = function (typeParameters) {
if (typeParameters && typeParameters.length) {
var typeArgumentsList = typeParameters.map(function (item) {
return item.name;
}).join(', ');
return '<' + typeArgumentsList + '>';
}
return '';
};
AbstractConverter.prototype.findDescriptionInComment = function (comment) {
if (!comment) {
return '';
}
var descText = this.parseDescTextFromComment(comment);
var tagText = this.extractTagsTextFromComment(comment);
return "" + descText + tagText;
};
AbstractConverter.prototype.parseDescTextFromComment = function (comment) {
if (comment.tags) {
var text_1 = null;
comment.tags.forEach(function (tag) {
if (tag.tag === 'classdesc'
|| tag.tag === 'description'
|| tag.tag === 'exemptedapi'
|| tag.tag === 'property') {
text_1 = tag.text.trim();
return;
}
});
if (text_1) {
return text_1.trim();
}
}
if (comment.shortText && comment.text) {
return comment.shortText + "\n" + comment.text;
}
if (comment.text) {
return comment.text.trim();
}
if (comment.shortText) {
return comment.shortText.trim();
}
return '';
};
AbstractConverter.prototype.extractTagsTextFromComment = function (comment) {
if (comment && comment.tags) {
return comment.tags.map(function (tag) {
if (tag.tag === 'see') {
return "\n\nSee " + tag.text.trim();
}
else if (tag.tag === 'example') {
return "\n\n**Example**\n\n" + tag.text.trim() + "\n\n";
}
else {
return '';
}
}).join('');
}
return '';
};
AbstractConverter.prototype.extractType = function (type) {
var _this = this;
var result = [];
if (type === undefined) {
return result;
}
if (type.type === 'union' && type.types && type.types.length) {
if (this.hasCommonPrefix(type.types)) {
result.push({
typeName: type.types[0].name.split('.')[0]
});
}
else {
result.push({
unionType: {
types: type.types.map(function (t) {
var childType = _this.extractType(t)[0];
childType.parentType = type.type;
return childType;
})
}
});
}
}
else if (type.type === 'array') {
var newType = this.extractType(type.elementType);
result.push({
arrayType: __assign(__assign({}, newType[0]), { parentType: type.type })
});
}
else if (type.type === 'intersection' && type.types.length) {
result.push({
intersectionType: {
types: type.types.map(function (t) {
var childType = _this.extractType(t)[0];
childType.parentType = type.type;
return childType;
})
}
});
}
else if (type.type === 'reflection' && type.declaration) {
if (type.declaration.indexSignature) {
var signatures = type.declaration.indexSignature;
signatures.forEach(function (signature) {
result.push({
reflectedType: {
key: {
typeName: signature.parameters[0].type.name,
typeId: signature.parameters[0].type.id
},
value: {
typeName: signature.type.name,
typeId: signature.type.id
}
}
});
});
}
else if (type.declaration.signatures && type.declaration.signatures.length) {
result.push({
typeName: this.generateCallFunction('', this.fillParameters(type.declaration.signatures[0].parameters)) + " => " + idResolver_1.typeToString(this.extractType(type.declaration.signatures[0].type)[0])
});
}
else if (type.declaration.children && type.declaration.children.length) {
result.push({
typeName: this.parseUserDefinedType(type)
});
}
else {
result.push({
typeName: 'Object'
});
}
}
else if (type.typeArguments && type.typeArguments.length) {
result.push({
genericType: {
outter: {
typeName: type.name,
typeId: type.id
},
inner: type.typeArguments.map(function (t) { return _this.extractType(t)[0]; })
}
});
}
else if (type.type === 'tuple' && type.elements && type.elements.length) {
result.push({
tupleType: {
types: type.elements.map(function (t) { return _this.extractType(t)[0]; })
}
});
}
else if (type.name) {
result.push({
typeName: type.name,
typeId: type.id
});
}
else if (type.value) {
result.push({
typeName: "\"" + type.value + "\""
});
}
else {
result.push({
typeName: 'Object'
});
}
return result;
};
AbstractConverter.prototype.hasCommonPrefix = function (types) {
if (types && types.length > 1 && types[0].name) {
if (types[0].name.indexOf('.') < 0) {
return false;
}
var prefix_1 = types[0].name.split('.')[0];
return types.find(function (t) { return !t.name || t.name.split('.')[0] !== prefix_1; }) === undefined;
}
return false;
};
AbstractConverter.prototype.generateCallFunction = function (prefix, parameters, typeParameters) {
if (parameters) {
return "" + prefix + this.getGenericType(typeParameters) + "(" + parameters.map(function (p) { return "" + p.id + (p.optional ? '?' : '') + ": " + (idResolver_1.typeToString(p.type[0])); }).join(', ') + ")";
}
return '';
};
AbstractConverter.prototype.fillParameters = function (parameters) {
var _this = this;
if (parameters) {
return parameters.map(function (p) {
var description = '';
if (p.comment) {
description = (p.comment.shortText && p.comment.shortText !== '') ? p.comment.shortText : p.comment.text;
}
return {
id: p.name,
type: _this.extractType(p.type),
description: linkConvertHelper_1.convertLinkToGfm(description),
optional: Boolean(p.flags && p.flags.isOptional)
};
});
}
return [];
};
AbstractConverter.prototype.extractReturnComment = function (comment) {
if (comment == null || comment.returns == null) {
return '';
}
return linkConvertHelper_1.convertLinkToGfm(comment.returns.trim());
};
AbstractConverter.prototype.extractInformationFromSignature = function (method, node, signatureIndex) {
if (node.signatures[signatureIndex].comment) {
method.summary = this.findDescriptionInComment(node.signatures[signatureIndex].comment);
}
method.syntax.parameters = this.fillParameters(node.signatures[signatureIndex].parameters);
if (node.signatures[signatureIndex].type && node.kindString !== 'Constructor' && node.signatures[signatureIndex].type.name !== 'void') {
method.syntax.return = {
type: this.extractType(node.signatures[signatureIndex].type),
description: this.extractReturnComment(node.signatures[signatureIndex].comment)
};
}
// comment the exception handling for now as template doesn't support it, so CI will not be blocked.
/*
let exceptions;
if (node.signatures[signatureIndex].comment && node.signatures[signatureIndex].comment.tags) {
exceptions = node.signatures[signatureIndex].comment.tags.filter(tag => tag.tag === 'throws');
}
if (exceptions && exceptions.length) {
method.exceptions = exceptions.map(e => extractException(e));
}
*/
if (node.kindString === 'Method' || node.kindString === 'Function') {
var typeParameter = node.signatures[signatureIndex].typeParameter;
var functionBody = this.generateCallFunction(method.name, method.syntax.parameters, typeParameter);
var returnBody = (method.syntax.return && method.syntax.return.type.length > 0) ? ": " + idResolver_1.typeToString(method.syntax.return.type[0]) : '';
method.syntax.content = (node.flags && node.flags.isStatic ? 'static ' : '') + "function " + functionBody + returnBody;
method.type = node.kindString.toLowerCase();
if (node.inheritedFrom) {
method.inherited = true;
method.inheritanceDescription = this.generateInheritanceDescription(node.inheritedFrom);
}
}
else {
method.name = method.uid.split('.').reverse()[1];
var functionBody = this.generateCallFunction(method.name, method.syntax.parameters);
method.syntax.content = "new " + functionBody;
method.type = 'constructor';
}
};
AbstractConverter.prototype.composeMethodNameFromSignature = function (method, typeParameters) {
var parameterType = method.syntax.parameters.map(function (p) {
return idResolver_1.typeToString(p.type[0]);
}).join(', ');
return method.name + this.getGenericType(typeParameters) + '(' + parameterType + ')';
};
AbstractConverter.prototype.parseTypeArgumentsForTypeAlias = function (node) {
var typeParameter;
if (node.typeParameter) {
typeParameter = node.typeParameter;
}
else if (node.typeArguments) {
typeParameter = node.typeArguments;
}
return this.getGenericType(typeParameter);
};
AbstractConverter.prototype.parseTypeDeclarationForTypeAlias = function (typeInfo) {
return idResolver_1.typeToString(this.extractType(typeInfo)[0]);
};
AbstractConverter.prototype.parseFunctionType = function (typeInfo) {
var typeResult = this.extractType(typeInfo);
var content = '';
if (typeResult.length) {
content = typeResult[0].typeName;
}
return content;
};
AbstractConverter.prototype.parseUserDefinedType = function (typeInfo) {
var _this = this;
if (!typeInfo.declaration || !typeInfo.declaration.children) {
return '';
}
var content = typeInfo.declaration.children.map(function (child) {
var type = '';
var isOptional = child.flags && child.flags.isOptional ? '?' : '';
if (child.kindString === 'Variable') {
type = "" + child.name + isOptional + ": " + idResolver_1.typeToString(_this.extractType(child.type)[0]);
}
else if (child.kindString === 'Function') {
type = _this.generateCallFunction("" + child.name + isOptional, _this.fillParameters(child.signatures[0].parameters)) + " => " + idResolver_1.typeToString(_this.extractType(child.signatures[0].type)[0]);
}
return type;
}).join(', ');
content = '{ ' + content + ' }';
return content;
};
AbstractConverter.prototype.generateInheritanceDescription = function (inheritedFrom) {
if (inheritedFrom) {
if (inheritedFrom.id) {
return "<b>Inherited From</b> [" + inheritedFrom.name + "](xref:" + inheritedFrom.name + ")";
}
else {
return "<b>Inherited From</b> " + inheritedFrom.name;
}
}
return null;
};
return AbstractConverter;
}());
exports.AbstractConverter = AbstractConverter;
//# sourceMappingURL=base.js.map