Fix up Resource and resource cache APIs' JSDoc

libraries/animation/src/AnimationCache.h

@@ -70,7 +70,7 @@ public:
      * @function AnimationCache.prefetch
      * @param {string} url - URL of the resource to prefetch.
      * @param {object} [extra=null]
-     * @returns {Resource}
+     * @returns {ResourceObject}
      */
 
     /**jsdoc
@@ -79,7 +79,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]
-     * @returns {Resource}
+     * @returns {object}
      */
 
 
@@ -87,7 +87,7 @@ public:
      * Returns animation resource for particular animation.
      * @function AnimationCache.getAnimation
      * @param {string} url - URL to load.
-     * @returns {Resource} animation
+     * @returns {AnimationObject} animation
      */
     Q_INVOKABLE AnimationPointer getAnimation(const QString& url) { return getAnimation(QUrl(url)); }
     Q_INVOKABLE AnimationPointer getAnimation(const QUrl& url);
@@ -104,6 +104,17 @@ private:
 
 Q_DECLARE_METATYPE(AnimationPointer)
 
+/**jsdoc
+ * @class AnimationObject
+ *
+ * @hifi-interface
+ * @hifi-client-entity
+ * @hifi-server-entity
+ * @hifi-assignment-client
+ *
+ * @property {string[]} jointNames
+ * @property {FBXAnimationFrame[]} frames
+ */
 /// An animation loaded from the network.
 class Animation : public Resource {
     Q_OBJECT
@@ -118,9 +129,16 @@ public:
 
     virtual bool isLoaded() const override;
 
-    
+    /**jsdoc
+     * @function AnimationObject.getJointNames
+     * @returns {string[]}
+     */
     Q_INVOKABLE QStringList getJointNames() const;
     
+    /**jsdoc
+     * @function AnimationObject.getFrames
+     * @returns {FBXAnimationFrame[]}
+     */
     Q_INVOKABLE QVector<FBXAnimationFrame> getFrames() const;
 
     const QVector<FBXAnimationFrame>& getFramesReference() const;

libraries/audio/src/Sound.h

@@ -77,6 +77,17 @@ private:
 
 typedef QSharedPointer<Sound> SharedSoundPointer;
 
+/**jsdoc
+ * @class SoundObject
+ * 
+ * @hifi-interface
+ * @hifi-client-entity
+ * @hifi-server-entity
+ * @hifi-assignment-client
+ *
+ * @property {boolean} downloaded
+ * @property {number} duration
+ */
 class SoundScriptingInterface : public QObject {
     Q_OBJECT
 
@@ -90,6 +101,10 @@ public:
     bool isReady() const { return _sound->isReady(); }
     float getDuration() { return _sound->getDuration(); }
 
+/**jsdoc
+ * @function SoundObject.ready
+ * @returns {Signal}
+ */
 signals:
     void ready();
 

libraries/audio/src/SoundCache.h

@@ -64,7 +64,7 @@ public:
      * @function SoundCache.prefetch
      * @param {string} url - URL of the resource to prefetch.
      * @param {object} [extra=null]
-     * @returns {Resource}
+     * @returns {ResourceObject}
      */
 
     /**jsdoc
@@ -73,14 +73,14 @@ 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]
-     * @returns {Resource}
+     * @returns {object}
      */
 
 
     /**jsdoc 
      * @function SoundCache.getSound
      * @param {string} url
-     * @returns {object}
+     * @returns {SoundObject}
      */
     Q_INVOKABLE SharedSoundPointer getSound(const QUrl& url);
 protected:

libraries/fbx/src/FBX.h

@@ -256,6 +256,11 @@ public:
     QHash<QString, size_t> texcoordSetMap;
 };
 
+/**jsdoc
+ * @typedef {object} FBXAnimationFrame
+ * @property {Quat[]} rotations
+ * @property {Vec3[]} translations
+ */
 /// A single animation frame extracted from an FBX document.
 class FBXAnimationFrame {
 public:

libraries/model-networking/src/model-networking/ModelCache.h

@@ -179,7 +179,7 @@ public:
      * @function ModelCache.prefetch
      * @param {string} url - URL of the resource to prefetch.
      * @param {object} [extra=null]
-     * @returns {Resource}
+     * @returns {ResourceObject}
      */
 
     /**jsdoc
@@ -188,7 +188,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]
-     * @returns {Resource}
+     * @returns {object}
      */
 
 

libraries/model-networking/src/model-networking/TextureCache.h

@@ -195,7 +195,7 @@ public:
      * @function TextureCache.prefetch
      * @param {string} url - URL of the resource to prefetch.
      * @param {object} [extra=null]
-     * @returns {Resource}
+     * @returns {ResourceObject}
      */
 
     /**jsdoc
@@ -204,7 +204,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]
-     * @returns {Resource}
+     * @returns {object}
      */
 
 
@@ -261,7 +261,7 @@ protected:
      * @param {string} url
      * @param {number} type
      * @param {number} [maxNumPixels=67108864]
-     * @returns {Resource}
+     * @returns {ResourceObject}
      */
     // 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);

libraries/networking/src/ResourceCache.h

@@ -87,7 +87,7 @@ private:
 class ScriptableResource : public QObject {
 
     /**jsdoc
-     * @constructor Resource
+     * @class ResourceObject
      *
      * @hifi-interface
      * @hifi-client-entity
@@ -97,11 +97,6 @@ class ScriptableResource : public QObject {
      * @property {string} url - URL of this resource.
      * @property {Resource.State} state - Current loading state.
      */
-    /**jsdoc
-     * @namespace Resource
-     * @variation 0
-     * @property {Resource.State} State
-     */
     Q_OBJECT
     Q_PROPERTY(QUrl url READ getURL)
     Q_PROPERTY(int state READ getState NOTIFY stateChanged)
@@ -109,8 +104,7 @@ class ScriptableResource : public QObject {
 public:
 
     /**jsdoc
-     * @name Resource.State
-     * @static
+     * @typedef {object} Resource.State
      * @property {number} QUEUED - The resource is queued up, waiting to be loaded.
      * @property {number} LOADING - The resource is downloading.
      * @property {number} LOADED - The resource has finished downloaded by is not complete.
@@ -131,7 +125,7 @@ public:
 
     /**jsdoc
      * Release this resource.
-     * @function Resource#release
+     * @function ResourceObject#release
      */
     Q_INVOKABLE void release();
 
@@ -146,7 +140,7 @@ signals:
 
     /**jsdoc
      * Triggered when download progress for this resource has changed.
-     * @function Resource#progressChanged
+     * @function ResourceObject#progressChanged
      * @param {number} bytesReceived - Byytes downloaded so far.
      * @param {number} bytesTotal - Total number of bytes in the resource.
      * @returns {Signal}
@@ -155,7 +149,7 @@ signals:
 
     /**jsdoc
      * Triggered when resource loading state has changed.
-     * @function Resource#stateChanged
+     * @function ResourceObject#stateChanged
      * @param {Resource.State} state - New state.
      * @returns {Signal}
      */
@@ -262,7 +256,7 @@ protected slots:
      * @function ResourceCache.prefetch
      * @param {string} url - URL of the resource to prefetch.
      * @param {object} [extra=null]
-     * @returns {Resource}
+     * @returns {ResourceObject}
      */
     // Prefetches a resource to be held by the QScriptEngine.
     // Left as a protected member so subclasses can overload prefetch
@@ -275,8 +269,9 @@ 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]
-     * @returns {Resource}
+     * @returns {object}
      */
+    // FIXME: The return type is not recognized by JavaScript.
     /// Loads a resource from the specified URL and returns it.
     /// If the caller is on a different thread than the ResourceCache,
     /// returns an empty smart pointer and loads its asynchronously.

libraries/script-engine/src/ScriptEngine.cpp

@@ -558,6 +558,16 @@ static void scriptableResourceFromScriptValue(const QScriptValue& value, Scripta
     resource = static_cast<ScriptableResourceRawPtr>(value.toQObject());
 }
 
+/**jsdoc
+ * @namespace Resource
+ *
+ * @hifi-interface
+ * @hifi-client-entity
+ * @hifi-server-entity
+ * @hifi-assignment-client
+ *
+ * @property {Resource.State} State
+ */
 static QScriptValue createScriptableResourcePrototype(ScriptEnginePointer engine) {
     auto prototype = engine->newObject();
 

tools/jsdoc/plugins/hifi.js

@@ -45,6 +45,7 @@ exports.handlers = {
             '../../libraries/controllers/src/controllers/impl/',
             '../../libraries/display-plugins/src/display-plugins/',
             '../../libraries/entities/src',
+            '../../libraries/fbx/src',
             '../../libraries/graphics/src/graphics/',
             '../../libraries/graphics-scripting/src/graphics-scripting/',
             '../../libraries/input-plugins/src/input-plugins',