Merge pull request #16005 from ctrlaltdavid/DOC-61

DOC-61: Render API JSDoc

interface/src/scripting/RenderScriptingInterface.h

@@ -15,13 +15,20 @@
 #include "RenderForward.h"
 
 /**jsdoc
- * The <code>Render</code> API allows you to configure the graphics engine
+ * The <code>Render</code> API enables you to configure the graphics engine.
  *
  * @namespace Render
  *
  * @hifi-interface
  * @hifi-client-entity
  * @hifi-avatar
+ *
+ * @property {Render.RenderMethod} renderMethod - The render method being used.
+ * @property {boolean} shadowsEnabled - <code>true</code> if shadows are enabled, <code>false</code> if they're disabled.
+ * @property {boolean} ambientOcclusionEnabled - <code>true</code> if ambient occlusion is enabled, <code>false</code> if it's 
+ *     disabled.
+ * @property {boolean} antialiasingEnabled - <code>true</code> if anti-aliasing is enabled, <code>false</code> if it's disabled.
+ * @property {number} viewportResolutionScale - The view port resolution scale, <code>&gt; 0.0</code>.
  */
 class RenderScriptingInterface : public QObject {
     Q_OBJECT
@@ -36,6 +43,21 @@ public:
 
     static RenderScriptingInterface* getInstance();
 
+    /**jsdoc
+     * <p>The rendering method is specified by the following values:</p>
+     * <table>
+     *   <thead>
+     *     <tr><th>Value</th><th>Name</th><th>Description</th>
+     *   </thead>
+     *   <tbody>
+     *     <tr><td><code>0</code></td><td>DEFERRED</td><td>More complex rendering pipeline where lighting is applied to the 
+     *       scene as a whole after all objects have been rendered.</td></tr>
+     *     <tr><td><code>1</code></td><td>FORWARD</td><td>Simpler rendering pipeline where each object in the scene, in turn, 
+     *       is rendered and has lighting applied.</td></tr>
+     *   </tbody>
+     * </table>
+     * @typedef {number} Render.RenderMethod
+     */
     // RenderMethod enum type
     enum class RenderMethod {
         DEFERRED = render::Args::RenderMethod::DEFERRED,
@@ -52,95 +74,114 @@ public:
 
 public slots:
     /**jsdoc
-     * Get a config for a job by name
+     * Gets the configuration for a rendering job by name.
+     * <p><strong>Warning:</strong> For internal, debugging purposes. Subject to change.</p>
      * @function Render.getConfig
-     * @param {string} name - Can be:
+     * @param {string} name - The name of the rendering job.
-     *     - <job_name>: Search for the first job named job_name traversing the the sub graph of task and jobs (from this task as root)
+     * @returns {object} The configuration for the rendering job.
-     *     - <parent_name>.[<sub_parent_names>.]<job_name>:  Allows you to first look for the parent_name job (from this task as root) and then search from there for the
-     *    optional sub_parent_names and finally from there looking for the job_name (assuming every job in the path is found)
-     * @returns {object} The sub job config.
      */
     QObject* getConfig(const QString& name) { return qApp->getRenderEngine()->getConfiguration()->getConfig(name); }
 
+
     /**jsdoc
-     * Gets the current render method
+     * Gets the render method being used.
      * @function Render.getRenderMethod
-     * @returns {number} <code>"DEFERRED"</code> or <code>"FORWARD"</code>
+     * @returns {Render.RenderMethod} The render method being used.
+     * @example <caption>Report the current render method.</caption>
+     * var renderMethod = Render.getRenderMethod();
+     * print("Current render method: " + Render.getRenderMethodNames()[renderMethod]);
      */
     RenderMethod getRenderMethod() const;
 
     /**jsdoc
-     * Sets the current render method
+     * Sets the render method to use.
      * @function Render.setRenderMethod
-     * @param {number} renderMethod - <code>"DEFERRED"</code> or <code>"FORWARD"</code>
+     * @param {Render.RenderMethod} renderMethod - The render method to use.
      */
     void setRenderMethod(RenderMethod renderMethod);
 
     /**jsdoc
-    * Gets the possible enum names of the RenderMethod type
+     * Gets the names of the possible render methods, per {@link Render.RenderMethod}.
-    * @function Render.getRenderMethodNames
+     * @function Render.getRenderMethodNames
-    * @returns [string] [ <code>"DEFERRED"</code>, <code>"FORWARD"</code> ]
+     * @returns {string[]} The names of the possible render methods.
-    */
+     * @example <caption>Report the names of the possible render methods.</caption>
+     * var renderMethods = Render.getRenderMethodNames();
+     * print("Render methods:");
+     * for (var i = 0; i < renderMethods.length; i++) {
+     *     print("- " + renderMethods[i]);
+     * }
+     */
     QStringList getRenderMethodNames() const;
 
 
     /**jsdoc
-     * Whether or not shadows are enabled
+     * Gets whether or not shadows are enabled.
      * @function Render.getShadowsEnabled
-     * @returns {bool} <code>true</code> if shadows are enabled, otherwise <code>false</code>
+     * @returns {boolean} <code>true</code> if shadows are enabled, <code>false</code> if they're disabled.
      */
     bool getShadowsEnabled() const;
 
     /**jsdoc
-     * Enables or disables shadows
+     * Sets whether or not shadows are enabled.
      * @function Render.setShadowsEnabled
-     * @param {bool} enabled - <code>true</code> to enable shadows, <code>false</code> to disable them
+     * @param {boolean} enabled - <code>true</code> to enable shadows, <code>false</code> to disable.
      */
     void setShadowsEnabled(bool enabled);
 
     /**jsdoc
-     * Whether or not ambient occlusion is enabled
+     * Gets whether or not ambient occlusion is enabled.
      * @function Render.getAmbientOcclusionEnabled
-     * @returns {bool} <code>true</code> if ambient occlusion is enabled, otherwise <code>false</code>
+     * @returns {boolean} <code>true</code> if ambient occlusion is enabled, <code>false</code> if it's disabled.
      */
     bool getAmbientOcclusionEnabled() const;
 
     /**jsdoc
-     * Enables or disables ambient occlusion
+     * Sets whether or not ambient occlusion is enabled.
      * @function Render.setAmbientOcclusionEnabled
-     * @param {bool} enabled - <code>true</code> to enable ambient occlusion, <code>false</code> to disable it
+     * @param {boolean} enabled - <code>true</code> to enable ambient occlusion, <code>false</code> to disable.
      */
     void setAmbientOcclusionEnabled(bool enabled);
 
     /**jsdoc
-     * Whether or not anti-aliasing is enabled
+     * Gets whether or not anti-aliasing is enabled.
      * @function Render.getAntialiasingEnabled
-     * @returns {bool} <code>true</code> if anti-aliasing is enabled, otherwise <code>false</code>
+     * @returns {boolean} <code>true</code> if anti-aliasing is enabled, <code>false</code> if it's disabled.
      */
     bool getAntialiasingEnabled() const;
 
     /**jsdoc
-     * Enables or disables anti-aliasing
+     * Sets whether or not anti-aliasing is enabled.
      * @function Render.setAntialiasingEnabled
-     * @param {bool} enabled - <code>true</code> to enable anti-aliasing, <code>false</code> to disable it
+     * @param {boolean} enabled - <code>true</code> to enable anti-aliasing, <code>false</code> to disable.
      */
     void setAntialiasingEnabled(bool enabled);
 
     /**jsdoc
-     * Gets the current viewport resolution scale
+     * Gets the view port resolution scale.
      * @function Render.getViewportResolutionScale
-     * @returns {number} 
+     * @returns {number} The view port resolution scale, <code>&gt; 0.0</code>.
      */
     float getViewportResolutionScale() const;
 
     /**jsdoc
-     * Sets the current viewport resolution scale
+     * Sets the view port resolution scale.
      * @function Render.setViewportResolutionScale
-     * @param {number} resolutionScale - between epsilon and 1.0
+     * @param {number} resolutionScale - The view port resolution scale to set, <code>&gt; 0.0</code>.
      */
     void setViewportResolutionScale(float resolutionScale);
 
 signals:
+    
+    /**jsdoc
+     * Triggered when one of the <code>Render</code> API's properties changes.
+     * @function Render.settingsChanged
+     * @returns {Signal}
+     * @example <caption>Report when a render setting changes.</caption>
+     * Render.settingsChanged.connect(function () {
+     *     print("Render setting changed");
+     * });
+     * // Toggle Developer > Render > Shadows or similar to trigger.
+     */
     void settingsChanged();
 
 private:

libraries/avatars/src/AvatarData.h

@@ -117,8 +117,7 @@ const int COLLIDE_WITH_OTHER_AVATARS = 11; // 12th bit
 const int HAS_HERO_PRIORITY = 12; // 13th bit  (be scared)
 
 /**jsdoc
- * <p>The pointing state of the hands is specified by the following values:
+ * <p>The pointing state of the hands is specified by the following values:</p>
- </p>
  * <table>
  *   <thead>
  *     <tr><th>Value</th><th>Description</th>

libraries/task/src/task/Config.h

@@ -109,14 +109,14 @@ public:
     virtual void setPresetList(const QJsonObject& object);
 
     /**jsdoc
-     * @function Render.toJSON
+     * @function Workload.toJSON
      * @returns {string}
      */
     // This must be named toJSON to integrate with the global scripting JSON object
     Q_INVOKABLE QString toJSON() { return QJsonDocument(toJsonValue(*this).toObject()).toJson(QJsonDocument::Compact); }
 
     /**jsdoc
-     * @function Render.load
+     * @function Workload.load
      * @param {object} map
      */
     Q_INVOKABLE void load(const QVariantMap& map) { qObjectFromJsonValue(QJsonObject::fromVariantMap(map), *this); emit loaded(); }
@@ -130,25 +130,25 @@ public:
 
     // Describe the node graph data connections of the associated Job/Task
     /**jsdoc
-     * @function Render.isTask
+     * @function Workload.isTask
      * @returns {boolean}
      */
     Q_INVOKABLE virtual bool isTask() const { return false; }
 
     /**jsdoc
-     * @function Render.getSubConfigs
+     * @function Workload.getSubConfigs
      * @returns {object[]}
      */
     Q_INVOKABLE virtual QObjectList getSubConfigs() const { return QObjectList(); }
 
     /**jsdoc
-     * @function Render.getNumSubs
+     * @function Workload.getNumSubs
      * @returns {number}
      */
     Q_INVOKABLE virtual int getNumSubs() const { return 0; }
 
     /**jsdoc
-     * @function Render.getSubConfig
+     * @function Workload.getSubConfig
      * @param {number} index
      * @returns {object}
      */
@@ -162,32 +162,32 @@ public:
 public slots:
 
     /**jsdoc
-     * @function Render.load
+     * @function Workload.load
      * @param {object} map
      */
     void load(const QJsonObject& val) { qObjectFromJsonValue(val, *this); emit loaded(); }
 
     /**jsdoc
-     * @function Render.refresh
+     * @function Workload.refresh
      */
     void refresh();
 
 signals:
 
     /**jsdoc
-     * @function Render.loaded
+     * @function Workload.loaded
      * @returns {Signal}
      */
     void loaded();
 
     /**jsdoc
-     * @function Render.newStats
+     * @function Workload.newStats
      * @returns {Signal}
      */
     void newStats();
 
     /**jsdoc
-     * @function Render.dirtyEnabled
+     * @function Workload.dirtyEnabled
      * @returns {Signal}
      */
     void dirtyEnabled();
@@ -202,7 +202,7 @@ public:
 
 
 /**jsdoc
- * @namespace Render
+ * @namespace Workload
  *
  * @hifi-interface
  * @hifi-client-entity
@@ -221,7 +221,7 @@ public:
     TaskConfig(bool enabled) : JobConfig(enabled) {}
 
     /**jsdoc
-     * @function Render.getConfig
+     * @function Workload.getConfig
      * @param {string} name
      * @returns {object}
      */