1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
return c > 3 && r && Object.defineProperty(target, key, r), r;
};
(function (factory) {
if (typeof module === "object" && typeof module.exports === "object") {
var v = factory(require, exports);
if (v !== undefined) module.exports = v;
}
else if (typeof define === "function" && define.amd) {
define(["require", "exports", "typedoc/dist/lib/converter/components", "typedoc/dist/lib/converter/converter", "./typedocVersionCompatibility", "./getRawComment"], factory);
}
})(function (require, exports) {
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const components_1 = require("typedoc/dist/lib/converter/components");
const converter_1 = require("typedoc/dist/lib/converter/converter");
const typedocVersionCompatibility_1 = require("./typedocVersionCompatibility");
const getRawComment_1 = require("./getRawComment");
/**
* This plugin allows an ES6 module to specify its TypeDoc name.
* It also allows multiple ES6 modules to be merged together into a single TypeDoc module.
*
* @usage
* At the top of an ES6 module, add a "dynamic module comment". Insert "@module typedocModuleName" to
* specify that this ES6 module should be merged with module: "typedocModuleName".
*
* Similar to the [[DynamicModulePlugin]], ensure that there is a comment tag (even blank) for the
* first symbol in the file.
*
* @example
* ```
*
* /**
* * @module newModuleName
* */
* /** for typedoc /
* import {foo} from "../foo";
* export let bar = "bar";
* ```
*
* Also similar to [[DynamicModulePlugin]], if @preferred is found in a dynamic module comment, the comment
* will be used as the module comment, and documentation will be generated from it (note: this plugin does not
* attempt to count lengths of merged module comments in order to guess the best one)
*/
let ExternalModuleNamePlugin = class ExternalModuleNamePlugin extends components_1.ConverterComponent {
initialize() {
this.listenTo(this.owner, {
[converter_1.Converter.EVENT_BEGIN]: this.onBegin,
[converter_1.Converter.EVENT_CREATE_DECLARATION]: this.onDeclaration,
[converter_1.Converter.EVENT_RESOLVE_BEGIN]: this.onBeginResolve,
});
}
/**
* Triggered when the converter begins converting a project.
*
* @param context The context object describing the current state the converter is in.
*/
onBegin(context) {
this.moduleRenames = [];
}
/**
* Triggered when the converter has created a declaration reflection.
*
* @param context The context object describing the current state the converter is in.
* @param reflection The reflection that is currently processed.
* @param node The node that is currently processed if available.
*/
onDeclaration(context, reflection, node) {
if (typedocVersionCompatibility_1.isModuleOrNamespace(reflection)) {
let comment = getRawComment_1.getRawComment(node);
// Look for @module
let match = /@module\s+([\w\u4e00-\u9fa5\.\-_/@"]+)/.exec(comment);
if (match) {
// Look for @preferred
let preferred = /@preferred/.exec(comment);
// Set up a list of renames operations to perform when the resolve phase starts
this.moduleRenames.push({
renameTo: match[1],
preferred: preferred != null,
symbol: node.symbol,
reflection: reflection,
});
}
}
if (reflection.comment) {
typedocVersionCompatibility_1.removeTags(reflection.comment, 'module');
typedocVersionCompatibility_1.removeTags(reflection.comment, 'preferred');
if (isEmptyComment(reflection.comment)) {
delete reflection.comment;
}
}
}
/**
* Triggered when the converter begins resolving a project.
*
* @param context The context object describing the current state the converter is in.
*/
onBeginResolve(context) {
let projRefs = context.project.reflections;
let refsArray = Object.keys(projRefs).reduce((m, k) => {
m.push(projRefs[k]);
return m;
}, []);
// Process each rename
this.moduleRenames.forEach((item) => {
let renaming = item.reflection;
// Find or create the module tree until the child's parent (each level is separated by .)
let nameParts = item.renameTo.split('.');
let parent = context.project;
for (let i = 0; i < nameParts.length - 1; ++i) {
let child = parent.children.filter((ref) => ref.name === nameParts[i])[0];
if (!child) {
child = typedocVersionCompatibility_1.createChildReflection(parent, nameParts[i]);
child.parent = parent;
child.children = [];
context.project.reflections[child.id] = child;
parent.children.push(child);
}
parent = child;
}
// Find an existing module with the child's name in the last parent. Use it as the merge target.
let mergeTarget = (parent.children.filter((ref) => ref.kind === renaming.kind && ref.name === nameParts[nameParts.length - 1])[0]);
// If there wasn't a merge target, change the name of the current module, connect it to the right parent and exit.
if (!mergeTarget) {
renaming.name = nameParts[nameParts.length - 1];
let oldParent = renaming.parent;
for (let i = 0; i < oldParent.children.length; ++i) {
if (oldParent.children[i] === renaming) {
oldParent.children.splice(i, 1);
break;
}
}
item.reflection.parent = parent;
parent.children.push(renaming);
typedocVersionCompatibility_1.updateSymbolMapping(context, item.symbol, parent);
return;
}
typedocVersionCompatibility_1.updateSymbolMapping(context, item.symbol, mergeTarget);
if (!mergeTarget.children) {
mergeTarget.children = [];
}
// Since there is a merge target, relocate all the renaming module's children to the mergeTarget.
let childrenOfRenamed = refsArray.filter((ref) => ref.parent === renaming);
childrenOfRenamed.forEach((ref) => {
// update links in both directions
ref.parent = mergeTarget;
mergeTarget.children.push(ref);
});
// If @preferred was found on the current item, update the mergeTarget's comment
// with comment from the renaming module
if (item.preferred)
mergeTarget.comment = renaming.comment;
// Now that all the children have been relocated to the mergeTarget, delete the empty module
// Make sure the module being renamed doesn't have children, or they will be deleted
if (renaming.children)
renaming.children.length = 0;
typedocVersionCompatibility_1.removeReflection(context.project, renaming);
// Remove @module and @preferred from the comment, if found.
if (mergeTarget.comment) {
typedocVersionCompatibility_1.removeTags(mergeTarget.comment, 'module');
typedocVersionCompatibility_1.removeTags(mergeTarget.comment, 'preferred');
}
if (isEmptyComment(mergeTarget.comment)) {
delete mergeTarget.comment;
}
});
}
};
ExternalModuleNamePlugin = __decorate([
components_1.Component({ name: 'external-module-name' })
], ExternalModuleNamePlugin);
exports.ExternalModuleNamePlugin = ExternalModuleNamePlugin;
function isEmptyComment(comment) {
return !comment || (!comment.text && !comment.shortText && (!comment.tags || comment.tags.length === 0));
}
});
|
