From 5b244357e0542122a2eea6fc51c09920d307e188 Mon Sep 17 00:00:00 2001 From: "Anthony J. Thibault" Date: Wed, 9 Nov 2016 18:03:42 -0800 Subject: [PATCH 1/4] Add jsdoc readme and plugin --- scripts/jsdoc/.gitignore | 1 + scripts/jsdoc/README.md | 13 ++++++++++++ scripts/jsdoc/config.json | 8 +++++++ scripts/jsdoc/plugins/hifi.js | 40 +++++++++++++++++++++++++++++++++++ scripts/jsdoc/root.js | 11 ++++++++++ 5 files changed, 73 insertions(+) create mode 100644 scripts/jsdoc/.gitignore create mode 100644 scripts/jsdoc/README.md create mode 100644 scripts/jsdoc/config.json create mode 100644 scripts/jsdoc/plugins/hifi.js create mode 100644 scripts/jsdoc/root.js diff --git a/scripts/jsdoc/.gitignore b/scripts/jsdoc/.gitignore new file mode 100644 index 0000000000..c585e19389 --- /dev/null +++ b/scripts/jsdoc/.gitignore @@ -0,0 +1 @@ +out \ No newline at end of file diff --git a/scripts/jsdoc/README.md b/scripts/jsdoc/README.md new file mode 100644 index 0000000000..c43f95cabe --- /dev/null +++ b/scripts/jsdoc/README.md @@ -0,0 +1,13 @@ +#JavaScript Documentation Generation + +##Prerequisites + +* Install node.js +* Install jsdoc via npm. `npm install jsdoc -g` + +To generate html documentation for the High Fidelity JavaScript API + +`cd scripts/jsdoc` +`jsdoc . -c config.json` + +The out folder should contain index.html diff --git a/scripts/jsdoc/config.json b/scripts/jsdoc/config.json new file mode 100644 index 0000000000..0fb833d015 --- /dev/null +++ b/scripts/jsdoc/config.json @@ -0,0 +1,8 @@ +{ + "templates": { + "default": { + "outputSourceFiles": false + } + }, + "plugins": ["plugins/hifi"] +} diff --git a/scripts/jsdoc/plugins/hifi.js b/scripts/jsdoc/plugins/hifi.js new file mode 100644 index 0000000000..fde4183db8 --- /dev/null +++ b/scripts/jsdoc/plugins/hifi.js @@ -0,0 +1,40 @@ +function endsWith(path, exts) { + var result = false; + exts.forEach(function(ext) { + if (path.endsWith(ext)) { + result = true; + } + }); + return result; +} + +exports.handlers = { + beforeParse: function(e) { + console.log("Scanning hifi source for jsdoc comments..."); + + // directories to scan for jsdoc comments + var dirList = [ + '../../interface/src', + '../../libraries/script-engine/src', + '../../libraries/networking/src', + '../../libraries/animation/src' + ]; + var exts = ['.h', '.cpp']; + + const fs = require('fs'); + dirList.forEach(function (dir) { + var files = fs.readdirSync(dir) + files.forEach(function (file) { + var path = dir + "/" + file; + if (fs.lstatSync(path).isFile() && endsWith(path, exts)) { + var data = fs.readFileSync(path, "utf8"); + 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'); + } + } + }); + }); + } +}; diff --git a/scripts/jsdoc/root.js b/scripts/jsdoc/root.js new file mode 100644 index 0000000000..097403f723 --- /dev/null +++ b/scripts/jsdoc/root.js @@ -0,0 +1,11 @@ +// +// root.js +// +// Copyright 2016 High Fidelity, Inc. +// +// Distributed under the Apache License, Version 2.0. +// See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html +// +// Root of High Fidelity generated java script documentation +// + From 839b1a3c5e872c806a809c2b61676b0f3c731be0 Mon Sep 17 00:00:00 2001 From: "Anthony J. Thibault" Date: Wed, 9 Nov 2016 18:09:10 -0800 Subject: [PATCH 2/4] Added some jsdoc comments to the C++ source --- .../src/scripting/AccountScriptingInterface.h | 23 +++++ libraries/animation/src/AnimationCache.h | 12 +++ libraries/networking/src/ResourceCache.h | 86 ++++++++++++++++++- .../src/AssetScriptingInterface.h | 47 ++++++++++ 4 files changed, 167 insertions(+), 1 deletion(-) diff --git a/interface/src/scripting/AccountScriptingInterface.h b/interface/src/scripting/AccountScriptingInterface.h index 0f958f2286..748f110356 100644 --- a/interface/src/scripting/AccountScriptingInterface.h +++ b/interface/src/scripting/AccountScriptingInterface.h @@ -19,12 +19,35 @@ class AccountScriptingInterface : public QObject { Q_PROPERTY(QString username READ getUsername NOTIFY usernameChanged) + /**jsdoc + * @namespace Account + * @property username {String} username if user is logged in, otherwise it returns "Unknown user" + */ + signals: + + /**jsdoc + * Triggered when username has changed. + * @function Account.usernameChanged + * @return {Signal} + */ void usernameChanged(); public slots: static AccountScriptingInterface* getInstance(); + + /**jsdoc + * Returns the username for the currently logged in High Fidelity metaverse account. + * @function Account.getUsername + * @return {string} username if user is logged in, otherwise it returns "Unknown user" + */ QString getUsername(); + + /**jsdoc + * Determine if the user is logged into the High Fidleity metaverse. + * @function Account.isLoggedIn + * @return {bool} true when user is logged into the High Fidelity metaverse. + */ bool isLoggedIn(); bool checkAndSignalForAccessToken(); }; diff --git a/libraries/animation/src/AnimationCache.h b/libraries/animation/src/AnimationCache.h index a7d8700fed..59e3de9bcb 100644 --- a/libraries/animation/src/AnimationCache.h +++ b/libraries/animation/src/AnimationCache.h @@ -29,7 +29,19 @@ class AnimationCache : public ResourceCache, public Dependency { Q_OBJECT SINGLETON_DEPENDENCY + /**jsdoc + * @namespace AnimationCache + * @augments ResourceCache + */ + public: + + /**jsdoc + * Returns animation resource for particular animation + * @function AnimationCache.getAnimation + * @param url {string} url to load + * @return {Resource} animation + */ Q_INVOKABLE AnimationPointer getAnimation(const QString& url) { return getAnimation(QUrl(url)); } Q_INVOKABLE AnimationPointer getAnimation(const QUrl& url); diff --git a/libraries/networking/src/ResourceCache.h b/libraries/networking/src/ResourceCache.h index eba84dddd4..48b21a1e98 100644 --- a/libraries/networking/src/ResourceCache.h +++ b/libraries/networking/src/ResourceCache.h @@ -88,7 +88,24 @@ class ScriptableResource : public QObject { Q_PROPERTY(QUrl url READ getUrl) Q_PROPERTY(int state READ getState NOTIFY stateChanged) + /**jsdoc + * @constructor Resource + * @property url {string} url of this resource + * @property state {Resource.State} current loading state + */ + public: + + /**jsdoc + * @name Resource.State + * @static + * @property QUEUED {int} The resource is queued up, waiting to be loaded. + * @property LOADING {int} The resource is downloading + * @property LOADED {int} The resource has finished downloaded by is not complete + * @property FINISHED {int} The resource has completly finished loading and is ready. + * @property FAILED {int} Downloading the resource has failed. + */ + enum State { QUEUED, LOADING, @@ -101,6 +118,10 @@ public: ScriptableResource(const QUrl& url); virtual ~ScriptableResource() = default; + /**jsdoc + * Release this resource + * @function Resource#release + */ Q_INVOKABLE void release(); const QUrl& getUrl() const { return _url; } @@ -111,7 +132,22 @@ public: void setInScript(bool isInScript); signals: + + /**jsdoc + * Signaled when download progress for this resource has changed + * @function Resource#progressChanged + * @param bytesReceived {int} bytes downloaded so far + * @param bytesTotal {int} total number of bytes in the resource + * @returns {Signal} + */ void progressChanged(uint64_t bytesReceived, uint64_t bytesTotal); + + /**jsdoc + * Signaled when resource loading state has changed + * @function Resource#stateChanged + * @param bytesReceived {Resource.State} new state + * @returns {Signal} + */ void stateChanged(int state); protected: @@ -148,14 +184,49 @@ class ResourceCache : public QObject { Q_PROPERTY(size_t numCached READ getNumCachedResources NOTIFY dirty) Q_PROPERTY(size_t sizeTotal READ getSizeTotalResources NOTIFY dirty) Q_PROPERTY(size_t sizeCached READ getSizeCachedResources NOTIFY dirty) - + + /**jsdoc + * @namespace ResourceCache + * @property numTotal {number} total number of total resources + * @property numCached {number} total number of cached resource + * @property sizeTotal {number} size in bytes of all resources + * @property sizeCached {number} size in bytes of all cached resources + */ + public: + /**jsdoc + * Returns the total number of resources + * @function ResourceCache.getNumTotalResources + * @return {number} + */ size_t getNumTotalResources() const { return _numTotalResources; } + + /**jsdoc + * Returns the total size in bytes of all resources + * @function ResourceCache.getSizeTotalResources + * @return {number} + */ size_t getSizeTotalResources() const { return _totalResourcesSize; } + /**jsdoc + * Returns the total number of cached resources + * @function ResourceCache.getNumCachedResources + * @return {number} + */ size_t getNumCachedResources() const { return _numUnusedResources; } + + /**jsdoc + * Returns the total size in bytes of cached resources + * @function ResourceCache.getSizeCachedResources + * @return {number} + */ size_t getSizeCachedResources() const { return _unusedResourcesSize; } + /**jsdoc + * Returns list of all resource urls + * @function ResourceCache.getResourceList + * @return {string[]} + */ Q_INVOKABLE QVariantList getResourceList(); static void setRequestLimit(int limit); @@ -192,6 +263,13 @@ protected slots: /// returns an empty smart pointer and loads its asynchronously. /// \param fallback a fallback URL to load if the desired one is unavailable /// \param extra extra data to pass to the creator, if appropriate + /**jsdoc + * Asynchronously loads a resource from the spedified URL and returns it. + * @param url {string} url of resource to load + * @param fallback {string} fallback URL if load of the desired url fails + * @function ResourceCache.getResource + * @return {Resource} + */ QSharedPointer getResource(const QUrl& url, const QUrl& fallback = QUrl(), void* extra = NULL); @@ -203,6 +281,12 @@ protected: // Pointers created through this method should be owned by the caller, // which should be a QScriptEngine with ScriptableResource registered, so that // the QScriptEngine will delete the pointer when it is garbage collected. + /**jsdoc + * Prefetches a resource. + * @param url {string} url of resource to load + * @function ResourceCache.prefetch + * @return {Resource} + */ Q_INVOKABLE ScriptableResource* prefetch(const QUrl& url) { return prefetch(url, nullptr); } /// Creates a new resource. diff --git a/libraries/script-engine/src/AssetScriptingInterface.h b/libraries/script-engine/src/AssetScriptingInterface.h index 82d220ab34..d8bc319256 100644 --- a/libraries/script-engine/src/AssetScriptingInterface.h +++ b/libraries/script-engine/src/AssetScriptingInterface.h @@ -19,13 +19,60 @@ #include +/**jsdoc + * @namespace Assets + */ class AssetScriptingInterface : public QObject { Q_OBJECT public: AssetScriptingInterface(QScriptEngine* engine); + /**jsdoc + * Upload content to the connected domain's asset server. + * @function Assets.uploadData + * @static + * @param data {string} content to upload + * @param callback {Assets~uploadDataCallback} called when upload is complete + */ + + /**jsdoc + * Called when uploadData is complete + * @callback Assets~uploadDataCallback + * @param {string} url + * @param {string} hash + */ + Q_INVOKABLE void uploadData(QString data, QScriptValue callback); + + /**jsdoc + * Download data from the connected domain's asset server. + * @function Assets.downloadData + * @static + * @param url {string} url of asset to download, must be atp scheme url. + * @param callback {Assets~downloadDataCallback} + */ + + /**jsdoc + * Called when downloadData is complete + * @callback Assets~downloadDataCallback + * @param data {string} content that was downloaded + */ + Q_INVOKABLE void downloadData(QString url, QScriptValue downloadComplete); + + /**jsdoc + * Sets up a path to hash mapping within the connected domain's asset server + * @function Assets.setMapping + * @static + * @param path {string} + * @param hash {string} + * @param callback {Assets~setMappingCallback} + */ + + /**jsdoc + * Called when setMapping is complete + * @callback Assets~setMappingCallback + */ Q_INVOKABLE void setMapping(QString path, QString hash, QScriptValue callback); #if (PR_BUILD || DEV_BUILD) From 940edd4a6d2c2b3f8682c0d09d2836e45abc8e0d Mon Sep 17 00:00:00 2001 From: "Anthony J. Thibault" Date: Wed, 9 Nov 2016 18:09:42 -0800 Subject: [PATCH 3/4] Added interface/src/scripting dir to doc search path --- scripts/jsdoc/plugins/hifi.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/jsdoc/plugins/hifi.js b/scripts/jsdoc/plugins/hifi.js index fde4183db8..8016aa2ae5 100644 --- a/scripts/jsdoc/plugins/hifi.js +++ b/scripts/jsdoc/plugins/hifi.js @@ -15,9 +15,10 @@ exports.handlers = { // directories to scan for jsdoc comments var dirList = [ '../../interface/src', + '../../interface/src/scripting', '../../libraries/script-engine/src', '../../libraries/networking/src', - '../../libraries/animation/src' + '../../libraries/animation/src', ]; var exts = ['.h', '.cpp']; From d111f7c4099528e8d7a6a5dc748626d129cf7844 Mon Sep 17 00:00:00 2001 From: "Anthony J. Thibault" Date: Thu, 10 Nov 2016 09:33:56 -0800 Subject: [PATCH 4/4] Moved jsdoc folder from scripts to tools directory --- {scripts => tools}/jsdoc/.gitignore | 0 {scripts => tools}/jsdoc/README.md | 0 {scripts => tools}/jsdoc/config.json | 0 {scripts => tools}/jsdoc/plugins/hifi.js | 0 {scripts => tools}/jsdoc/root.js | 0 5 files changed, 0 insertions(+), 0 deletions(-) rename {scripts => tools}/jsdoc/.gitignore (100%) rename {scripts => tools}/jsdoc/README.md (100%) rename {scripts => tools}/jsdoc/config.json (100%) rename {scripts => tools}/jsdoc/plugins/hifi.js (100%) rename {scripts => tools}/jsdoc/root.js (100%) diff --git a/scripts/jsdoc/.gitignore b/tools/jsdoc/.gitignore similarity index 100% rename from scripts/jsdoc/.gitignore rename to tools/jsdoc/.gitignore diff --git a/scripts/jsdoc/README.md b/tools/jsdoc/README.md similarity index 100% rename from scripts/jsdoc/README.md rename to tools/jsdoc/README.md diff --git a/scripts/jsdoc/config.json b/tools/jsdoc/config.json similarity index 100% rename from scripts/jsdoc/config.json rename to tools/jsdoc/config.json diff --git a/scripts/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js similarity index 100% rename from scripts/jsdoc/plugins/hifi.js rename to tools/jsdoc/plugins/hifi.js diff --git a/scripts/jsdoc/root.js b/tools/jsdoc/root.js similarity index 100% rename from scripts/jsdoc/root.js rename to tools/jsdoc/root.js