From 839b1a3c5e872c806a809c2b61676b0f3c731be0 Mon Sep 17 00:00:00 2001 From: "Anthony J. Thibault" Date: Wed, 9 Nov 2016 18:09:10 -0800 Subject: [PATCH] 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)