Mirrors/overte
3
0
Fork 0
mirror of https://github.com/overte-org/overte.git synced 2025-04-05 21:12:25 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge d86c065699 into b38237cb8d

Browse source
This commit is contained in:
UnTamedStArBlOb 2025-04-03 17:26:24 +00:00 committed by GitHub
commit 81a4855147
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
41 changed files with 2145 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
libraries/avatars-renderer/src/avatars-renderer/Avatar.h
View file

@ -565,7 +565,7 @@ signals:
* restrictions on permissible scale values imposed by the domain.
* @function MyAvatar.targetScaleChanged
* @param {number} targetScale - The avatar's target scale.
* @returns Signal
* @returns {*} Signal
*/
void targetScaleChanged(float targetScale);

14
libraries/avatars/src/AvatarData.cpp
View file

@ -2857,14 +2857,24 @@ glm::mat4 AvatarData::getControllerRightHandMatrix() const {
* @property {boolean} intersects - <code>true</code> if an avatar is intersected, <code>false</code> if it isn't.
* @property {string} avatarID - The ID of the avatar that is intersected.
* @property {number} distance - The distance from the ray origin to the intersection.
* @property {string} face - The name of the box face that is intersected; <code>"UNKNOWN_FACE"</code> if mesh was picked
* against.
* @property {string} face - The name of the box face that is intersected; <code>"UNKNOWN_FACE"</code> if mesh was picked against.
* @property {Vec3} intersection - The ray intersection point in world coordinates.
* @property {Vec3} surfaceNormal - The surface normal at the intersection point.
* @property {number} jointIndex - The index of the joint intersected.
* @property {SubmeshIntersection} extraInfo - Extra information on the mesh intersected if mesh was picked against,
* <code>{}</code> if it wasn't.
*/
/*@jsdoc
* Information about a parabola-to-avatar intersection.
* @typedef {Object} ParabolaToAvatarIntersectionParameters
* @property {PickParabola} pick - The pick used for the intersection calculation.
* @property {Uuid[]} avatarsToInclude - List of avatars to include in the intersection check.
* @property {Uuid[]} avatarsToDiscard - List of avatars to exclude from the intersection check.
*
* @typedef {RayToAvatarIntersectionResult} ParabolaToAvatarIntersectionResult
*/
ScriptValue RayToAvatarIntersectionResultToScriptValue(ScriptEngine* engine, const RayToAvatarIntersectionResult& value) {
ScriptValue obj = engine->newObject();
obj.setProperty("intersects", value.intersects);

4
libraries/controllers/src/controllers/impl/MappingBuilderProxy.h
View file

@ -116,9 +116,9 @@ class UserInputMapper;
* A filter in a {@link Controller.MappingJSONRoute}.
* @typedef {object} Controller.MappingJSONFilter
* @property {string} type - The name of the filter, being the name of the one of the {@link RouteObject}'s filter methods.
* @property {string} [?] - If the filter method has a first parameter, the property name is the name of that parameter and the
* @property {string} [_1] - If the filter method has a first parameter, the property name is the name of that parameter and the
* property value is the value to use.
* @property {string} [?] - If the filter method has a second parameter, the property name is the name of that parameter and
* @property {string} [_2] - If the filter method has a second parameter, the property name is the name of that parameter and
* the property value is the value to use.
* @example <caption>A hysteresis filter.</caption>
* {

4
libraries/controllers/src/controllers/impl/RouteBuilderProxy.h
View file

@ -71,7 +71,7 @@ class RouteBuilderProxy : public QObject {
* routes using the same input are processed.
* <p>This is a QML-specific version of {@link MappingObject#when|when}: use this version in QML files.</p>
* @function RouteObject#whenQml
* @param {condition|condition[]} expression - <p>A <code>condition</code> may be a:</p>
* @param { boolean | boolean[] | number | number[] } expression - <p>A <code>condition</code> may be a:</p>
* <ul>
* <li>A boolean or numeric {@link Controller.Hardware} property, which is evaluated as a boolean.</li>
* <li><code>!</code> followed by a {@link Controller.Hardware} property, indicating the logical NOT should be
@ -165,7 +165,7 @@ class RouteBuilderProxy : public QObject {
* the input is read only if the condition is <code>true</code>. Thus, if the condition is not met then subsequent
* routes using the same input are processed.
* @function RouteObject#when
* @param {condition|condition[]} expression - <p>A <code>condition</code> may be a:</p>
* @param { boolean | boolean[] | number | number[] } expression - <p>A <code>condition</code> may be a:</p>
* <ul>
* <li>A numeric {@link Controller.Hardware} property, which is evaluated as a boolean.</li>
* <li><code>!</code> followed by a {@link Controller.Hardware} property to use the logical NOT of the property

2
libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.h
View file

@ -48,7 +48,7 @@ public slots:
* Gets a handle to the model data used for displaying an avatar, 3D entity, or 3D overlay.
* <p>Note: The model data may be used for more than one instance of the item displayed in the scene.</p>
* @function Graphics.getModel
* @param {UUID} id - The ID of the avatar, 3D entity, or 3D overlay.
* @param {Uuid} id - The ID of the avatar, 3D entity, or 3D overlay.
* @returns {GraphicsModel} The model data for the avatar, entity, or overlay, as displayed. This includes the results of
* applying any {@link Entities.EntityProperties-Material|Material} entities to the item.
* @example <caption>Report some details of your avatar's model.</caption>

2
libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.cpp
View file

@ -261,7 +261,7 @@ bool scriptable::ScriptableMesh::setVertexProperty(glm::uint32 vertexIndex, cons
/*@jsdoc
* Called for each vertex when {@link GraphicsMesh.updateVertexAttributes} is called.
* @callback GraphicsMesh~forEachVertextCallback
* @callback GraphicsMesh~forEachVertexCallback
* @param {Object<Graphics.BufferTypeName, Graphics.BufferType>} attributes - The attributes of the vertex.
* @param {number} index - The vertex index.
* @param {object} properties - The properties of the mesh, per {@link GraphicsMesh}.

8
libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h
View file

@ -116,7 +116,7 @@ namespace scriptable {
/*@jsdoc
* Gets the value of an attribute for all vertices in the <em>whole</em> mesh (i.e., parent and mesh parts).
* @function GraphicsMeshPArt.queryVertexAttributes
* @function GraphicsMeshPart.queryVertexAttributes
* @param {Graphics.BufferTypeName} name - The name of the attribute to get the vertex values of.
* @throws Throws an error if the <code>name</code> is invalid or isn't used in the mesh.
* @returns {Graphics.BufferType[]} The attribute values for all vertices.
@ -230,7 +230,7 @@ namespace scriptable {
/*@jsdoc
* Removes an attribute from all vertices in the <em>whole</em> mesh (i.e., parent and mesh parts).
* <p>Note: The <code>"position"</code> attribute cannot be removed.</p>
* @function GraphicsMeshPArt.removeAttribute
* @function GraphicsMeshPart.removeAttribute
* @param {Graphics.BufferTypeName} name - The name of the attribute to remove.
* @returns {boolean} <code>true</code> if the attribute existed and was removed, <code>false</code> otherwise.
*/
@ -255,7 +255,7 @@ namespace scriptable {
/*@jsdoc
* Replaces a mesh part with a copy of another mesh part.
* @function GraphicsMeshPart.replaceMeshPartData
* @param {GrphicsMeshPart} source - The mesh part to copy.
* @param {GraphicsMeshPart} source - The mesh part to copy.
* @param {Graphics.BufferTypeName[]} [attributes] - The attributes to copy. If not specified, all attributes are
* copied from the source.
* @throws Throws an error if the mesh part of source mesh part aren't valid.
@ -291,7 +291,7 @@ namespace scriptable {
/*@jsdoc
* Calls a function for each vertex in the <em>whole</em> mesh (i.e., parent and mesh parts).
* @function GraphicsMeshPArt.forEachVertex
* @function GraphicsMeshPart.forEachVertex
* @param {GraphicsMesh~forEachVertexCallback} callback - The function to call for each vertex.
* @returns {number} The number of vertices the callback was called for.
*/

4
libraries/midi/src/Midi.h
View file

@ -143,8 +143,8 @@ public slots:
/*@jsdoc
* Unblocks a MIDI device's input or output.
* @function Midi.unblockMidiDevice
* @param {string} name- The name of the MIDI device to unblock.
* @param {boolean} output - <code>true</code> to unblock the device's output, <code>false</code> to unblock its input.
* @param {string} name - The name of the MIDI device to unblock.
* @param {boolean} output - <code>true</code> to unblock the device's output, <code>false</code> to unblock its input.
*/
Q_INVOKABLE void unblockMidiDevice(QString name, bool output);

5
libraries/networking/src/AssetClient.cpp
View file

@ -132,7 +132,8 @@ MiniPromise::Promise AssetClient::cacheInfoRequestAsync(MiniPromise::Promise def
* @property {object} [rawHeaders] - The raw headers that are set in the meta data. <em>Not used.</em>
* @property {boolean} [saveToDisk] - <code>true</code> if the cache item is allowed to be store on disk,
* <code>false</code> if it isn't.
* @property {string} [url|metaDataURL] - The ATP URL of the cached item.
* @property {string} [url] - The ATP URL of the cached item.
* @property {string} [metaDataURL] - The ATP URL of the cached item.
*/
MiniPromise::Promise AssetClient::queryCacheMetaAsync(const QUrl& url, MiniPromise::Promise deferred) {
if (QThread::currentThread() != thread()) {
@ -235,7 +236,7 @@ namespace {
* @typedef {object} Assets.SaveToCacheHeaders
* @property {string} [expires] - The date and time the cache value expires, in the format:
* <code>"ddd, dd MMM yyyy HH:mm:ss"</code>. The default value is an invalid date, representing "never expires".
* @property {string} [last-modified] - The date and time the cache value was last modified, in the format:
* @property {string} ["last-modified"] - The date and time the cache value was last modified, in the format:
* <code>"ddd, dd MMM yyyy HH:mm:ss"</code>. The default value is the current date and time.
*/
/*@jsdoc

6
libraries/physics/src/ObjectDynamic.cpp
View file

@ -106,14 +106,14 @@ bool ObjectDynamic::updateArguments(QVariantMap arguments) {
* <code>0</code> means that the action should not be deleted.
* @property {boolean} isMine=true - <code>true</code> if the action was created during the current client session,
* <code>false</code> if it wasn't. <em>Read-only.</em>
* @property {boolean} ::no-motion-state - Is present with a value of <code>true</code> when the entity hasn't been registered
* @property {boolean} 'no-motion-state' - Is present with a value of <code>true</code> when the entity hasn't been registered
* with the physics engine yet (e.g., if the action hasn't been properly configured), otherwise the property is
* <code>undefined</code>. <em>Read-only.</em>
* @property {boolean} ::active - <code>true</code> when the action is modifying the entity's motion, <code>false</code>
* @property {boolean} 'active' - <code>true</code> when the action is modifying the entity's motion, <code>false</code>
* otherwise. Is present once the entity has been registered with the physics engine, otherwise the property is
* <code>undefined</code>.
* <em>Read-only.</em>
* @property {Entities.PhysicsMotionType} ::motion-type - How the entity moves with the action. Is present once the entity has
* @property {Entities.PhysicsMotionType} 'motion-type' - How the entity moves with the action. Is present once the entity has
* been registered with the physics engine, otherwise the property is <code>undefined</code>. <em>Read-only.</em>
*
* @comment The different action types have additional arguments as follows:

13
libraries/render-utils/src/GeometryCache.h
View file

@ -45,6 +45,19 @@ typedef QPair<Vec3Pair, Vec4Pair> Vec3PairVec4Pair;
typedef QPair<Vec4Pair, glm::vec4> Vec4PairVec4;
typedef QPair<Vec4Pair, Vec4Pair> Vec4PairVec4Pair;
/*@jsdoc
* **Note:** This is just scaffolding and has not been properly implemented.
* @typedef {Object} Vec3Pair
* @property {Vec3} first - The first 3D vector.
* @property {Vec3} second - The second 3D vector.
*
* @example <caption>Creating a pair of vec3 objects to represent two 3D vectors.</caption>
* const myVec3Pair = {
* first: new vec3(1.0, 0.0, 0.0), // First vector pointing along the X-axis
* second: new vec3(0.0, 1.0, 0.0) // Second vector pointing along the Y-axis
* };
*/
inline uint qHash(const Vec2FloatPairPair& v, uint seed) {
// multiply by prime numbers greater than the possible size
return qHash(v.first.first.x + 5009 * v.first.first.y + 5011 * v.first.second +

27
libraries/script-engine/src/AssetScriptingInterface.cpp
View file

@ -455,6 +455,33 @@ void AssetScriptingInterface::compressData(const ScriptValue& options, const Scr
* @property {string} [url] - The <code>atp:</code> URL of the content: using the path if specified, otherwise the hash.
* @property {string} [path] - The uploaded content's mapped path, if specified.
*/
/*@jsdoc
* Content and delete options for {@link Assets.deleteAsset}.
*
* **Note:** This is just scaffolding and has not been properly implemented yet.
*
* @typedef {Object} Assets.DeleteOptions
* @property {string | ArrayBuffer} data - The content to upload.
* @property {string} [path] - A user-friendly path for the file in the asset server. May have a leading `"atp:"`.
*
* If not specified, no path-to-hash mapping is set.
*
* **Warning:** The asset server destroys any unmapped SHA256-named file at server restart. Either set the mapping path
* with this property or use {@link Assets.setMapping} to set a path-to-hash mapping for the uploaded file.
*/
/*@jsdoc
* Result value returned by {@link Assets.putAsset}.
*
* **Note:** This is just scaffolding and has not been properly implemented yet.
*
* @typedef {Object} Assets.DeleteResult
* @property {number} [byteLength] - The number of bytes in the hash file stored on the asset server.
* @property {string} [contentType] - `"application/gzip"` if the content stored is gzip compressed.
* @property {string} [url] - The `atp:` URL of the content: using the path if specified, otherwise the hash.
* @property {string} [path] - The uploaded content's mapped path, if specified.
*/
void AssetScriptingInterface::putAsset(const ScriptValue& options, const ScriptValue& scope, const ScriptValue& callback) {
auto compress = options.property("compress").toBool() || options.property("compressed").toBool();
auto data = options.isObject() ? options.property("data") : options;

14
libraries/script-engine/src/ConsoleScriptingInterface.h
View file

@ -56,7 +56,7 @@ public:
* Logs an "INFO" message to the program log and triggers {@link Script.infoMessage}.
* The message logged is "INFO -" followed by the message values separated by spaces.
* @function console.info
* @param {...*} [message] - The message values to log.
* @param {*} [message] - The message values to log.
*/
static ScriptValue info(ScriptContext* context, ScriptEngine* engine);
@ -65,7 +65,7 @@ public:
* The message logged is the message values separated by spaces.
* <p>If a {@link console.group} is in effect, the message is indented by an amount proportional to the group level.</p>
* @function console.log
* @param {...*} [message] - The message values to log.
* @param {*} [message] - The message values to log.
* @example <caption>Log some values.</caption>
* Script.printedMessage.connect(function (message, scriptName) {
* console.info("Console.log message:", "\"" + message + "\"", "in", "[" + scriptName + "]");
@ -82,7 +82,7 @@ public:
* Logs a message to the program log and triggers {@link Script.printedMessage}.
* The message logged is the message values separated by spaces.
* @function console.debug
* @param {...*} [message] - The message values to log.
* @param {*} [message] - The message values to log.
*/
static ScriptValue debug(ScriptContext* context, ScriptEngine* engine);
@ -90,7 +90,7 @@ public:
* Logs a "WARNING" message to the program log and triggers {@link Script.warningMessage}.
* The message logged is "WARNING - " followed by the message values separated by spaces.
* @function console.warn
* @param {...*} [message] - The message values to log.
* @param {*} [message] - The message values to log.
*/
static ScriptValue warn(ScriptContext* context, ScriptEngine* engine);
@ -98,7 +98,7 @@ public:
* Logs an "ERROR" message to the program log and triggers {@link Script.errorMessage}.
* The message logged is "ERROR - " followed by the message values separated by spaces.
* @function console.error
* @param {...*} [message] - The message values to log.
* @param {*} [message] - The message values to log.
*/
static ScriptValue error(ScriptContext* context, ScriptEngine* engine);
@ -107,7 +107,7 @@ public:
* Logs an "ERROR" message to the program log and triggers {@link Script.errorMessage}.
* The message logged is "ERROR - " followed by the message values separated by spaces.
* @function console.exception
* @param {...*} [message] - The message values to log.
* @param {*} [message] - The message values to log.
*/
static ScriptValue exception(ScriptContext* context, ScriptEngine* engine);
@ -117,7 +117,7 @@ public:
* <p>Note: Script execution continues whether or not the test condition fails.</p>
* @function console.assert
* @param {boolean} assertion - The test condition value.
* @param {...*} [message] - The message values to log if the assertion evaluates to <code>false</code>.
* @param {*} [message] - The message values to log if the assertion evaluates to <code>false</code>.
* @example <caption>Demonstrate assertion behavior.</caption>
* Script.errorMessage.connect(function (message, scriptName) {
* console.info("Error message logged:", "\"" + message + "\"", "in", "[" + scriptName + "]");

2
libraries/script-engine/src/ScriptManager.cpp
View file

@ -782,7 +782,7 @@ void ScriptManager::init() {
* The message logged is the message values separated by spaces.
* <p>Alternatively, you can use {@link Script.print} or one of the {@link console} API methods.</p>
* @function print
* @param {...*} [message] - The message values to print.
* @param {*} [message] - The message values to print.
*/
scriptEngine->globalObject().setProperty("print", scriptEngine->newFunction(debugPrint));

2
libraries/script-engine/src/ScriptManager.h
View file

@ -580,7 +580,7 @@ public:
* @brief Registers a global object by name.
*
* @param valueName
* @param value
* @param string
*/
Q_INVOKABLE void registerValue(const QString& valueName, ScriptValue value);

8
libraries/script-engine/src/ScriptManagerScriptingInterface.h
View file

@ -162,7 +162,7 @@ public:
* registers a global object by name.
* @function Script.registerValue
* @param {string} valueName
* @param {value} value
* @param {*} value
*/
/// registers a global object by name
Q_INVOKABLE void registerValue(const QString& valueName, ScriptValue value) { _manager->registerValue(valueName, value); }
@ -547,8 +547,8 @@ public:
/*@jsdoc
* Create test object for garbage collector debugging.
* @function Script.createGarbageCollectorDebuggingObject()
* @Returns Test object.
* @function Script.createGarbageCollectorDebuggingObject
* @Returns {*} Test object.
*/
Q_INVOKABLE ScriptValue createGarbageCollectorDebuggingObject();
@ -800,7 +800,7 @@ protected:
/*@jsdoc
* @function Script.executeOnScriptThread
* @param {function} function - Function.
* @param {ConnectionType} [type=2] - Connection type.
* @param {*} [type=2] - Connection type.
* @deprecated This function is deprecated and will be removed.
*/
// V8TODO: Nothing seems to be using this, and it generates:

4
libraries/shared/src/DebugDraw.h
View file

@ -95,7 +95,7 @@ public:
* @param {Quat} rotation - The orientation of the marker in world coordinates.
* @param {Vec3} position - The position of the market in world coordinates.
* @param {Vec4} color - The color of the marker.
* @param {float} size - A float between 0.0 and 1.0 (10 cm) to control the size of the marker.
* @param {number} size - A float between 0.0 and 1.0 (10 cm) to control the size of the marker.
* @example <caption>Briefly draw a debug marker in front of your avatar, in world coordinates.</caption>
* var MARKER_NAME = "my marker";
* DebugDraw.addMarker(
@ -128,7 +128,7 @@ public:
* @param {Quat} rotation - The orientation of the marker in avatar coordinates.
* @param {Vec3} position - The position of the market in avatar coordinates.
* @param {Vec4} color - color of the marker.
* @param {float} size - A float between 0.0 and 1.0 (10 cm) to control the size of the marker.
* @param {number} size - A float between 0.0 and 1.0 (10 cm) to control the size of the marker.
* @example <caption>Briefly draw a debug marker in front of your avatar, in avatar coordinates.</caption>
* var MARKER_NAME = "My avatar marker";
* DebugDraw.addMyAvatarMarker(

2
libraries/ui/src/QmlFragmentClass.h
View file

@ -36,7 +36,7 @@ public:
/*@jsdoc
* Creates a new button, adds it to this and returns it.
* @function QmlFragmentClass#addButton
* @param properties {object} button properties
* @param {object} properties - button properties
* @returns {TabletButtonProxy}
*/
Q_INVOKABLE QObject* addButton(const QVariant& properties);

2
tools/jsdoc/CMakeLists.txt
View file

@ -10,12 +10,14 @@ set(JSDOC_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR})
file(TO_NATIVE_PATH ${JSDOC_WORKING_DIR}/node_modules/.bin/jsdoc JSDOC_PATH)
file(TO_NATIVE_PATH ${JSDOC_WORKING_DIR}/config.json JSDOC_CONFIG_PATH)
file(TO_NATIVE_PATH ${JSDOC_OUTPUT_DIR}/out OUTPUT_DIR)
file(TO_NATIVE_PATH ${OVERTE_TSD_JSDOC_DIR}/overte-tsd-jsdoc)
file(TO_NATIVE_PATH ${JSDOC_WORKING_DIR}/root.js NATIVE_JSDOC_WORKING_DIR)
set(JSDOC_OUTPUT_PATH ${OUTPUT_DIR} CACHE INTERNAL "${PROJECT_NAME}: JSDoc output directory")
add_custom_command(TARGET ${TARGET_NAME}
COMMAND ${NPM_EXECUTABLE} --no-progress install && ${JSDOC_PATH} ${NATIVE_JSDOC_WORKING_DIR} -c ${JSDOC_CONFIG_PATH} -d ${OUTPUT_DIR}
COMMAND ${NPM_EXECUTABLE} --no-progress install && ${JSDOC_PATH} ${NATIVE_JSDOC_WORKING_DIR} -t ${OVERTE_TSD_JSDOC_DIR} -c ${JSDOC_CONFIG_PATH} -d ${OUTPUT_DIR}
WORKING_DIRECTORY ${JSDOC_WORKING_DIR}
COMMENT "generate the JSDoc JSON"
)

3
tools/jsdoc/overte-tsd-jsdoc/Dictionary.js Normal file
View file

@ -0,0 +1,3 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
//# sourceMappingURL=Dictionary.js.map

1
tools/jsdoc/overte-tsd-jsdoc/Dictionary.js.map Normal file
View file

@ -0,0 +1 @@
{"version":3,"file":"Dictionary.js","sourceRoot":"","sources":["../src/Dictionary.ts"],"names":[],"mappings":""}

681
tools/jsdoc/overte-tsd-jsdoc/Emitter.js Normal file
View file

@ -0,0 +1,681 @@
"use strict";
var __importStar = (this && this.__importStar) || function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k in mod) if (Object.hasOwnProperty.call(mod, k)) result[k] = mod[k];
result["default"] = mod;
return result;
};
Object.defineProperty(exports, "__esModule", { value: true });
const ts = __importStar(require("typescript"));
const logger_1 = require("./logger");
const assert_never_1 = require("./assert_never");
const doclet_utils_1 = require("./doclet_utils");
const create_helpers_1 = require("./create_helpers");
const type_resolve_helpers_1 = require("./type_resolve_helpers");
function shouldMoveOutOfClass(doclet) {
return doclet_utils_1.isClassDoclet(doclet)
|| doclet_utils_1.isNamespaceDoclet(doclet)
|| doclet_utils_1.isEnumDoclet(doclet)
|| doclet.kind === 'typedef';
}
class Emitter {
constructor(options) {
this.options = options;
this.results = [];
this._treeRoots = [];
this._treeNodes = {};
}
parse(docs) {
logger_1.debug(`Emitter.parse()`);
this.results = [];
this._treeRoots = [];
this._treeNodes = {};
if (!docs)
return;
this._createTreeNodes(docs);
this._buildTree(docs);
if (this.options.generationStrategy === 'exported')
this._markExported();
this._parseTree();
}
emit() {
console.log(`----------------------------------------------------------------`);
console.log(`Emitter.emit()`);
const resultFile = ts.createSourceFile('types.d.ts', '', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
const printer = ts.createPrinter({
removeComments: false,
newLine: ts.NewLineKind.LineFeed,
});
let out2 = '';
for (let i = 0; i < this.results.length; ++i) {
out2 += printer.printNode(ts.EmitHint.Unspecified, this.results[i], resultFile);
out2 += '\n\n';
}
return out2;
}
_createTreeNodes(docs) {
logger_1.debug(`----------------------------------------------------------------`);
logger_1.debug(`Emitter._createTreeNodes()`);
for (let i = 0; i < docs.length; ++i) {
const doclet = docs[i];
if (doclet.kind === 'package') {
logger_1.debug(`Emitter._createTreeNodes(): skipping ${logger_1.docletDebugInfo(doclet)} (package)`);
continue;
}
const node = this._treeNodes[doclet.longname];
if (!node) {
logger_1.debug(`Emitter._createTreeNodes(): adding ${logger_1.docletDebugInfo(doclet)} to this._treeNodes`);
this._treeNodes[doclet.longname] = { doclet, children: [] };
}
else {
logger_1.debug(`Emitter._createTreeNodes(): skipping ${logger_1.docletDebugInfo(doclet)} (doclet name already known)`);
}
}
}
_buildTree(docs) {
logger_1.debug(`----------------------------------------------------------------`);
logger_1.debug(`Emitter._buildTree()`);
for (let i = 0; i < docs.length; ++i) {
const doclet = docs[i];
this._buildTreeNode(docs, doclet);
}
}
_buildTreeNode(docs, doclet) {
if (doclet.kind === 'package') {
logger_1.debug(`Emitter._buildTreeNode(): skipping ${logger_1.docletDebugInfo(doclet)} (package)`);
return;
}
if (doclet_utils_1.isClassDoclet(doclet) && doclet_utils_1.isConstructorDoclet(doclet)) {
const ownerClass = this._getNodeFromLongname(doclet.longname, (node) => doclet_utils_1.isClassDeclarationDoclet(node.doclet));
if (!ownerClass) {
logger_1.warn(`Failed to find owner class of constructor '${doclet.longname}'.`, doclet);
return;
}
if (this._checkDuplicateChild(doclet, ownerClass, (child) => doclet_utils_1.isConstructorDoclet(child.doclet)))
return;
logger_1.debug(`Emitter._buildTreeNode(): adding constructor ${logger_1.docletDebugInfo(doclet)} to class declaration ${logger_1.docletDebugInfo(ownerClass.doclet)}`);
ownerClass.children.push({ doclet: doclet, children: [] });
if (!doclet_utils_1.hasParamsDoclet(doclet) && doclet_utils_1.isClassDoclet(ownerClass.doclet) && doclet_utils_1.hasParamsDoclet(ownerClass.doclet)) {
logger_1.debug(`Emitter._buildTreeNode(): inheriting 'params' from owner class ${logger_1.docletDebugInfo(ownerClass.doclet)} for undocumented constructor ${logger_1.docletDebugInfo(doclet)}`);
doclet.params = ownerClass.doclet.params;
}
return;
}
let interfaceMerge = null;
if (doclet.kind === 'class') {
const impls = doclet.implements || [];
const mixes = doclet.mixes || [];
const extras = impls.concat(mixes);
if (extras.length) {
const longname = this._getInterfaceKey(doclet.longname);
interfaceMerge = this._treeNodes[longname] = {
doclet: {
kind: 'interface',
name: doclet.name,
scope: doclet.scope,
longname: longname,
augments: extras,
memberof: doclet.memberof,
},
children: [],
};
logger_1.debug(`Emitter._buildTreeNode(): merge interface ${logger_1.docletDebugInfo(interfaceMerge.doclet)} created for ${logger_1.docletDebugInfo(doclet)}`);
}
}
let namespaceMerge = null;
if (doclet.kind === 'interface' || doclet.kind === 'mixin') {
const staticChildren = docs.filter(d => d.memberof === doclet.longname && d.scope === 'static');
if (staticChildren.length) {
const longname = this._getNamespaceKey(doclet.longname);
namespaceMerge = this._treeNodes[longname] = {
doclet: {
kind: 'namespace',
name: doclet.name,
scope: doclet.scope,
longname: longname,
memberof: doclet.memberof,
},
children: [],
};
logger_1.debug(`Emitter._buildTreeNode(): merge namespace ${logger_1.docletDebugInfo(namespaceMerge.doclet)} created for ${logger_1.docletDebugInfo(doclet)}`);
staticChildren.forEach(c => c.memberof = longname);
}
}
doclet_utils_1.isDefaultExportDoclet(doclet, this._treeNodes);
if (doclet.memberof) {
const parent = this._getNodeFromLongname(doclet.memberof, function (node) {
if (doclet.scope === 'instance')
return doclet_utils_1.isClassDoclet(node.doclet);
return true;
});
if (!parent) {
logger_1.warn(`Failed to find parent of doclet '${doclet.longname}' using memberof '${doclet.memberof}', this is likely due to invalid JSDoc.`, doclet);
return;
}
if (doclet_utils_1.isDefaultExportDoclet(doclet, this._treeNodes)) {
if (doclet.meta && doclet.meta.code.value && doclet.meta.code.value.startsWith('{')) {
logger_1.debug(`Emitter._buildTreeNode(): 'module.exports = {name: ... }' named export pattern doclet ${logger_1.docletDebugInfo(doclet)}: skipping doclet but scan the object members`);
const value = JSON.parse(doclet.meta.code.value);
for (const name in value) {
this._resolveDocletType(name, parent, function (namedExportNode) {
logger_1.debug(`Emitter._buildTreeNode(): tagging ${logger_1.docletDebugInfo(namedExportNode.doclet)} as a named export`);
namedExportNode.isNamedExport = true;
});
}
return;
}
else {
const thisEmitter = this;
if (this._checkDuplicateChild(doclet, parent, (child) => doclet_utils_1.isDefaultExportDoclet(child.doclet, thisEmitter._treeNodes)))
return;
logger_1.debug(`Emitter._buildTreeNode(): adding default export ${logger_1.docletDebugInfo(doclet)} to module ${logger_1.docletDebugInfo(parent.doclet)}`);
parent.children.push({ doclet: doclet, children: [] });
return;
}
}
if (doclet_utils_1.isExportsAssignmentDoclet(doclet, this._treeNodes)) {
logger_1.debug(`Emitter._buildTreeNode(): adding 'exports =' assignment ${logger_1.docletDebugInfo(doclet)} to module ${logger_1.docletDebugInfo(parent.doclet)}`);
parent.children.push({ doclet: doclet, children: [] });
return;
}
const obj = this._treeNodes[doclet.longname];
if (!obj) {
logger_1.warn('Failed to find doclet node when building tree, this is likely a bug.', doclet);
return;
}
const isParentClassLike = doclet_utils_1.isClassDoclet(parent.doclet);
if (isParentClassLike && shouldMoveOutOfClass(doclet)) {
logger_1.debug(`Emitter._buildTreeNode(): move out of class!`);
const mod = this._getOrCreateClassNamespace(parent);
if (interfaceMerge) {
logger_1.debug(`Emitter._buildTreeNode(): adding ${logger_1.docletDebugInfo(interfaceMerge.doclet)} to ${logger_1.docletDebugInfo(mod.doclet)}`);
mod.children.push(interfaceMerge);
}
if (namespaceMerge) {
logger_1.debug(`Emitter._buildTreeNode(): adding ${logger_1.docletDebugInfo(namespaceMerge.doclet)} to ${logger_1.docletDebugInfo(mod.doclet)}`);
mod.children.push(namespaceMerge);
}
logger_1.debug(`Emitter._buildTreeNode(): adding ${logger_1.docletDebugInfo(obj.doclet)} to ${logger_1.docletDebugInfo(mod.doclet)}`);
mod.children.push(obj);
}
else {
if (this._checkDuplicateChild(doclet, parent, function (child) {
if (child.doclet.kind !== doclet.kind)
return false;
if (child.doclet.longname === doclet.longname)
return true;
const shortname = doclet.name || '';
const optionalLongname = doclet.longname.slice(0, doclet.longname.length - shortname.length) + `[${shortname}]`;
if (child.doclet.longname === optionalLongname)
return true;
return false;
}))
return;
const isObjModuleLike = doclet_utils_1.isNamespaceDoclet(doclet);
const isParentModuleLike = doclet_utils_1.isNamespaceDoclet(parent.doclet);
if (isObjModuleLike && isParentModuleLike) {
logger_1.debug(`Emitter._buildTreeNode(): nested modules / namespaces!`);
obj.isNested = true;
}
const isParentEnum = doclet_utils_1.isEnumDoclet(parent.doclet);
if (!isParentEnum) {
if (interfaceMerge) {
logger_1.debug(`Emitter._buildTreeNode(): adding ${logger_1.docletDebugInfo(interfaceMerge.doclet)} to ${logger_1.docletDebugInfo(parent.doclet)}`);
parent.children.push(interfaceMerge);
}
if (namespaceMerge) {
logger_1.debug(`Emitter._buildTreeNode(): adding ${logger_1.docletDebugInfo(namespaceMerge.doclet)} to ${logger_1.docletDebugInfo(parent.doclet)}`);
parent.children.push(namespaceMerge);
}
logger_1.debug(`Emitter._buildTreeNode(): adding ${logger_1.docletDebugInfo(obj.doclet)} to ${logger_1.docletDebugInfo(parent.doclet)}`);
parent.children.push(obj);
}
}
}
else {
const obj = this._treeNodes[doclet.longname];
if (!obj) {
logger_1.warn('Failed to find doclet node when building tree, this is likely a bug.', doclet);
return;
}
if (interfaceMerge) {
logger_1.debug(`Emitter._buildTreeNode(): ${logger_1.docletDebugInfo(interfaceMerge.doclet)} detected as a root`);
this._treeRoots.push(interfaceMerge);
}
if (namespaceMerge) {
logger_1.debug(`Emitter._buildTreeNode(): ${logger_1.docletDebugInfo(namespaceMerge.doclet)} detected as a root`);
this._treeRoots.push(namespaceMerge);
}
logger_1.debug(`Emitter._buildTreeNode(): ${logger_1.docletDebugInfo(obj.doclet)} detected as a root`);
this._treeRoots.push(obj);
}
}
_checkDuplicateChild(doclet, parent, match) {
for (const child of parent.children) {
if (match(child)) {
if (!doclet_utils_1.isDocumentedDoclet(doclet)) {
logger_1.debug(`Emitter._checkConcurrentChild(): skipping undocumented ${logger_1.docletDebugInfo(doclet)} because ${logger_1.docletDebugInfo(child.doclet)} is already known in parent ${logger_1.docletDebugInfo(parent.doclet)}`);
}
else {
logger_1.debug(`Emitter._buildTreeNode(): replacing ${logger_1.docletDebugInfo(child.doclet)} with ${logger_1.docletDebugInfo(doclet)} in ${logger_1.docletDebugInfo(parent.doclet)}`);
child.doclet = doclet;
}
return true;
}
}
return false;
}
_markExported() {
logger_1.debug(`----------------------------------------------------------------`);
logger_1.debug(`Emitter._markExported()`);
this._markExportedNode = this._markExportedNode.bind(this);
for (let i = 0; i < this._treeRoots.length; i++) {
const node = this._treeRoots[i];
if (node.doclet.kind === 'module')
this._markExportedNode(node);
}
}
_markExportedNode(node, markThisNode = true) {
logger_1.debug(`Emitter._markExportedNode(${logger_1.docletDebugInfo(node.doclet)}, markThisNode=${markThisNode})`);
const doProcessNode = (node.isExported === undefined);
if (markThisNode)
node.isExported = true;
else if (!node.isExported)
node.isExported = false;
if (!doProcessNode)
return;
switch (node.doclet.kind) {
case 'class':
case 'interface':
case 'mixin':
this._markExportedParams(node, node.doclet.params);
if (node.doclet.augments)
for (const augment of node.doclet.augments)
this._resolveDocletType(augment, node, this._markExportedNode);
if (node.doclet.implements)
for (const implement of node.doclet.implements)
this._resolveDocletType(implement, node, this._markExportedNode);
if (node.doclet.mixes)
for (const mix of node.doclet.mixes)
this._resolveDocletType(mix, node, this._markExportedNode);
this._markExportedChildren(node);
break;
case 'file':
this._markExportedParams(node, node.doclet.params);
break;
case 'event':
this._markExportedParams(node, node.doclet.params);
break;
case 'callback':
case 'function':
if (node.doclet.this)
this._resolveDocletType(node.doclet.this, node, this._markExportedNode);
this._markExportedParams(node, node.doclet.params);
this._markExportedReturns(node, node.doclet.returns);
break;
case 'member':
case 'constant':
if (doclet_utils_1.isDefaultExportDoclet(node.doclet, this._treeNodes)) {
if (node.doclet.meta && node.doclet.meta.code.value) {
this._resolveDocletType(node.doclet.meta.code.value, node, this._markExportedNode);
}
}
else if (doclet_utils_1.isNamedExportDoclet(node.doclet, this._treeNodes)
&& node.doclet.meta && node.doclet.meta.code.value
&& (!doclet_utils_1.isEnumDoclet(node.doclet))) {
const thisEmitter = this;
this._resolveDocletType(node.doclet.meta.code.value, node, function (refNode) {
const markThisNode = node.doclet.meta && (node.doclet.meta.code.value === node.doclet.name);
thisEmitter._markExportedNode(refNode, markThisNode);
}, function (target) {
return (target !== node);
});
}
else {
this._markExportedTypes(node, node.doclet.type);
}
break;
case 'module':
for (const child of node.children) {
if (doclet_utils_1.isDefaultExportDoclet(child.doclet, this._treeNodes)
|| doclet_utils_1.isNamedExportDoclet(child.doclet, this._treeNodes)) {
this._markExportedNode(child);
}
}
break;
case 'namespace':
this._markExportedChildren(node);
break;
case 'typedef':
this._markExportedTypes(node, node.doclet.type);
this._markExportedParams(node, node.doclet.params);
this._markExportedReturns(node, node.doclet.returns);
break;
case 'signal':
break;
default:
return assert_never_1.assertNever(node.doclet);
}
}
_markExportedTypes(node, types) {
if (types) {
for (const typeName of types.names) {
this._resolveDocletType(typeName, node, this._markExportedNode);
}
}
}
_markExportedParams(node, params) {
if (params) {
for (const param of params) {
if (param.type) {
for (const paramType of param.type.names) {
this._resolveDocletType(paramType, node, this._markExportedNode);
}
}
}
}
}
_markExportedReturns(node, returns) {
if (returns) {
for (const ret of returns) {
for (const retType of ret.type.names) {
this._resolveDocletType(retType, node, this._markExportedNode);
}
}
}
}
_markExportedChildren(node) {
for (const child of node.children) {
this._markExportedNode(child);
}
}
_parseTree() {
logger_1.debug(`----------------------------------------------------------------`);
logger_1.debug(`Emitter._parseTree()`);
for (let i = 0; i < this._treeRoots.length; ++i) {
const node = this._parseTreeNode(this._treeRoots[i]);
if (node)
this.results.push(node);
}
}
_parseTreeNode(node, parent) {
if (this.options.generationStrategy === 'exported' && !node.isExported) {
logger_1.debug(`Emitter._parseTreeNode(${logger_1.docletDebugInfo(node.doclet)}): skipping doclet, not exported`);
return null;
}
if (!node.exportName
&& this._ignoreDoclet(node.doclet)) {
logger_1.debug(`Emitter._parseTreeNode(${logger_1.docletDebugInfo(node.doclet)}): skipping ignored doclet`);
return null;
}
logger_1.debug(`Emitter._parseTreeNode(${logger_1.docletDebugInfo(node.doclet)}, parent=${parent ? logger_1.docletDebugInfo(parent.doclet) : parent})`);
const children = [];
if (children) {
for (let i = 0; i < node.children.length; ++i) {
const childNode = this._parseTreeNode(node.children[i], node);
if (childNode)
children.push(childNode);
}
}
switch (node.doclet.kind) {
case 'class':
if (doclet_utils_1.isConstructorDoclet(node.doclet)) {
return create_helpers_1.createConstructor(node.doclet);
}
else {
return create_helpers_1.createClass(node.doclet, children, node.exportName);
}
case 'constant':
case 'member':
if (doclet_utils_1.isDefaultExportDoclet(node.doclet, this._treeNodes)
&& node.doclet.meta
&& node.doclet.meta.code.value) {
return create_helpers_1.createExportDefault(node.doclet, node.doclet.meta.code.value);
}
if (doclet_utils_1.isNamedExportDoclet(node.doclet, this._treeNodes)
&& node.doclet.meta
&& node.doclet.meta.code.value
&& !doclet_utils_1.isEnumDoclet(node.doclet)) {
if (node.doclet.meta.code.value !== node.doclet.name) {
const thisEmitter = this;
let tsRes = null;
this._resolveDocletType(node.doclet.meta.code.value, node, function (refNode) {
const namedRefNode = {
doclet: refNode.doclet,
children: refNode.children,
isNested: refNode.isNested,
isExported: true,
exportName: node.doclet.name
};
tsRes = thisEmitter._parseTreeNode(namedRefNode, parent);
});
return tsRes;
}
else {
logger_1.debug(`Emitter._parseTreeNode(): skipping named export with reference of the same name`);
return null;
}
}
if (doclet_utils_1.isExportsAssignmentDoclet(node.doclet, this._treeNodes)) {
logger_1.debug(`Emitter._parseTreeNode(): skipping 'exports =' assignment`);
return null;
}
if (node.doclet.isEnum)
return create_helpers_1.createEnum(node.doclet, node.exportName);
else if (parent && parent.doclet.kind === 'class')
return create_helpers_1.createClassMember(node.doclet);
else if (parent && parent.doclet.kind === 'interface')
return create_helpers_1.createInterfaceMember(node.doclet);
else
return create_helpers_1.createNamespaceMember(node.doclet, node.exportName);
case 'callback':
case 'function':
if (node.doclet.memberof) {
const parent = this._treeNodes[node.doclet.memberof];
if (parent && parent.doclet.kind === 'class')
return create_helpers_1.createClassMethod(node.doclet);
else if (parent && parent.doclet.kind === 'interface')
return create_helpers_1.createInterfaceMethod(node.doclet);
}
return create_helpers_1.createFunction(node.doclet, node.exportName);
case 'interface':
return create_helpers_1.createInterface(node.doclet, children, node.exportName);
case 'mixin':
return create_helpers_1.createInterface(node.doclet, children, node.exportName);
case 'module':
return create_helpers_1.createModule(node.doclet, !!node.isNested, children);
case 'namespace':
return create_helpers_1.createNamespace(node.doclet, !!node.isNested, children, node.exportName);
case 'typedef':
return create_helpers_1.createTypedef(node.doclet, children, node.exportName);
case 'file':
return null;
case 'event':
return null;
case 'signal':
return null;
default:
return assert_never_1.assertNever(node.doclet);
}
}
_ignoreDoclet(doclet) {
if (doclet.kind !== 'package' && doclet_utils_1.isConstructorDoclet(doclet)) {
return false;
}
let reason = undefined;
if (doclet.kind === 'package')
reason = 'package doclet';
else if (!!doclet.ignore)
reason = 'doclet with an ignore flag';
else if (!this.options.private && doclet.access === 'private')
reason = 'private access disabled';
else if (doclet.kind === 'function' && (doclet.override || doclet.overrides))
reason = 'overriding doclet';
if (reason
|| doclet.kind === 'package') {
logger_1.debug(`Emitter._ignoreDoclet(doclet=${logger_1.docletDebugInfo(doclet)}) => true (${reason})`);
return true;
}
if (doclet.access === undefined) {
return false;
}
const accessLevels = ["private", "package", "protected", "public"];
const ignored = accessLevels.indexOf(doclet.access.toString()) < accessLevels.indexOf(this.options.access || "package");
if (ignored) {
logger_1.debug(`Emitter._ignoreDoclet(doclet=${logger_1.docletDebugInfo(doclet)}) => true (low access level)`);
}
return ignored;
}
_getInterfaceKey(longname) {
return longname ? longname + '$$interface$helper' : '';
}
_getNamespaceKey(longname) {
return longname ? longname + '$$namespace$helper' : '';
}
_getOrCreateClassNamespace(obj) {
if (obj.doclet.kind === 'module' || obj.doclet.kind === 'namespace') {
return obj;
}
const namespaceKey = this._getNamespaceKey(obj.doclet.longname);
let mod = this._treeNodes[namespaceKey];
if (mod) {
return mod;
}
mod = this._treeNodes[namespaceKey] = {
doclet: {
kind: 'namespace',
name: obj.doclet.name,
scope: 'static',
longname: namespaceKey,
},
children: [],
};
if (obj.doclet.memberof) {
const parent = this._treeNodes[obj.doclet.memberof];
if (!parent) {
logger_1.warn(`Failed to find parent of doclet '${obj.doclet.longname}' using memberof '${obj.doclet.memberof}', this is likely due to invalid JSDoc.`, obj.doclet);
return mod;
}
let parentMod = this._getOrCreateClassNamespace(parent);
logger_1.debug(`Emitter._getOrCreateClassNamespace(): pushing ${logger_1.docletDebugInfo(mod.doclet)} as a child of ${logger_1.docletDebugInfo(parentMod.doclet)}`);
mod.doclet.memberof = parentMod.doclet.longname;
parentMod.children.push(mod);
}
else {
logger_1.debug(`Emitter._getOrCreateClassNamespace(): no memberof, pushing ${logger_1.docletDebugInfo(mod.doclet)} as a root`);
this._treeRoots.push(mod);
}
return mod;
}
_getNodeFromLongname(longname, filter) {
function _debug(msg) { }
const node = this._treeNodes[longname];
if (!node) {
_debug(`Emitter._getNodeFromLongname('${longname}') => null`);
logger_1.warn(`No such doclet '${longname}'`);
return null;
}
if (!filter || filter(node)) {
_debug(`Emitter._getNodeFromLongname('${longname}') => ${logger_1.docletDebugInfo(node.doclet)}`);
return node;
}
if (node.doclet.kind === 'module') {
for (const child of node.children) {
if (child.doclet.longname === longname && filter(child)) {
_debug(`Emitter._getNodeFromLongname('${longname}') => ${logger_1.docletDebugInfo(child.doclet)}`);
return child;
}
}
_debug(`Emitter._getNodeFromLongname('${longname}') => null`);
logger_1.warn(`No such doclet '${longname}' in module`);
return null;
}
else {
_debug(`Emitter._getNodeFromLongname('${longname}') => null`);
logger_1.warn(`Unexpected doclet for longname '${longname}`, node.doclet);
return null;
}
}
_resolveDocletType(typeName, currentNode, callback, filter) {
function _debug(msg) { }
_debug(`Emitter._resolveDocletType(typeName='${typeName}', currentNode=${logger_1.docletDebugInfo(currentNode.doclet)})`);
const tokens = type_resolve_helpers_1.generateTree(typeName);
if (!tokens) {
logger_1.warn(`Could not resolve type '${typeName}' in current node:`, currentNode.doclet);
return;
}
tokens.dump((msg) => _debug(`Emitter._resolveDocletType(): tokens = ${msg}`));
const thisEmitter = this;
tokens.walkTypes(function (token) {
_debug(`Emitter._resolveDocletType(): token = {name:${token.name}, type:${token.typeToString()}}`);
typeName = token.name;
if (typeName.match(/.*\[ *\].*/))
typeName = typeName.slice(0, typeName.indexOf('['));
_debug(`Emitter._resolveDocletType(): typeName = ${typeName}`);
switch (typeName) {
case 'void':
case 'null':
case 'string':
case 'String':
case 'boolean':
case 'Boolean':
case 'number':
case 'Number':
case 'function':
case 'Function':
case 'any':
case 'object':
case 'Object':
case '*':
case 'Array':
case 'Union':
case 'Promise':
case 'HTMLElement':
return;
}
let scope = currentNode.doclet.longname;
while (scope) {
_debug(`Emitter._resolveDocletType(): scope='${scope}'`);
const longnames = [
`${scope}.${typeName}`,
`${scope}~${typeName}`,
`${scope}~${typeName}$$interface$helper`,
`${scope}~${typeName}$$namespace$helper`,
];
let targetFound = false;
for (const longname of longnames) {
_debug(`Emitter._resolveDocletType(): trying longname '${longname}'...`);
const target = thisEmitter._treeNodes[longname];
if (target) {
if (filter && (!filter(target))) {
_debug(`Emitter._resolveDocletType(): filtered out ${logger_1.docletDebugInfo(target.doclet)}`);
}
else {
_debug(`Emitter._resolveDocletType(): found! ${logger_1.docletDebugInfo(target.doclet)}`);
callback(target);
targetFound = true;
}
}
}
if (targetFound) {
_debug(`Emitter._resolveDocletType(): done`);
return;
}
const scopeNode = thisEmitter._treeNodes[scope];
if (!scopeNode)
break;
for (const tsTypeParameterDeclaration of type_resolve_helpers_1.resolveTypeParameters(scopeNode.doclet)) {
if (tsTypeParameterDeclaration.name.text === typeName) {
_debug(`Emitter._resolveDocletType(): template found! in ${logger_1.docletDebugInfo(scopeNode.doclet)}`);
return;
}
}
scope = scopeNode.doclet.memberof;
}
logger_1.warn(`Could not resolve type '${typeName}' in current node:`, currentNode.doclet);
});
}
}
exports.Emitter = Emitter;
//# sourceMappingURL=Emitter.js.map

1
tools/jsdoc/overte-tsd-jsdoc/Emitter.js.map Normal file
View file

File diff suppressed because one or more lines are too long

21
tools/jsdoc/overte-tsd-jsdoc/LICENSE Normal file
View file

@ -0,0 +1,21 @@
The MIT License
Copyright (c) 2016 Chad Engler
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

50
tools/jsdoc/overte-tsd-jsdoc/PropTree.js Normal file
View file

@ -0,0 +1,50 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const logger_1 = require("./logger");
class PropTree {
constructor(props) {
this.roots = [];
this.nodes = {};
for (let i = 0; i < props.length; ++i) {
const prop = props[i];
if (!prop || !prop.name) {
logger_1.warn('Encountered a property with no name, this is likely due to invalid JSDoc. Skipping.');
continue;
}
const parts = prop.name.split('.');
this.nodes[prop.name] = {
prop,
name: parts[parts.length - 1],
children: [],
};
}
for (let i = 0; i < props.length; ++i) {
const prop = props[i];
if (!prop || !prop.name)
continue;
const parts = prop.name.split('.');
const obj = this.nodes[prop.name];
if (!obj) {
logger_1.warn('Failed to find dot-notation property in map. This is likely a bug.');
continue;
}
if (parts.length > 1) {
parts.pop();
let parentName = parts.join('.');
if (parentName.endsWith('[]')) {
parentName = parentName.substring(0, parentName.length - '[]'.length);
}
const parent = this.nodes[parentName];
if (!parent) {
continue;
}
parent.children.push(obj);
}
else {
this.roots.push(obj);
}
}
}
}
exports.PropTree = PropTree;
//# sourceMappingURL=PropTree.js.map

1
tools/jsdoc/overte-tsd-jsdoc/PropTree.js.map Normal file
View file

@ -0,0 +1 @@
{"version":3,"file":"PropTree.js","sourceRoot":"","sources":["../src/PropTree.ts"],"names":[],"mappings":";;AACA,qCAAgC;AAShC,MAAa,QAAQ;IAKjB,YAAY,KAAoB;QAHhC,UAAK,GAAgB,EAAE,CAAC;QACxB,UAAK,GAA0B,EAAE,CAAC;QAK9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,EACrC;YACI,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YAEtB,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EACvB;gBACI,aAAI,CAAC,qFAAqF,CAAC,CAAC;gBAC5F,SAAS;aACZ;YAED,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAEnC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBACpB,IAAI;gBACJ,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;gBAC7B,QAAQ,EAAE,EAAE;aACf,CAAC;SACL;QAGD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,EACrC;YACI,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YAEtB,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI;gBACnB,SAAS;YAEb,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAEnC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAElC,IAAI,CAAC,GAAG,EACR;gBACI,aAAI,CAAC,oEAAoE,CAAC,CAAC;gBAC3E,SAAS;aACZ;YAED,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EACpB;gBACI,KAAK,CAAC,GAAG,EAAE,CAAC;gBACZ,IAAI,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACjC,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAC7B;oBACI,UAAU,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;iBACzE;gBAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;gBAEtC,IAAI,CAAC,MAAM,EACX;oBAEI,SAAS;iBACZ;gBAED,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;aAC7B;iBAED;gBACI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;aACvB;SACJ;IACL,CAAC;CACJ;AAtED,4BAsEC"}

7
tools/jsdoc/overte-tsd-jsdoc/assert_never.js Normal file
View file

@ -0,0 +1,7 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
function assertNever(x) {
throw new Error("Unexpected object: " + JSON.stringify(x));
}
exports.assertNever = assertNever;
//# sourceMappingURL=assert_never.js.map

1
tools/jsdoc/overte-tsd-jsdoc/assert_never.js.map Normal file
View file

@ -0,0 +1 @@
{"version":3,"file":"assert_never.js","sourceRoot":"","sources":["../src/assert_never.ts"],"names":[],"mappings":";;AAAA,SAAgB,WAAW,CAAC,CAAQ;IAEhC,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/D,CAAC;AAHD,kCAGC"}

390
tools/jsdoc/overte-tsd-jsdoc/create_helpers.js Normal file
View file

@ -0,0 +1,390 @@
"use strict";
var __importStar = (this && this.__importStar) || function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k in mod) if (Object.hasOwnProperty.call(mod, k)) result[k] = mod[k];
result["default"] = mod;
return result;
};
Object.defineProperty(exports, "__esModule", { value: true });
const ts = __importStar(require("typescript"));
const logger_1 = require("./logger");
const doclet_utils_1 = require("./doclet_utils");
const PropTree_1 = require("./PropTree");
const type_resolve_helpers_1 = require("./type_resolve_helpers");
const declareModifier = ts.createModifier(ts.SyntaxKind.DeclareKeyword);
const constModifier = ts.createModifier(ts.SyntaxKind.ConstKeyword);
const readonlyModifier = ts.createModifier(ts.SyntaxKind.ReadonlyKeyword);
const exportModifier = ts.createModifier(ts.SyntaxKind.ExportKeyword);
const defaultModifier = ts.createModifier(ts.SyntaxKind.DefaultKeyword);
function validateClassLikeChildren(children, validate, msg) {
if (children) {
for (let i = children.length - 1; i >= 0; --i) {
const child = children[i];
if (!validate(child)) {
logger_1.warn(`Encountered child that is not a ${msg}, this is likely due to invalid JSDoc.`, child);
children.splice(i, 1);
}
}
}
}
function validateClassChildren(children) {
validateClassLikeChildren(children, ts.isClassElement, 'ClassElement');
}
function validateInterfaceChildren(children) {
validateClassLikeChildren(children, ts.isTypeElement, 'TypeElement');
}
function validateModuleChildren(children) {
if (children) {
for (let i = children.length - 1; i >= 0; --i) {
const child = children[i];
if (!ts.isClassDeclaration(child)
&& !ts.isInterfaceDeclaration(child)
&& !ts.isFunctionDeclaration(child)
&& !ts.isEnumDeclaration(child)
&& !ts.isModuleDeclaration(child)
&& !ts.isTypeAliasDeclaration(child)
&& !ts.isVariableStatement(child)
&& !ts.isExportAssignment(child)) {
logger_1.warn('Encountered child that is not a supported declaration, this is likely due to invalid JSDoc.', child);
children.splice(i, 1);
}
}
}
}
function buildName(doclet, altName) {
if (altName)
return ts.createIdentifier(altName);
if (doclet.name.startsWith('exports.'))
return ts.createIdentifier(doclet.name.replace('exports.', ''));
return ts.createIdentifier(doclet.name);
}
function buildOptionalName(doclet, altName) {
if (altName)
return ts.createIdentifier(altName);
if (doclet.meta && (doclet.meta.code.name === 'module.exports'))
return undefined;
if (doclet.name.startsWith('exports.'))
return ts.createIdentifier(doclet.name.replace('exports.', ''));
return ts.createIdentifier(doclet.name);
}
function formatMultilineComment(comment) {
return comment.split('\n').join('\n * ');
}
function handlePropsComment(props, jsdocTagName) {
return props.map((prop) => {
if (prop.description) {
let name;
if (prop.optional) {
if (prop.defaultvalue !== undefined) {
name = `[${prop.name} = ${prop.defaultvalue}]`;
}
else {
name = `[${prop.name}]`;
}
}
else {
name = prop.name;
}
const description = ` - ${formatMultilineComment(prop.description)}`;
return `\n * @${jsdocTagName} ${name}${description}`;
}
return '';
}).filter((value) => value !== '').join('');
}
function handleReturnsComment(doclet) {
if (doclet_utils_1.isFunctionDoclet(doclet) && doclet.returns) {
return doclet.returns.map((ret) => {
if (ret.description)
return `\n * @returns ${formatMultilineComment(ret.description)}`;
return '';
})
.filter((value) => value !== '').join('');
}
return '';
}
function handleExamplesComment(doclet) {
if (doclet.examples !== undefined) {
return doclet.examples.map((example) => {
return `\n * @example
* ${formatMultilineComment(example)}`;
})
.join('');
}
return '';
}
function handleParamsComment(doclet) {
if ((doclet_utils_1.isClassDoclet(doclet)
|| doclet_utils_1.isFileDoclet(doclet)
|| doclet_utils_1.isEventDoclet(doclet)
|| doclet_utils_1.isFunctionDoclet(doclet)
|| doclet_utils_1.isTypedefDoclet(doclet))
&& doclet.params) {
return handlePropsComment(doclet.params, 'param');
}
return '';
}
function handlePropertiesComment(doclet) {
if (!doclet_utils_1.isEnumDoclet(doclet) && doclet.properties) {
return handlePropsComment(doclet.properties, 'property');
}
return '';
}
function handleComment(doclet, node) {
if (doclet.comment && doclet.comment.length > 4) {
let description = '';
if (doclet.description) {
description = `\n * ${formatMultilineComment(doclet.description)}`;
}
else if (doclet_utils_1.isClassDoclet(doclet) && doclet.classdesc) {
if (!ts.isConstructorDeclaration(node)) {
description = `\n * ${formatMultilineComment(doclet.classdesc)}`;
}
}
const examples = handleExamplesComment(doclet);
const properties = handlePropertiesComment(doclet);
const params = handleParamsComment(doclet);
const returns = handleReturnsComment(doclet);
if (doclet_utils_1.isEnumDoclet(doclet)) {
if (!ts.isEnumDeclaration(node)) {
logger_1.warn(`Node is not an enum declaration, even though the doclet is. This is likely a tsd-jsdoc bug.`);
return node;
}
if (doclet.properties) {
const enumProperties = doclet.properties;
const enumMembers = node.members;
for (let index = 0; index < enumProperties.length; index++) {
const enumProperty = enumProperties[index];
const enumMember = enumMembers[index];
handleComment(enumProperty, enumMember);
}
}
}
if (description || examples || properties || params || returns) {
let comment = `*${description}${examples}${properties}${params}${returns}
`;
if (doclet.kind === 'typedef') {
comment = `*${description}${examples}${params}${returns}
`;
}
const kind = ts.SyntaxKind.MultiLineCommentTrivia;
ts.addSyntheticLeadingComment(node, kind, comment, true);
}
}
return node;
}
function createClass(doclet, children, altName) {
logger_1.debug(`createClass(${logger_1.docletDebugInfo(doclet)}, altName=${altName})`);
validateClassChildren(children);
const mods = [];
if (!doclet.memberof)
mods.push(declareModifier);
if (doclet.meta && doclet.meta.code.name === 'module.exports')
mods.push(exportModifier, defaultModifier);
const members = children || [];
const typeParams = type_resolve_helpers_1.resolveTypeParameters(doclet);
const heritageClauses = type_resolve_helpers_1.resolveHeritageClauses(doclet, false);
if (doclet.params) {
if (members.filter(member => ts.isConstructorDeclaration(member)).length === 0) {
logger_1.debug(`createClass(): no constructor set yet, adding one automatically`);
members.unshift(ts.createConstructor(undefined, undefined, type_resolve_helpers_1.createFunctionParams(doclet), undefined));
}
}
if (doclet.properties) {
const tree = new PropTree_1.PropTree(doclet.properties);
nextProperty: for (let i = 0; i < tree.roots.length; ++i) {
const node = tree.roots[i];
for (const tsProp of members.filter(member => ts.isPropertyDeclaration(member))) {
if (tsProp.name) {
const propName = tsProp.name.text;
if (propName === node.name) {
logger_1.debug(`createClass(): skipping property already declared '${node.name}'`);
continue nextProperty;
}
}
}
const opt = node.prop.optional ? ts.createToken(ts.SyntaxKind.QuestionToken) : undefined;
const t = node.children.length ? type_resolve_helpers_1.createTypeLiteral(node.children, node) : type_resolve_helpers_1.resolveType(node.prop.type);
const property = ts.createProperty(undefined, undefined, node.name, opt, t, undefined);
if (node.prop.description) {
let comment = `*\n * ${node.prop.description.split(/\r\s*/).join("\n * ")}\n`;
ts.addSyntheticLeadingComment(property, ts.SyntaxKind.MultiLineCommentTrivia, comment, true);
}
members.push(property);
}
}
return handleComment(doclet, ts.createClassDeclaration(undefined, mods, buildOptionalName(doclet, altName), typeParams, heritageClauses, members));
}
exports.createClass = createClass;
function createInterface(doclet, children, altName) {
logger_1.debug(`createInterface(${logger_1.docletDebugInfo(doclet)}, altName=${altName})`);
validateInterfaceChildren(children);
const mods = doclet.memberof ? undefined : [declareModifier];
const members = children;
const typeParams = type_resolve_helpers_1.resolveTypeParameters(doclet);
const heritageClauses = type_resolve_helpers_1.resolveHeritageClauses(doclet, true);
return handleComment(doclet, ts.createInterfaceDeclaration(undefined, mods, buildName(doclet, altName), typeParams, heritageClauses, members));
}
exports.createInterface = createInterface;
function createFunction(doclet, altName) {
logger_1.debug(`createFunction(${logger_1.docletDebugInfo(doclet)}, altName=${altName})`);
const mods = [];
if (!doclet.memberof)
mods.push(declareModifier);
if (doclet.meta && (doclet.meta.code.name === 'module.exports'))
mods.push(exportModifier, defaultModifier);
const params = type_resolve_helpers_1.createFunctionParams(doclet);
const type = type_resolve_helpers_1.createFunctionReturnType(doclet);
const typeParams = type_resolve_helpers_1.resolveTypeParameters(doclet);
return handleComment(doclet, ts.createFunctionDeclaration(undefined, mods, undefined, buildOptionalName(doclet, altName), typeParams, params, type, undefined));
}
exports.createFunction = createFunction;
function createClassMethod(doclet) {
logger_1.debug(`createClassMethod(${logger_1.docletDebugInfo(doclet)})`);
const mods = [];
const params = type_resolve_helpers_1.createFunctionParams(doclet);
const type = type_resolve_helpers_1.createFunctionReturnType(doclet);
const typeParams = type_resolve_helpers_1.resolveTypeParameters(doclet);
if (!doclet.memberof)
mods.push(declareModifier);
if (doclet.access === 'private')
mods.push(ts.createModifier(ts.SyntaxKind.PrivateKeyword));
else if (doclet.access === 'protected')
mods.push(ts.createModifier(ts.SyntaxKind.ProtectedKeyword));
else if (doclet.access === 'public')
mods.push(ts.createModifier(ts.SyntaxKind.PublicKeyword));
if (doclet.scope === 'static')
mods.push(ts.createModifier(ts.SyntaxKind.StaticKeyword));
const [name, questionToken] = type_resolve_helpers_1.resolveOptionalFromName(doclet);
return handleComment(doclet, ts.createMethod(undefined, mods, undefined, name, questionToken, typeParams, params, type, undefined));
}
exports.createClassMethod = createClassMethod;
function createInterfaceMethod(doclet) {
logger_1.debug(`createInterfaceMethod(${logger_1.docletDebugInfo(doclet)})`);
const mods = [];
const params = type_resolve_helpers_1.createFunctionParams(doclet);
const type = type_resolve_helpers_1.createFunctionReturnType(doclet);
const typeParams = type_resolve_helpers_1.resolveTypeParameters(doclet);
const [name, questionToken] = type_resolve_helpers_1.resolveOptionalFromName(doclet);
return handleComment(doclet, ts.createMethodSignature(typeParams, params, type, name, questionToken));
}
exports.createInterfaceMethod = createInterfaceMethod;
function createEnum(doclet, altName) {
logger_1.debug(`createEnum(${logger_1.docletDebugInfo(doclet)}, altName=${altName})`);
const mods = [];
const props = [];
if (!doclet.memberof)
mods.push(declareModifier);
if (doclet.kind === 'constant')
mods.push(constModifier);
if (doclet.properties && doclet.properties.length) {
for (let i = 0; i < doclet.properties.length; ++i) {
const p = doclet.properties[i];
const l = p.defaultvalue !== undefined ? ts.createLiteral(p.defaultvalue) : undefined;
props.push(ts.createEnumMember(p.name, l));
}
}
return handleComment(doclet, ts.createEnumDeclaration(undefined, mods, buildName(doclet, altName), props));
}
exports.createEnum = createEnum;
function createClassMember(doclet) {
logger_1.debug(`createClassMember(${logger_1.docletDebugInfo(doclet)})`);
const type = type_resolve_helpers_1.resolveType(doclet.type, doclet);
const mods = getAccessModifiers(doclet);
if (doclet.scope === 'static')
mods.push(ts.createModifier(ts.SyntaxKind.StaticKeyword));
if (doclet.kind === 'constant' || doclet.readonly)
mods.push(readonlyModifier);
const [name, questionToken] = type_resolve_helpers_1.resolveOptionalFromName(doclet);
return handleComment(doclet, ts.createProperty(undefined, mods, name, questionToken, type, undefined));
}
exports.createClassMember = createClassMember;
function getAccessModifiers(doclet) {
const mods = [];
if (doclet.access === 'private' || doclet.access === 'package')
mods.push(ts.createModifier(ts.SyntaxKind.PrivateKeyword));
else if (doclet.access === 'protected')
mods.push(ts.createModifier(ts.SyntaxKind.ProtectedKeyword));
else if (doclet.access === 'public')
mods.push(ts.createModifier(ts.SyntaxKind.PublicKeyword));
return mods;
}
function createConstructor(doclet) {
logger_1.debug(`createConstructor(${logger_1.docletDebugInfo(doclet)})`);
return handleComment(doclet, ts.createConstructor(undefined, getAccessModifiers(doclet), type_resolve_helpers_1.createFunctionParams(doclet), undefined));
}
exports.createConstructor = createConstructor;
function createInterfaceMember(doclet) {
logger_1.debug(`createInterfaceMember(${logger_1.docletDebugInfo(doclet)})`);
const mods = [];
const type = type_resolve_helpers_1.resolveType(doclet.type, doclet);
if (doclet.kind === 'constant')
mods.push(readonlyModifier);
if (doclet.scope === 'static')
mods.push(ts.createModifier(ts.SyntaxKind.StaticKeyword));
const [name, questionToken] = type_resolve_helpers_1.resolveOptionalFromName(doclet);
return handleComment(doclet, ts.createPropertySignature(mods, name, questionToken, type, undefined));
}
exports.createInterfaceMember = createInterfaceMember;
function createNamespaceMember(doclet, altName) {
logger_1.debug(`createNamespaceMember(${logger_1.docletDebugInfo(doclet)})`);
const mods = doclet.memberof ? undefined : [declareModifier];
const flags = (doclet.kind === 'constant' || doclet.readonly) ? ts.NodeFlags.Const : undefined;
const literalValue = doclet.defaultvalue !== undefined ? doclet.defaultvalue
: doclet.meta && doclet.meta.code.type === 'Literal' ? doclet.meta.code.value
: undefined;
const initializer = (flags === ts.NodeFlags.Const && literalValue !== undefined) ? ts.createLiteral(literalValue) : undefined;
const type = initializer ? undefined : type_resolve_helpers_1.resolveType(doclet.type, doclet);
return handleComment(doclet, ts.createVariableStatement(mods, ts.createVariableDeclarationList([
ts.createVariableDeclaration(buildName(doclet, altName), type, initializer)
], flags)));
}
exports.createNamespaceMember = createNamespaceMember;
function createExportDefault(doclet, value) {
logger_1.debug(`createExportDefault(${logger_1.docletDebugInfo(doclet)}, '${value}')`);
const expression = ts.createIdentifier(value);
return handleComment(doclet, ts.createExportDefault(expression));
}
exports.createExportDefault = createExportDefault;
function createModule(doclet, nested, children) {
logger_1.debug(`createModule(${logger_1.docletDebugInfo(doclet)})`);
validateModuleChildren(children);
const mods = doclet.memberof ? undefined : [declareModifier];
let body = undefined;
let flags = ts.NodeFlags.None;
if (nested)
flags |= ts.NodeFlags.NestedNamespace;
if (children)
body = ts.createModuleBlock(children);
let nameStr = doclet.name;
if ((nameStr[0] === '"' && nameStr[nameStr.length - 1] === '"')
|| (nameStr[0] === '\'' && nameStr[nameStr.length - 1] === '\'')) {
nameStr = nameStr.substr(1, nameStr.length - 2);
}
const name = ts.createStringLiteral(nameStr);
return handleComment(doclet, ts.createModuleDeclaration(undefined, mods, name, body, flags));
}
exports.createModule = createModule;
function createNamespace(doclet, nested, children, altName) {
logger_1.debug(`createNamespace(${logger_1.docletDebugInfo(doclet)}, altName=${altName})`);
validateModuleChildren(children);
const mods = doclet.memberof ? undefined : [declareModifier];
let body = undefined;
let flags = ts.NodeFlags.Namespace;
if (nested)
flags |= ts.NodeFlags.NestedNamespace;
if (children) {
body = ts.createModuleBlock(children);
}
return handleComment(doclet, ts.createModuleDeclaration(undefined, mods, buildName(doclet, altName), body, flags));
}
exports.createNamespace = createNamespace;
function createTypedef(doclet, children, altName) {
logger_1.debug(`createTypedef(${logger_1.docletDebugInfo(doclet)}, altName=${altName})`);
const mods = doclet.memberof ? undefined : [declareModifier];
const type = type_resolve_helpers_1.resolveType(doclet.type, doclet);
const typeParams = type_resolve_helpers_1.resolveTypeParameters(doclet);
return handleComment(doclet, ts.createTypeAliasDeclaration(undefined, mods, buildName(doclet, altName), typeParams, type));
}
exports.createTypedef = createTypedef;
//# sourceMappingURL=create_helpers.js.map

1
tools/jsdoc/overte-tsd-jsdoc/create_helpers.js.map Normal file
View file

File diff suppressed because one or more lines are too long

164
tools/jsdoc/overte-tsd-jsdoc/doclet_utils.js Normal file
View file

@ -0,0 +1,164 @@
"use strict";
var __importStar = (this && this.__importStar) || function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k in mod) if (Object.hasOwnProperty.call(mod, k)) result[k] = mod[k];
result["default"] = mod;
return result;
};
Object.defineProperty(exports, "__esModule", { value: true });
const fs = __importStar(require("fs"));
const path = __importStar(require("path"));
const logger_1 = require("./logger");
function isDocumentedDoclet(doclet) {
if (doclet.undocumented)
if (doclet.comment && doclet.comment.length > 0)
return true;
else
return false;
else
return true;
}
exports.isDocumentedDoclet = isDocumentedDoclet;
function hasParamsDoclet(doclet) {
if (doclet.kind === 'class'
|| doclet.kind === 'interface'
|| doclet.kind === 'mixin'
|| doclet.kind === 'file'
|| doclet.kind === 'event'
|| doclet.kind === 'function'
|| doclet.kind === 'callback'
|| doclet.kind === 'typedef') {
if (doclet.params && doclet.params.length > 0)
return true;
}
return false;
}
exports.hasParamsDoclet = hasParamsDoclet;
function isClassDoclet(doclet) {
return doclet.kind === 'class' || doclet.kind === 'interface' || doclet.kind === 'mixin';
}
exports.isClassDoclet = isClassDoclet;
function isClassDeclarationDoclet(doclet) {
return !!(doclet.kind === 'class'
&& doclet.meta
&& (!doclet.meta.code.type
|| doclet.meta.code.type === 'ClassDeclaration'
|| doclet.meta.code.type === 'ClassExpression'));
}
exports.isClassDeclarationDoclet = isClassDeclarationDoclet;
function isConstructorDoclet(doclet) {
return !!(doclet.kind === 'class'
&& doclet.meta
&& doclet.meta.code.type === 'MethodDefinition');
}
exports.isConstructorDoclet = isConstructorDoclet;
function isFileDoclet(doclet) {
return doclet.kind === 'file';
}
exports.isFileDoclet = isFileDoclet;
function isEventDoclet(doclet) {
return doclet.kind === 'event';
}
exports.isEventDoclet = isEventDoclet;
function isFunctionDoclet(doclet) {
return doclet.kind === 'function' || doclet.kind === 'callback';
}
exports.isFunctionDoclet = isFunctionDoclet;
function isMemberDoclet(doclet) {
return doclet.kind === 'member' || doclet.kind === 'constant';
}
exports.isMemberDoclet = isMemberDoclet;
function isNamespaceDoclet(doclet) {
return doclet.kind === 'module' || doclet.kind === 'namespace';
}
exports.isNamespaceDoclet = isNamespaceDoclet;
function isTypedefDoclet(doclet) {
return doclet.kind === 'typedef';
}
exports.isTypedefDoclet = isTypedefDoclet;
function isPackageDoclet(doclet) {
return doclet.kind === 'package';
}
exports.isPackageDoclet = isPackageDoclet;
function isEnumDoclet(doclet) {
return isMemberDoclet(doclet) && (doclet.isEnum === true);
}
exports.isEnumDoclet = isEnumDoclet;
function isDefaultExportDoclet(doclet, treeNodes) {
if (doclet.kind !== 'module'
&& doclet.meta
&& doclet.meta.code.name === 'module.exports'
&& doclet.longname.startsWith('module:')) {
const moduleName = doclet.memberof ? doclet.memberof : doclet.longname;
const node = treeNodes[moduleName];
if (node && node.doclet.kind === 'module') {
if (!doclet.memberof) {
doclet.memberof = node.doclet.longname;
logger_1.debug(`isDefaultExport(): ${logger_1.docletDebugInfo(doclet)}.memberof fixed to '${doclet.memberof}'`);
}
if (!doclet.meta.code.value) {
const sourcePath = path.join(doclet.meta.path, doclet.meta.filename);
const fd = fs.openSync(sourcePath, 'r');
if (fd < 0) {
logger_1.warn(`Could not read from '${sourcePath}'`);
return true;
}
const begin = doclet.meta.range[0];
const end = doclet.meta.range[1];
const length = end - begin;
const buffer = Buffer.alloc(length);
if (fs.readSync(fd, buffer, 0, length, begin) !== length) {
logger_1.warn(`Could not read from '${sourcePath}'`);
return true;
}
doclet.meta.code.value = buffer.toString().trim();
if (doclet.meta.code.value.endsWith(";"))
doclet.meta.code.value = doclet.meta.code.value.slice(0, -1).trimRight();
if (doclet.meta.code.value.match(/^export +default +/))
doclet.meta.code.value = doclet.meta.code.value.replace(/^export +default +/, "");
logger_1.debug(`isDefaultExport(): ${logger_1.docletDebugInfo(doclet)}.meta.code.value fixed to '${doclet.meta.code.value}'`);
}
return true;
}
}
return false;
}
exports.isDefaultExportDoclet = isDefaultExportDoclet;
function isNamedExportDoclet(doclet, treeNodes) {
const node = treeNodes[doclet.longname];
if (node && node.isNamedExport) {
return true;
}
if (doclet.kind !== 'module'
&& doclet.meta
&& doclet.meta.code.name
&& (doclet.meta.code.name.startsWith('module.exports.') || doclet.meta.code.name.startsWith('exports.'))
&& doclet.longname.startsWith('module:')
&& doclet.memberof) {
const parent = treeNodes[doclet.memberof];
if (parent && parent.doclet.kind === 'module') {
if (node) {
node.isNamedExport = true;
}
return true;
}
}
return false;
}
exports.isNamedExportDoclet = isNamedExportDoclet;
function isExportsAssignmentDoclet(doclet, treeNodes) {
if (doclet.kind === 'member'
&& doclet.meta
&& doclet.meta.code.name
&& doclet.meta.code.name === 'exports'
&& doclet.longname.startsWith('module:')
&& doclet.memberof) {
const node = treeNodes[doclet.memberof];
if (node && node.doclet.kind === 'module')
return true;
}
return false;
}
exports.isExportsAssignmentDoclet = isExportsAssignmentDoclet;
//# sourceMappingURL=doclet_utils.js.map

1
tools/jsdoc/overte-tsd-jsdoc/doclet_utils.js.map Normal file
View file

File diff suppressed because one or more lines are too long

59
tools/jsdoc/overte-tsd-jsdoc/logger.js Normal file
View file

@ -0,0 +1,59 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const header = '[TSD-JSDoc]';
let isVerbose = false;
function setVerbose(value) {
isVerbose = value;
}
exports.setVerbose = setVerbose;
function warn(msg, data) {
if (typeof (console) === 'undefined')
return;
let prefix = header;
if (data && data.meta) {
const meta = data.meta;
prefix = `${prefix} ${meta.filename}:${meta.lineno}:${meta.columnno}`;
}
console.warn(`${prefix} ${msg}`);
if (isVerbose && arguments.length > 1) {
console.warn(data);
}
if (isDebug) {
console.log(`${header} WARN: ${msg}`);
if (arguments.length > 1) {
console.log(data);
}
}
}
exports.warn = warn;
let isDebug = false;
function setDebug(value) {
isDebug = value;
}
exports.setDebug = setDebug;
function debug(msg, data) {
if (typeof (console) === 'undefined')
return;
if (isDebug) {
console.log(`${header} DEBUG: ${msg}`);
if (arguments.length > 1) {
console.log(data);
}
}
}
exports.debug = debug;
function docletDebugInfo(doclet) {
let debugInfo = `{longname='${doclet.longname}', kind='${doclet.kind}'`;
if ((doclet.kind !== 'package') && doclet.meta) {
if (doclet.meta.code.id)
debugInfo += `, id='${doclet.meta.code.id}'`;
if (doclet.meta.range)
debugInfo += `, range=[${doclet.meta.range[0]}-${doclet.meta.range[1]}]`;
else if (doclet.meta.lineno)
debugInfo += `, lineno=${doclet.meta.lineno}`;
}
debugInfo += `}`;
return debugInfo;
}
exports.docletDebugInfo = docletDebugInfo;
//# sourceMappingURL=logger.js.map

1
tools/jsdoc/overte-tsd-jsdoc/logger.js.map Normal file
View file

@ -0,0 +1 @@
{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":";;AAAA,MAAM,MAAM,GAAG,aAAa,CAAC;AAE7B,IAAI,SAAS,GAAG,KAAK,CAAC;AAEtB,SAAgB,UAAU,CAAC,KAAc;IAErC,SAAS,GAAG,KAAK,CAAC;AACtB,CAAC;AAHD,gCAGC;AAED,SAAgB,IAAI,CAAC,GAAW,EAAE,IAAU;IAExC,IAAI,OAAM,CAAC,OAAO,CAAC,KAAK,WAAW;QAC/B,OAAO;IAEX,IAAI,MAAM,GAAG,MAAM,CAAC;IACpB,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,EACrB;QACI,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACvB,MAAM,GAAG,GAAG,MAAM,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;KACzE;IAED,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;IAEjC,IAAI,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EACrC;QACI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;KACtB;IAED,IAAI,OAAO,EACX;QAGI,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,UAAU,GAAG,EAAE,CAAC,CAAC;QACtC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EACxB;YACI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;SACrB;KACJ;AACL,CAAC;AA7BD,oBA6BC;AAED,IAAI,OAAO,GAAG,KAAK,CAAC;AAEpB,SAAgB,QAAQ,CAAC,KAAc;IAEnC,OAAO,GAAG,KAAK,CAAC;AACpB,CAAC;AAHD,4BAGC;AAED,SAAgB,KAAK,CAAC,GAAW,EAAE,IAAU;IAEzC,IAAI,OAAM,CAAC,OAAO,CAAC,KAAK,WAAW;QAC/B,OAAO;IAEX,IAAI,OAAO,EACX;QAEI,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,WAAW,GAAG,EAAE,CAAC,CAAC;QACvC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EACxB;YACI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;SACrB;KACJ;AACL,CAAC;AAdD,sBAcC;AAED,SAAgB,eAAe,CAAC,MAAkB;IAC9C,IAAI,SAAS,GAAG,cAAc,MAAM,CAAC,QAAQ,YAAY,MAAM,CAAC,IAAI,GAAG,CAAC;IACxE,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,IAAI,MAAM,CAAC,IAAI,EAC9C;QACI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YACnB,SAAS,IAAI,SAAS,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC;QACjD,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK;YACjB,SAAS,IAAI,YAAY,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;aACxE,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM;YACvB,SAAS,IAAI,YAAY,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;KACrD;IACD,SAAS,IAAI,GAAG,CAAC;IACjB,OAAO,SAAS,CAAC;AACrB,CAAC;AAbD,0CAaC"}

41
tools/jsdoc/overte-tsd-jsdoc/package.json Normal file
View file

@ -0,0 +1,41 @@
{
"name": "tsd-jsdoc",
"version": "0.0.1",
"description": "Compiles JSDoc annotated javascript into a Typescript Declaration File (.d.ts).",
"main": "dist/publish.js",
"author": "Chad Engler <chad@pantherdev.com>",
"license": "MIT",
"repository": {
"type": "git",
"url": "git@github.com:englercj/jsdoc2tsd.git"
},
"scripts": {
"build": "tsc -p tsconfig.json",
"watch": "tsc -w -p tsconfig.json",
"prepare": "npm run build",
"test": "npm run build && mocha --ui tdd -r ts-node/register --timeout 5000 --colors test/specs/**.ts"
},
"files": [
"dist/*",
"README.md",
"LICENSE"
],
"devDependencies": {
"@types/chai": "^4.1.7",
"@types/mocha": "^5.2.5",
"@types/node": "^10.12.12",
"chai": "^4.2.0",
"jsdoc": "^3.6.3",
"jsdoc-api": "^5.0.3",
"mocha": "^5.2.0",
"object-to-spawn-args": "^2.0.0",
"ts-node": "^7.0.1",
"walk-back": "^3.0.1"
},
"peerDependencies": {
"jsdoc": "^3.6.3"
},
"dependencies": {
"typescript": "^3.2.1"
}
}

25
tools/jsdoc/overte-tsd-jsdoc/plugin.js Normal file
View file

@ -0,0 +1,25 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
function defineTags(dictionary) {
dictionary.defineTag("template", {
onTagged: function (doclet, tag) {
doclet.tags = doclet.tags || [];
doclet.tags.push(tag);
}
});
}
exports.defineTags = defineTags;
;
const regexTypeOf = /typeof\s+([^\|\}]+)/g;
exports.handlers = {
jsdocCommentFound: function (event) {
let oldResult = "";
let newResult = event.comment || "";
while (newResult !== oldResult) {
oldResult = newResult;
newResult = newResult.replace(regexTypeOf, (typeExpression, className) => "Class<" + className + ">");
}
event.comment = newResult;
}
};
//# sourceMappingURL=plugin.js.map

1
tools/jsdoc/overte-tsd-jsdoc/plugin.js.map Normal file
View file

@ -0,0 +1 @@
{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":";;AAAA,SAAgB,UAAU,CAAC,UAA0B;IACjD,UAAU,CAAC,SAAS,CAAC,UAAU,EAAE;QAC7B,QAAQ,EAAE,UAAS,MAAM,EAAE,GAAG;YAC1B,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YAChC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;KACJ,CAAC,CAAC;AACP,CAAC;AAPD,gCAOC;AAAA,CAAC;AAEF,MAAM,WAAW,GAAG,sBAAsB,CAAA;AAE/B,QAAA,QAAQ,GAAG;IAClB,iBAAiB,EAAE,UAAS,KAAgE;QACxF,IAAI,SAAS,GAAG,EAAE,CAAC;QACnB,IAAI,SAAS,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;QACpC,OAAO,SAAS,KAAK,SAAS,EAAE;YAC5B,SAAS,GAAG,SAAS,CAAC;YACtB,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,SAAS,EAAE,EAAE,CAAC,QAAQ,GAAG,SAAS,GAAG,GAAG,CAAC,CAAC;SACzG;QACD,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;IAC9B,CAAC;CACJ,CAAC"}

82
tools/jsdoc/overte-tsd-jsdoc/publish.js Normal file
View file

@ -0,0 +1,82 @@
"use strict";
var __importStar = (this && this.__importStar) || function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k in mod) if (Object.hasOwnProperty.call(mod, k)) result[k] = mod[k];
result["default"] = mod;
return result;
};
Object.defineProperty(exports, "__esModule", { value: true });
const path = __importStar(require("path"));
const fs = __importStar(require("fs"));
const helper = __importStar(require("jsdoc/util/templateHelper"));
const Emitter_1 = require("./Emitter");
const logger_1 = require("./logger");
function publish(data, opts) {
logger_1.setVerbose(!!opts.verbose);
logger_1.setDebug(!!opts.debug);
if (!opts.generationStrategy) {
opts.generationStrategy = 'documented';
}
logger_1.debug(`publish(): Generation strategy: '${opts.generationStrategy}'`);
if (opts.generationStrategy === 'documented') {
data(function () {
if (this.undocumented) {
if ((!this.comment) || (this.comment === '')) {
logger_1.debug(`publish(): ${logger_1.docletDebugInfo(this)} removed`);
return true;
}
else {
logger_1.debug(`publish(): ${logger_1.docletDebugInfo(this)} saved from removal`);
}
}
return false;
}).remove();
}
else if (opts.generationStrategy === 'exported') {
logger_1.warn(`Note: The 'exported' generation strategy is still an experimental feature for the moment, thank you for your comprehension. `
+ `Feel free to contribute in case you find a bug.`);
}
const docs = data().get().filter(d => !d.inherited || d.overrides);
const emitter = new Emitter_1.Emitter(opts);
emitter.parse(docs);
if (opts.destination === 'console') {
console.log(emitter.emit());
}
else {
try {
fs.mkdirSync(opts.destination);
}
catch (e) {
if (e.code !== 'EEXIST') {
throw e;
}
}
let filedata = emitter.emit().toString();
console.log('stage1 starting preprocesing');
filedata = filedata.replace(/(: void)/gmi, '');
filedata = filedata.replace(/(: int)/gmi, ': number');
filedata = filedata.replace(/(numberer)/gmi, 'Inter');
console.log('stage2 replacing Void and int');
filedata = filedata.replace(/([a-zA-Z])~([a-zA-Z])/g, '$1.$2');
filedata = filedata.replace(/\b(([A-Z][a-z]+)+)-(([A-Z][a-z]+)+)\b/g, '$1$3');
console.log('stage3 removing "-" from type names');
filedata = filedata.replace(/\b(Vec[2-4]|Mat4|Quat)\b/g, 'T$1');
console.log('stage4 add prefix "T" to the types');
filedata = filedata.replace(/\bdeclare namespace T(Vec[2-4]|Mat4|Quat)/g, 'declare namespace $1');
filedata = filedata.replace(/\bT(Vec[2-4]|Mat4|Quat)\./g, '$1.');
console.log('stage5 Restore previous names for namespace');
filedata = filedata.replace(/function: \(/g, 'fn: (');
console.log('stage6 "function" is really wrong name for na variable');
const pkgArray = helper.find(data, { kind: 'package' }) || [];
const pkg = pkgArray[0];
let definitionName = 'types';
if (pkg && pkg.name) {
definitionName = pkg.name.split('/').pop() || definitionName;
}
const out = path.join(opts.destination, opts.outFile || `${definitionName}.d.ts`);
fs.writeFileSync(out, filedata);
}
}
exports.publish = publish;
//# sourceMappingURL=publish.js.map

1
tools/jsdoc/overte-tsd-jsdoc/publish.js.map Normal file
View file

@ -0,0 +1 @@
{"version":3,"file":"publish.js","sourceRoot":"","sources":["../src/publish.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA6B;AAC7B,uCAAyB;AACzB,kEAAoD;AACpD,uCAAoC;AACpC,qCAA8E;AAM9E,SAAgB,OAAO,CAAC,IAAe,EAAE,IAAqB;IAG1D,mBAAU,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,iBAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAGvB,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAC5B;QACI,IAAI,CAAC,kBAAkB,GAAG,YAAY,CAAC;KAC1C;IACD,cAAK,CAAC,oCAAoC,IAAI,CAAC,kBAAkB,GAAG,CAAC,CAAC;IAEtE,IAAI,IAAI,CAAC,kBAAkB,KAAK,YAAY,EAC5C;QAEI,IAAI,CAGA;YAEI,IAAI,IAAI,CAAC,YAAY,EACrB;gBAEI,IAAI,CAAC,CAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,EAAE,CAAC,EAC7C;oBACI,cAAK,CAAC,cAAc,wBAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;oBACrD,OAAO,IAAI,CAAC;iBACf;qBAED;oBACI,cAAK,CAAC,cAAc,wBAAe,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;iBACnE;aACJ;YACD,OAAO,KAAK,CAAC;QACjB,CAAC,CACJ,CAAC,MAAM,EAAE,CAAC;KACd;SACI,IAAI,IAAI,CAAC,kBAAkB,KAAK,UAAU,EAC/C;QAKI,aAAI,CAAC,8HAA8H;cAC7H,iDAAiD,CAAC,CAAC;KAC5D;IAGD,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC;IAGnE,MAAM,OAAO,GAAG,IAAI,iBAAO,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAGpB,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAClC;QACI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;KAC/B;SAED;QACI,IACA;YACI,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;SAClC;QACD,OAAO,CAAC,EACR;YACI,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EACvB;gBACI,MAAM,CAAC,CAAC;aACX;SACJ;QAED,IAAI,QAAQ,GAAW,OAAO,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAA;QAChD,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAA;QAC3C,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;QAC/C,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAGtD,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACtD,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAA;QAE5C,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,wBAAwB,EAAE,OAAO,CAAC,CAAC;QAG/D,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,wCAAwC,EAAE,MAAM,CAAC,CAAC;QAC9E,OAAO,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAA;QAIlD,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;QAChE,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAA;QAGjD,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,4CAA4C,EAAE,sBAAsB,CAAC,CAAC;QAClG,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,4BAA4B,EAAE,KAAK,CAAC,CAAC;QACjE,OAAO,CAAC,GAAG,CAAC,6CAA6C,CAAC,CAAA;QAG1D,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACtD,OAAO,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAA;QAIrE,MAAM,QAAQ,GAAQ,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC;QACnE,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAmB,CAAC;QAC1C,IAAI,cAAc,GAAW,OAAO,CAAC;QACrC,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE;YACnB,cAAc,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,cAAc,CAAC;SAC9D;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,IAAI,GAAG,cAAc,OAAO,CAAC,CAAC;QAClF,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;KAEnC;AACL,CAAC;AAnHD,0BAmHC"}

523
tools/jsdoc/overte-tsd-jsdoc/type_resolve_helpers.js Normal file
View file

@ -0,0 +1,523 @@
"use strict";
var __importStar = (this && this.__importStar) || function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k in mod) if (Object.hasOwnProperty.call(mod, k)) result[k] = mod[k];
result["default"] = mod;
return result;
};
Object.defineProperty(exports, "__esModule", { value: true });
const ts = __importStar(require("typescript"));
const logger_1 = require("./logger");
const PropTree_1 = require("./PropTree");
const rgxObjectTokenize = /(<|>|,|\(|\)|\||\{|\}|:)/;
const rgxCommaAll = /,/g;
const rgxParensAll = /\(|\)/g;
const anyTypeNode = ts.createKeywordTypeNode(ts.SyntaxKind.AnyKeyword);
const voidTypeNode = ts.createKeywordTypeNode(ts.SyntaxKind.VoidKeyword);
const strTypeNode = ts.createKeywordTypeNode(ts.SyntaxKind.StringKeyword);
var ENodeType;
(function (ENodeType) {
ENodeType[ENodeType["GENERIC"] = 0] = "GENERIC";
ENodeType[ENodeType["UNION"] = 1] = "UNION";
ENodeType[ENodeType["FUNCTION"] = 2] = "FUNCTION";
ENodeType[ENodeType["TUPLE"] = 3] = "TUPLE";
ENodeType[ENodeType["TYPE"] = 4] = "TYPE";
ENodeType[ENodeType["OBJECT"] = 5] = "OBJECT";
})(ENodeType || (ENodeType = {}));
class StringTreeNode {
constructor(name, type, parent) {
this.name = name;
this.type = type;
this.parent = parent;
this.children = [];
}
dump(output, indent = 0) {
output(`${' '.repeat(indent)}name: ${this.name}, type:${this.typeToString()}`);
this.children.forEach((child) => {
child.dump(output, indent + 1);
});
}
walkTypes(callback) {
for (let i = 0; i < this.children.length; ++i) {
if (this.type === ENodeType.OBJECT && (i % 2 === 0))
continue;
this.children[i].walkTypes(callback);
}
callback(this);
}
typeToString() {
switch (this.type) {
case ENodeType.GENERIC:
return 'GENERIC';
case ENodeType.UNION:
return 'UNION';
case ENodeType.FUNCTION:
return 'FUNCTION';
case ENodeType.TUPLE:
return 'TUPLE';
case ENodeType.TYPE:
return 'TYPE';
case ENodeType.OBJECT:
return 'OBJECT';
default:
return 'UNKNOWN';
}
}
}
exports.StringTreeNode = StringTreeNode;
function resolveComplexTypeName(name, doclet) {
const root = generateTree(name);
if (!root) {
logger_1.warn(`failed to generate tree for ${name}, defaulting to any`);
return anyTypeNode;
}
return resolveTree(root);
}
exports.resolveComplexTypeName = resolveComplexTypeName;
function generateTree(name, parent = null) {
const anyNode = new StringTreeNode('any', ENodeType.TYPE, parent);
const parts = name.split(rgxObjectTokenize).filter(function (e) {
return e.trim() !== '';
});
for (let i = 0; i < parts.length; ++i) {
const part = parts[i].trim();
const partUpper = part.toUpperCase();
if (part.endsWith('.')) {
const matchingIndex = findMatchingBracket(parts, i + 1, '<', '>');
if (matchingIndex === -1) {
logger_1.warn(`Unable to find matching '<', '>' brackets in '${part}', defaulting to \`any\``, name);
return anyNode;
}
const node = new StringTreeNode(part.substring(0, part.length - 1), ENodeType.GENERIC, parent);
generateTree(parts.slice(i + 2, matchingIndex).join(''), node);
if (!parent)
return node;
parent.children.push(node);
i = matchingIndex + 1;
continue;
}
if (part === '(') {
const matchingIndex = findMatchingBracket(parts, i, '(', ')');
if (matchingIndex === -1) {
logger_1.warn(`Unable to find matching '(', ')' brackets in '${part}', defaulting to \`any\``, name);
return anyNode;
}
const node = new StringTreeNode('Union', ENodeType.UNION, parent);
generateTree(parts.slice(i + 1, matchingIndex).join(''), node);
if (!parent)
return node;
parent.children.push(node);
i = matchingIndex + 1;
continue;
}
if (part === '{') {
const matchingIndex = findMatchingBracket(parts, i, '{', '}');
if (matchingIndex === -1) {
logger_1.warn(`Unable to find matching '{', '}' brackets in '${part}', defaulting to \`any\``, name);
return anyNode;
}
const node = new StringTreeNode('Object', ENodeType.OBJECT, parent);
generateTree(parts.slice(i + 1, matchingIndex).join(''), node);
if (!parent)
return node;
parent.children.push(node);
i = matchingIndex + 1;
continue;
}
if (partUpper === 'FUNCTION') {
const node = new StringTreeNode(part, ENodeType.FUNCTION, parent);
let matchingIndex = findMatchingBracket(parts, i + 1, '(', ')');
if (matchingIndex === -1) {
logger_1.warn(`Unable to find matching '(', ')' brackets in '${part}', defaulting to \`any\``, name);
return anyNode;
}
if (matchingIndex > i + 2)
generateTree(parts.slice(i + 2, matchingIndex).join(''), node);
if (parts.length > matchingIndex + 2 && parts[matchingIndex + 1] === ':') {
generateTree(parts[matchingIndex + 2], node);
matchingIndex += 2;
}
else {
node.children.push(new StringTreeNode('void', ENodeType.TYPE, node));
}
if (!parent)
return node;
parent.children.push(node);
i = matchingIndex + 1;
continue;
}
if (part === '|' || part === ',' || part === ':') {
continue;
}
const node = new StringTreeNode(part, ENodeType.TYPE, parent);
if (part === '*')
node.name = 'any';
else if (partUpper === 'OBJECT')
node.name = 'object';
else if (partUpper === 'ARRAY')
node.name = 'any[]';
if (!parent)
return node;
parent.children.push(node);
}
return anyNode;
}
exports.generateTree = generateTree;
function findMatchingBracket(parts, startIndex, openBracket, closeBracket) {
let count = 0;
for (let i = startIndex; i < parts.length; ++i) {
if (parts[i] === openBracket) {
++count;
}
else if (parts[i] === closeBracket) {
if (--count === 0) {
return i;
}
}
}
return -1;
}
function resolveTree(node, parentTypes = null) {
const childTypes = [];
node.children.forEach((child) => resolveTree(child, childTypes));
const upperName = node.name.toUpperCase();
switch (node.type) {
case ENodeType.OBJECT:
const objectProperties = [];
for (var i = 0; i < node.children.length; i = i + 2) {
let valType = childTypes[i + 1];
if (!valType) {
logger_1.warn('Unable to resolve object value type, this is likely due to invalid JSDoc. Defaulting to \`any\`.', node);
valType = anyTypeNode;
}
const property = ts.createPropertySignature(undefined, ts.createIdentifier(node.children[i].name), undefined, valType, undefined);
objectProperties.push(property);
}
const objectNode = ts.createTypeLiteralNode(objectProperties);
ts.setEmitFlags(objectNode, ts.EmitFlags.SingleLine);
if (!parentTypes)
return objectNode;
parentTypes.push(objectNode);
break;
case ENodeType.GENERIC:
let genericNode;
if (upperName === 'OBJECT') {
let keyType = childTypes[0];
if (!keyType) {
logger_1.warn(`Unable to resolve object key type, this is likely due to invalid JSDoc. Defaulting to \`string\`.`);
keyType = strTypeNode;
}
else if (node.children[0].type !== ENodeType.TYPE || (node.children[0].name !== 'string' && node.children[0].name !== 'number')) {
logger_1.warn(`Invalid object key type. It must be \`string\` or \`number\`, but got: ${node.children[0].name}. Defaulting to \`string\`.`);
keyType = strTypeNode;
}
let valType = childTypes[1];
if (!valType) {
logger_1.warn('Unable to resolve object value type, this is likely due to invalid JSDoc. Defaulting to \`any\`.', node);
valType = anyTypeNode;
}
const indexParam = ts.createParameter(undefined, undefined, undefined, 'key', undefined, keyType, undefined);
const indexSignature = ts.createIndexSignature(undefined, undefined, [indexParam], valType);
genericNode = ts.createTypeLiteralNode([indexSignature]);
}
else if (upperName === 'ARRAY') {
let valType = childTypes[0];
if (!valType) {
logger_1.warn('Unable to resolve array value type, defaulting to \`any\`.', node);
valType = anyTypeNode;
}
genericNode = ts.createArrayTypeNode(valType);
}
else if (upperName === 'CLASS') {
let valType = childTypes[0];
if (!valType) {
logger_1.warn('Unable to resolve class value type, defaulting to \`any\`.', node);
valType = anyTypeNode;
}
genericNode = ts.createTypeQueryNode(ts.createIdentifier(node.children[0].name));
}
else {
if (childTypes.length === 0) {
logger_1.warn('Unable to resolve generic type, defaulting to \`any\`.', node);
childTypes.push(anyTypeNode);
}
if (upperName === 'PROMISE') {
while (childTypes.length > 1)
childTypes.pop();
}
genericNode = ts.createTypeReferenceNode(node.name, childTypes);
}
if (!parentTypes)
return genericNode;
parentTypes.push(genericNode);
break;
case ENodeType.UNION:
if (childTypes.length === 0) {
logger_1.warn('Unable to resolve any types for union, defaulting to \`any\`.', node);
childTypes.push(anyTypeNode);
}
const unionNode = ts.createUnionTypeNode(childTypes);
if (!parentTypes)
return unionNode;
parentTypes.push(unionNode);
break;
case ENodeType.FUNCTION:
const funcParameters = [];
if (childTypes.length === 0 || childTypes.length === 1) {
const anyArray = ts.createArrayTypeNode(anyTypeNode);
const dotDotDot = ts.createToken(ts.SyntaxKind.DotDotDotToken);
funcParameters.push(ts.createParameter(undefined, undefined, dotDotDot, 'params', undefined, anyArray, undefined));
if (childTypes.length === 0)
childTypes.push(voidTypeNode);
}
for (var i = 0; i < node.children.length - 1; ++i) {
const param = ts.createParameter(undefined, undefined, undefined, 'arg' + i, undefined, childTypes[i], undefined);
funcParameters.push(param);
}
const functionNode = ts.createFunctionTypeNode(undefined, funcParameters, childTypes[childTypes.length - 1]);
if (!parentTypes)
return functionNode;
parentTypes.push(functionNode);
break;
case ENodeType.TYPE:
const typeNode = ts.createTypeReferenceNode(node.name, undefined);
if (!parentTypes)
return typeNode;
parentTypes.push(typeNode);
break;
}
return anyTypeNode;
}
function toKeywordTypeKind(k) {
if (!k || k.length === 0)
return null;
k = k.toUpperCase();
switch (k) {
case 'ANY': return ts.SyntaxKind.AnyKeyword;
case 'UNKNOWN': return ts.SyntaxKind.UnknownKeyword;
case 'NUMBER': return ts.SyntaxKind.NumberKeyword;
case 'BIGINT': return ts.SyntaxKind.BigIntKeyword;
case 'OBJECT': return ts.SyntaxKind.ObjectKeyword;
case 'BOOLEAN': return ts.SyntaxKind.BooleanKeyword;
case 'BOOL': return ts.SyntaxKind.BooleanKeyword;
case 'STRING': return ts.SyntaxKind.StringKeyword;
case 'SYMBOL': return ts.SyntaxKind.SymbolKeyword;
case 'THIS': return ts.SyntaxKind.ThisKeyword;
case 'VOID': return ts.SyntaxKind.VoidKeyword;
case 'UNDEFINED': return ts.SyntaxKind.UndefinedKeyword;
case 'NULL': return ts.SyntaxKind.NullKeyword;
case 'NEVER': return ts.SyntaxKind.NeverKeyword;
default:
return null;
}
}
exports.toKeywordTypeKind = toKeywordTypeKind;
function resolveOptionalParameter(doclet) {
if (doclet.defaultvalue || doclet.optional)
return ts.createToken(ts.SyntaxKind.QuestionToken);
return undefined;
}
exports.resolveOptionalParameter = resolveOptionalParameter;
function resolveVariableParameter(doclet) {
if (doclet.variable)
return ts.createToken(ts.SyntaxKind.DotDotDotToken);
return undefined;
}
exports.resolveVariableParameter = resolveVariableParameter;
function resolveOptionalFromName(doclet) {
let name = doclet.name;
if (name.startsWith('[') && name.endsWith(']')) {
name = name.substring(1, name.length - 1);
return [name, ts.createToken(ts.SyntaxKind.QuestionToken)];
}
if (doclet.optional) {
return [name, ts.createToken(ts.SyntaxKind.QuestionToken)];
}
return [name, undefined];
}
exports.resolveOptionalFromName = resolveOptionalFromName;
function getExprWithTypeArgs(identifier) {
const expr = ts.createIdentifier(identifier);
return ts.createExpressionWithTypeArguments(undefined, expr);
}
function resolveHeritageClauses(doclet, onlyExtend) {
const clauses = [];
let extensions = doclet.augments || [];
if (onlyExtend) {
extensions = extensions.concat(doclet.implements || []);
extensions = extensions.concat(doclet.mixes || []);
}
if (extensions.length) {
clauses.push(ts.createHeritageClause(ts.SyntaxKind.ExtendsKeyword, extensions.map(getExprWithTypeArgs)));
}
if (onlyExtend)
return clauses;
let implementations = (doclet.implements || []).concat(doclet.mixes || []);
if (implementations.length) {
clauses.push(ts.createHeritageClause(ts.SyntaxKind.ImplementsKeyword, implementations.map(getExprWithTypeArgs)));
}
return clauses;
}
exports.resolveHeritageClauses = resolveHeritageClauses;
function resolveTypeParameters(doclet) {
const typeParams = [];
if (doclet.tags) {
for (let i = 0; i < doclet.tags.length; ++i) {
const tag = doclet.tags[i];
if (tag.title === 'template') {
onTemplateTag(tag.text);
}
}
}
else if (doclet.comment && doclet.comment.includes('@template')) {
logger_1.debug(`resolveTypeParameters(): jsdoc@3.6.x @template handling directly in the comment text for ${logger_1.docletDebugInfo(doclet)}`);
for (let line of doclet.comment.split(/\r?\n/)) {
line = line.trim();
if (line.startsWith('*'))
line = line.slice(1).trim();
if (line.startsWith('@template')) {
line = line.slice('@template'.length).trim();
onTemplateTag(line);
}
}
}
function onTemplateTag(tagText) {
const types = (tagText || 'T').split(',');
for (let x = 0; x < types.length; ++x) {
const name = types[x].trim();
if (!name)
continue;
typeParams.push(ts.createTypeParameterDeclaration(name, undefined, undefined));
}
}
return typeParams;
}
exports.resolveTypeParameters = resolveTypeParameters;
function resolveType(t, doclet) {
if (!t || !t.names || t.names.length === 0) {
if (doclet && doclet.properties)
return resolveTypeName('object', doclet);
if (doclet) {
logger_1.warn(`Unable to resolve type for ${doclet.longname || doclet.name}, none specified in JSDoc. Defaulting to \`any\`.`, doclet);
}
else {
logger_1.warn(`Unable to resolve type for an unnamed item, this is likely due to invalid JSDoc.` +
` Often this is caused by invalid JSDoc on a parameter. Defaulting to \`any\`.`, doclet);
}
return anyTypeNode;
}
if (t.names.length === 1) {
return resolveTypeName(t.names[0], doclet);
}
else {
const types = [];
for (let i = 0; i < t.names.length; ++i) {
types.push(resolveTypeName(t.names[i], doclet));
}
return ts.createUnionTypeNode(types);
}
}
exports.resolveType = resolveType;
function resolveTypeName(name, doclet) {
if (!name) {
logger_1.warn('Unable to resolve type name, it is null, undefined, or empty. Defaulting to \`any\`.', doclet);
return anyTypeNode;
}
if (name === '*')
return anyTypeNode;
const keyword = toKeywordTypeKind(name);
if (keyword !== null) {
if (keyword === ts.SyntaxKind.ThisKeyword)
return ts.createThisTypeNode();
if (keyword === ts.SyntaxKind.ObjectKeyword) {
if (!doclet || !doclet.properties)
return anyTypeNode;
else
return resolveTypeLiteral(doclet.properties);
}
return ts.createKeywordTypeNode(keyword);
}
const upperName = name.toUpperCase();
if (upperName === 'FUNCTION' || upperName === 'FUNCTION()') {
if (doclet && doclet.kind === 'typedef') {
const params = createFunctionParams(doclet);
const type = createFunctionReturnType(doclet);
return ts.createFunctionTypeNode(undefined, params, type);
}
else {
const anyArray = ts.createArrayTypeNode(anyTypeNode);
const dotDotDot = ts.createToken(ts.SyntaxKind.DotDotDotToken);
const param = ts.createParameter(undefined, undefined, dotDotDot, 'params', undefined, anyArray, undefined);
return ts.createFunctionTypeNode(undefined, [param], anyTypeNode);
}
}
return resolveComplexTypeName(name);
}
exports.resolveTypeName = resolveTypeName;
function resolveTypeLiteral(props) {
if (!props)
return ts.createTypeLiteralNode([]);
const tree = new PropTree_1.PropTree(props);
return createTypeLiteral(tree.roots);
}
exports.resolveTypeLiteral = resolveTypeLiteral;
function createTypeLiteral(children, parent) {
const members = [];
for (let i = 0; i < children.length; ++i) {
const node = children[i];
const opt = node.prop.optional ? ts.createToken(ts.SyntaxKind.QuestionToken) : undefined;
const t = node.children.length ? createTypeLiteral(node.children, node) : resolveType(node.prop.type);
const property = ts.createPropertySignature(undefined, node.name, opt, t, undefined);
if (!parent && (node.prop.description || node.prop.defaultvalue)) {
let comment = `*\n `;
if (node.prop.description)
comment += `* ${node.prop.description.split(/\r\s*/).join("\n * ")}\n `;
if (node.prop.defaultvalue)
comment += `* @defaultValue ${node.prop.defaultvalue}\n `;
ts.addSyntheticLeadingComment(property, ts.SyntaxKind.MultiLineCommentTrivia, comment, true);
}
members.push(property);
}
let node = ts.createTypeLiteralNode(members);
if (parent && parent.prop.type) {
const names = parent.prop.type.names;
if (names.length === 1 && names[0].toLowerCase() === 'array.<object>') {
node = ts.createArrayTypeNode(node);
}
}
return node;
}
exports.createTypeLiteral = createTypeLiteral;
function createFunctionParams(doclet) {
const params = [];
if ((doclet.kind === 'function' || doclet.kind === 'typedef') && doclet.this) {
const type = resolveType({ names: [doclet.this] }, doclet);
params.push(ts.createParameter(undefined, undefined, undefined, 'this', undefined, type, undefined));
}
if (!doclet.params || !doclet.params.length)
return params;
const tree = new PropTree_1.PropTree(doclet.params);
for (let i = 0; i < tree.roots.length; ++i) {
const node = tree.roots[i];
const opt = resolveOptionalParameter(node.prop);
const dots = resolveVariableParameter(node.prop);
let type = node.children.length ? createTypeLiteral(node.children, node) : resolveType(node.prop.type);
if (dots) {
type = ts.createArrayTypeNode(type);
}
params.push(ts.createParameter(undefined, undefined, dots, node.name, opt, type, undefined));
}
return params;
}
exports.createFunctionParams = createFunctionParams;
function createFunctionReturnType(doclet) {
if (doclet.returns && doclet.returns.length === 1) {
return resolveType(doclet.returns[0].type, doclet);
}
else {
return ts.createKeywordTypeNode(ts.SyntaxKind.VoidKeyword);
}
}
exports.createFunctionReturnType = createFunctionReturnType;
//# sourceMappingURL=type_resolve_helpers.js.map

1
tools/jsdoc/overte-tsd-jsdoc/type_resolve_helpers.js.map Normal file
View file

File diff suppressed because one or more lines are too long