Mirrors/overte-AleziaKurdis
3
0
Fork 0
mirror of https://github.com/AleziaKurdis/overte.git synced 2025-04-08 23:12:16 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added custom jsdoc tags to High Fidelity

Browse source 
There are 4 new jsdoc tags:

* @hifi-interface - indicates that this namespace or class is available in Interface Scripts.
* @hifi-assignment-client - indicates that this namespace or class is available in Assignment Client Scripts.
* @hifi-client-entity - indicates that this namespace or class is available in Client Entity Scripts.
* @hifi-server-entity - indicates that this namespace or class is avaialbe in Server Entity Scripts.

These tags should appear just after the @class or @namespace tag. For example:

    /**jsdoc
     * Your avatar is your in-world representation of you. The <code>MyAvatar</code> API is used to manipulate the avatar.
     * For example, you can customize the avatar's appearance, run custom avatar animations,
     * change the avatar's position within the domain, or manage the avatar's collisions with other objects.
     *
     * @namespace MyAvatar
     *
     * @hifi-interface
     * @hifi-client-entity
     *
This commit is contained in:
Anthony J. Thibault 2018-04-26 14:13:42 -07:00
parent 098b432fd9
commit c6b12307aa
2 changed files with 87 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
interface/src/avatar/MyAvatar.h
View file

@ -60,6 +60,10 @@ class MyAvatar : public Avatar {
* change the avatar's position within the domain, or manage the avatar's collisions with other objects.
*
* @namespace MyAvatar
*
* @hifi-interface
* @hifi-client-entity
*
* @property {Vec3} qmlPosition - A synonym for <code>position</code> for use by QML.
* @property {boolean} shouldRenderLocally=true - If <code>true</code> then your avatar is rendered for you in Interface,
* otherwise it is not rendered for you (but it is still rendered for other users).

94
tools/jsdoc/plugins/hifi.js
View file

@ -9,21 +9,25 @@ function endsWith(path, exts) {
}
exports.handlers = {
// This event is triggered before parsing has even started.
// We use this event to scan the C++ files for jsdoc comments
// and reformat them into a form digestable by jsdoc.
beforeParse: function(e) {
const pathTools = require('path');
var pathTools = require('path');
var rootFolder = pathTools.dirname(e.filename);
console.log("Scanning hifi source for jsdoc comments...");
// directories to scan for jsdoc comments
var dirList = [
'../../interface/src',
'../../interface/src/assets',
'../../interface/src/audio',
'../../interface/src/assets',
'../../interface/src/audio',
'../../interface/src/avatar',
'../../interface/src/commerce',
'../../interface/src/devices',
'../../interface/src/java',
'../../interface/src/networking',
'../../interface/src/commerce',
'../../interface/src/devices',
'../../interface/src/java',
'../../interface/src/networking',
'../../interface/src/ui/',
'../../interface/src/scripting',
'../../interface/src/ui/overlays',
@ -50,25 +54,93 @@ exports.handlers = {
'../../libraries/trackers/src/trackers',
'../../libraries/ui/src/ui',
'../../plugins/oculus/src',
'../../plugins/openvr/src',
'../../plugins/openvr/src'
];
// only files with this extension will be searched for jsdoc comments.
var exts = ['.h', '.cpp'];
const fs = require('fs');
var fs = require('fs');
dirList.forEach(function (dir) {
var joinedDir = pathTools.join(rootFolder, dir);
var files = fs.readdirSync(joinedDir)
var files = fs.readdirSync(joinedDir);
files.forEach(function (file) {
var path = pathTools.join(joinedDir, file);
if (fs.lstatSync(path).isFile() && endsWith(path, exts)) {
// load entire file into a string
var data = fs.readFileSync(path, "utf8");
// this regex searches for blocks starting with /**jsdoc and end with */
var reg = /(\/\*\*jsdoc(.|[\r\n])*?\*\/)/gm;
var matches = data.match(reg);
if (matches) {
e.source += matches.map(function (s) { return s.replace('/**jsdoc', '/**'); }).join('\n');
// add to source, but strip off c-comment asterisks
e.source += matches.map(function (s) {
return s.replace('/**jsdoc', '/**');
}).join('\n');
}
}
});
});
},
// This event is triggered when a new doclet has been created
// but before it is passed to the template for output
newDoclet: function (e) {
// we only care about hifi custom tags on namespace and class doclets
if (e.doclet.kind === "namespace" || e.doclet.kind === "class") {
var rows = [];
if (e.doclet.hifiInterface) {
rows.push("Interface Scripts");
}
if (e.doclet.hifiAssignmentClient) {
rows.push("Assignment Client Scripts");
}
if (e.doclet.hifiClientEntity) {
rows.push("Client Entity Scripts");
}
if (e.doclet.hifiServerEntity) {
rows.push("Server Entity Scripts");
}
// Append an Available In: table at the end of the namespace description.
if (rows.length > 0) {
var table = "<br><br><table><td>Available In:<td>" + rows.join("<td>") + "</table>";
e.doclet.description = e.doclet.description + table;
}
}
}
};
// Define custom hifi tags here
exports.defineTags = function (dictionary) {
// @hifi-interface
dictionary.defineTag("hifi-interface", {
onTagged: function (doclet, tag) {
doclet.hifiInterface = true;
}
});
// @hifi-assignment-client
dictionary.defineTag("hifi-assigment-client", {
onTagged: function (doclet, tag) {
doclet.hifiAssignmentClient = true;
}
});
// @hifi-client-entity
dictionary.defineTag("hifi-client-entity", {
onTagged: function (doclet, tag) {
doclet.hifiClientEntity = true;
}
});
// @hifi-server-entity
dictionary.defineTag("hifi-server-entity", {
onTagged: function (doclet, tag) {
doclet.hifiServerEntity = true;
}
});
};