From 48632be3c2760725d6376f03e227045a1d7220b4 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 2 May 2018 16:12:48 +1200 Subject: [PATCH 1/2] Fix up cache APIs' JSDoc --- libraries/animation/src/AnimationCache.h | 30 +++---- libraries/audio/src/SoundCache.h | 20 ++--- .../src/model-networking/ModelCache.h | 18 ++--- .../src/model-networking/TextureCache.h | 81 +++++++++---------- libraries/networking/src/ResourceCache.h | 18 ++--- 5 files changed, 70 insertions(+), 97 deletions(-) diff --git a/libraries/animation/src/AnimationCache.h b/libraries/animation/src/AnimationCache.h index 03b37aef2f..103b620254 100644 --- a/libraries/animation/src/AnimationCache.h +++ b/libraries/animation/src/AnimationCache.h @@ -43,45 +43,39 @@ public: * @property {number} sizeCached - Size in bytes of all cached resources. Read-only. */ - // Functions are copied over from ResourceCache (see ResourceCache.h for reason). + // Functions are copied over from ResourceCache (see ResourceCache.h for reason). - /**jsdoc + /**jsdoc * Get the list of all resource URLs. * @function AnimationCache.getResourceList - * @return {string[]} + * @returns {string[]} */ - /**jsdoc + /**jsdoc * @function AnimationCache.dirty * @returns {Signal} */ - /**jsdoc + /**jsdoc * @function AnimationCache.updateTotalSize * @param {number} deltaSize */ - /**jsdoc + /**jsdoc + * Prefetches a resource. * @function AnimationCache.prefetch - * @param {string} url - * @param {object} extra - * @returns {object} + * @param {string} url - URL of the resource to prefetch. + * @param {object} [extra=null] + * @returns {Resource} */ - /**jsdoc + /**jsdoc * Asynchronously loads a resource from the specified URL and returns it. * @function AnimationCache.getResource * @param {string} url - URL of the resource to load. * @param {string} [fallback=""] - Fallback URL if load of the desired URL fails. * @param {} [extra=null] - * @return {Resource} - */ - - /**jsdoc - * Prefetches a resource. - * @function AnimationCache.prefetch - * @param {string} url - URL of the resource to prefetch. - * @return {Resource} + * @returns {Resource} */ diff --git a/libraries/audio/src/SoundCache.h b/libraries/audio/src/SoundCache.h index d8c52635e0..039e815ff3 100644 --- a/libraries/audio/src/SoundCache.h +++ b/libraries/audio/src/SoundCache.h @@ -36,12 +36,12 @@ public: */ - // Functions are copied over from ResourceCache (see ResourceCache.h for reason). + // Functions are copied over from ResourceCache (see ResourceCache.h for reason). /**jsdoc * Get the list of all resource URLs. * @function SoundCache.getResourceList - * @return {string[]} + * @returns {string[]} */ /**jsdoc @@ -55,10 +55,11 @@ public: */ /**jsdoc + * Prefetches a resource. * @function SoundCache.prefetch - * @param {string} url - * @param {object} extra - * @returns {object} + * @param {string} url - URL of the resource to prefetch. + * @param {object} [extra=null] + * @returns {Resource} */ /**jsdoc @@ -67,14 +68,7 @@ public: * @param {string} url - URL of the resource to load. * @param {string} [fallback=""] - Fallback URL if load of the desired URL fails. * @param {} [extra=null] - * @return {Resource} - */ - - /**jsdoc - * Prefetches a resource. - * @function SoundCache.prefetch - * @param {string} url - URL of the resource to prefetch. - * @return {Resource} + * @returns {Resource} */ diff --git a/libraries/model-networking/src/model-networking/ModelCache.h b/libraries/model-networking/src/model-networking/ModelCache.h index 9532f39ce0..438c5e0d65 100644 --- a/libraries/model-networking/src/model-networking/ModelCache.h +++ b/libraries/model-networking/src/model-networking/ModelCache.h @@ -156,7 +156,7 @@ public: /**jsdoc * Get the list of all resource URLs. * @function ModelCache.getResourceList - * @return {string[]} + * @returns {string[]} */ /**jsdoc @@ -170,10 +170,11 @@ public: */ /**jsdoc + * Prefetches a resource. * @function ModelCache.prefetch - * @param {string} url - * @param {object} extra - * @returns {object} + * @param {string} url - URL of the resource to prefetch. + * @param {object} [extra=null] + * @returns {Resource} */ /**jsdoc @@ -182,14 +183,7 @@ public: * @param {string} url - URL of the resource to load. * @param {string} [fallback=""] - Fallback URL if load of the desired URL fails. * @param {} [extra=null] - * @return {Resource} - */ - - /**jsdoc - * Prefetches a resource. - * @function ModelCache.prefetch - * @param {string} url - URL of the resource to prefetch. - * @return {Resource} + * @returns {Resource} */ diff --git a/libraries/model-networking/src/model-networking/TextureCache.h b/libraries/model-networking/src/model-networking/TextureCache.h index 3f46dc3074..0c0dbeefa4 100644 --- a/libraries/model-networking/src/model-networking/TextureCache.h +++ b/libraries/model-networking/src/model-networking/TextureCache.h @@ -148,56 +148,50 @@ public: // Properties are copied over from ResourceCache (see ResourceCache.h for reason). /**jsdoc - * API to manage texture cache resources. - * @namespace TextureCache - * - * @property {number} numTotal - Total number of total resources. Read-only. - * @property {number} numCached - Total number of cached resource. Read-only. - * @property {number} sizeTotal - Size in bytes of all resources. Read-only. - * @property {number} sizeCached - Size in bytes of all cached resources. Read-only. - */ + * API to manage texture cache resources. + * @namespace TextureCache + * + * @property {number} numTotal - Total number of total resources. Read-only. + * @property {number} numCached - Total number of cached resource. Read-only. + * @property {number} sizeTotal - Size in bytes of all resources. Read-only. + * @property {number} sizeCached - Size in bytes of all cached resources. Read-only. + */ // Functions are copied over from ResourceCache (see ResourceCache.h for reason). - /**jsdoc - * Get the list of all resource URLs. - * @function TextureCache.getResourceList - * @return {string[]} - */ + /**jsdoc + * Get the list of all resource URLs. + * @function TextureCache.getResourceList + * @returns {string[]} + */ - /**jsdoc - * @function TextureCache.dirty - * @returns {Signal} - */ + /**jsdoc + * @function TextureCache.dirty + * @returns {Signal} + */ - /**jsdoc - * @function TextureCache.updateTotalSize - * @param {number} deltaSize - */ + /**jsdoc + * @function TextureCache.updateTotalSize + * @param {number} deltaSize + */ - /**jsdoc - * @function TextureCache.prefetch - * @param {string} url - * @param {object} extra - * @returns {object} - */ + /**jsdoc + * Prefetches a resource. + * @function TextureCache.prefetch + * @param {string} url - URL of the resource to prefetch. + * @param {object} [extra=null] + * @returns {Resource} + */ - /**jsdoc - * Asynchronously loads a resource from the specified URL and returns it. - * @function TextureCache.getResource - * @param {string} url - URL of the resource to load. - * @param {string} [fallback=""] - Fallback URL if load of the desired URL fails. - * @param {} [extra=null] - * @return {Resource} - */ - - /**jsdoc - * Prefetches a resource. - * @function TextureCache.prefetch - * @param {string} url - URL of the resource to prefetch. - * @return {Resource} - */ + /**jsdoc + * Asynchronously loads a resource from the specified URL and returns it. + * @function TextureCache.getResource + * @param {string} url - URL of the resource to load. + * @param {string} [fallback=""] - Fallback URL if load of the desired URL fails. + * @param {} [extra=null] + * @returns {Resource} + */ /// Returns the ID of the permutation/normal texture used for Perlin noise shader programs. This texture @@ -246,10 +240,11 @@ signals: protected: /**jsdoc - * @function TextureCache.prefect + * @function TextureCache.prefetch * @param {string} url * @param {number} type * @param {number} [maxNumPixels=67108864] + * @returns {Resource} */ // Overload ResourceCache::prefetch to allow specifying texture type for loads Q_INVOKABLE ScriptableResource* prefetch(const QUrl& url, int type, int maxNumPixels = ABSOLUTE_MAX_TEXTURE_NUM_PIXELS); diff --git a/libraries/networking/src/ResourceCache.h b/libraries/networking/src/ResourceCache.h index 609483bc56..8a77beefd4 100644 --- a/libraries/networking/src/ResourceCache.h +++ b/libraries/networking/src/ResourceCache.h @@ -209,7 +209,7 @@ public: /**jsdoc * Get the list of all resource URLs. * @function ResourceCache.getResourceList - * @return {string[]} + * @returns {string[]} */ Q_INVOKABLE QVariantList getResourceList(); @@ -251,10 +251,11 @@ protected slots: void updateTotalSize(const qint64& deltaSize); /**jsdoc + * Prefetches a resource. * @function ResourceCache.prefetch - * @param {string} url - * @param {object} extra - * @returns {object} + * @param {string} url - URL of the resource to prefetch. + * @param {object} [extra=null] + * @returns {Resource} */ // Prefetches a resource to be held by the QScriptEngine. // Left as a protected member so subclasses can overload prefetch @@ -267,7 +268,7 @@ protected slots: * @param {string} url - URL of the resource to load. * @param {string} [fallback=""] - Fallback URL if load of the desired URL fails. * @param {} [extra=null] - * @return {Resource} + * @returns {Resource} */ /// Loads a resource from the specified URL and returns it. /// If the caller is on a different thread than the ResourceCache, @@ -285,12 +286,7 @@ 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. - * @function ResourceCache.prefetch - * @param {string} url - URL of the resource to prefetch. - * @return {Resource} - */ + // JSDoc is provided on more general function signature. Q_INVOKABLE ScriptableResource* prefetch(const QUrl& url) { return prefetch(url, nullptr); } /// Creates a new resource. From 3febdcb141d540075c09739efae715d7543a1e14 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 2 May 2018 16:15:35 +1200 Subject: [PATCH 2/2] Miscellaneous JSDoc tidying --- interface/src/scripting/SelectionScriptingInterface.h | 6 +++--- .../src/graphics-scripting/GraphicsScriptingInterface.h | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/interface/src/scripting/SelectionScriptingInterface.h b/interface/src/scripting/SelectionScriptingInterface.h index 71ff41248a..86ececcbca 100644 --- a/interface/src/scripting/SelectionScriptingInterface.h +++ b/interface/src/scripting/SelectionScriptingInterface.h @@ -131,7 +131,7 @@ public: /**jsdoc * Get the names of all the selection lists. * @function Selection.getListNames - * @return {list[]} An array of names of all the selection lists. + * @returns {list[]} An array of names of all the selection lists. */ Q_INVOKABLE QStringList getListNames() const; @@ -181,7 +181,7 @@ public: * Get the list of avatars, entities, and overlays stored in a selection list. * @function Selection.getList * @param {string} listName - The name of the selection list. - * @return {Selection.SelectedItemsList} The content of a selection list. If the list name doesn't exist, the function + * @returns {Selection.SelectedItemsList} The content of a selection list. If the list name doesn't exist, the function * returns an empty object with no properties. */ Q_INVOKABLE QVariantMap getSelectedItemsList(const QString& listName) const; @@ -189,7 +189,7 @@ public: /**jsdoc * Get the names of the highlighted selection lists. * @function Selection.getHighlightedListNames - * @return {string[]} An array of names of the selection list currently highlight enabled. + * @returns {string[]} An array of names of the selection list currently highlight enabled. */ Q_INVOKABLE QStringList getHighlightedListNames() const; diff --git a/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.h b/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.h index 526352804b..e0bb39c855 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.h +++ b/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.h @@ -39,7 +39,7 @@ public slots: * * @function Graphics.getModel * @param {UUID} entityID - The objectID of the model whose meshes are to be retrieved. - * @return {Graphics.Model} the resulting Model object + * @returns {Graphics.Model} the resulting Model object */ scriptable::ScriptableModelPointer getModel(QUuid uuid); @@ -54,7 +54,7 @@ public slots: * * @function Graphics.newMesh * @param {Graphics.IFSData} ifsMeshData Index-Faced Set (IFS) arrays used to create the new mesh. - * @return {Graphics.Mesh} the resulting Mesh / Mesh Part object + * @returns {Graphics.Mesh} the resulting Mesh / Mesh Part object */ /**jsdoc * @typedef {object} Graphics.IFSData