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) diff --git a/tools/jsdoc/.gitignore b/tools/jsdoc/.gitignore new file mode 100644 index 0000000000..c585e19389 --- /dev/null +++ b/tools/jsdoc/.gitignore @@ -0,0 +1 @@ +out \ No newline at end of file diff --git a/tools/jsdoc/README.md b/tools/jsdoc/README.md new file mode 100644 index 0000000000..c43f95cabe --- /dev/null +++ b/tools/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/tools/jsdoc/config.json b/tools/jsdoc/config.json new file mode 100644 index 0000000000..0fb833d015 --- /dev/null +++ b/tools/jsdoc/config.json @@ -0,0 +1,8 @@ +{ + "templates": { + "default": { + "outputSourceFiles": false + } + }, + "plugins": ["plugins/hifi"] +} diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js new file mode 100644 index 0000000000..8016aa2ae5 --- /dev/null +++ b/tools/jsdoc/plugins/hifi.js @@ -0,0 +1,41 @@ +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', + '../../interface/src/scripting', + '../../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/tools/jsdoc/root.js b/tools/jsdoc/root.js new file mode 100644 index 0000000000..097403f723 --- /dev/null +++ b/tools/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 +// +