Performance API JSDoc

interface/src/RefreshRateManager.cpp

@@ -19,7 +19,6 @@ static const int VR_TARGET_RATE = 90;
 
 /**jsdoc
  * <p>Refresh rate profile.</p>
- *
  * <table>
  *   <thead>
  *     <tr><th>Refresh Rate Profile</th><th>Description</th></tr>
@@ -32,15 +31,13 @@ static const int VR_TARGET_RATE = 90;
  *     <tr><td><code>"Realtime"</code></td><td>High refresh rate, even when Interface doesn't have focus or is minimized.
  *   </tbody>
  * </table>
- *
- * @typedef {string} RefreshRateProfile
+ * @typedef {string} RefreshRateProfileName
  */
 static const std::array<std::string, RefreshRateManager::RefreshRateProfile::PROFILE_NUM> REFRESH_RATE_PROFILE_TO_STRING =
     { { "Eco", "Interactive", "Realtime" } };
 
 /**jsdoc
  * <p>Interface states that affect the refresh rate.</p>
- *
  * <table>
  *   <thead>
  *     <tr><th>Refresh Rate Regime</th><th>Description</th></tr>
@@ -54,26 +51,23 @@ static const std::array<std::string, RefreshRateManager::RefreshRateProfile::PRO
  *     <tr><td><code>"ShutDown"</code></td><td>Interface is shutting down.</td></tr>
  *   </tbody>
  * </table>
- *
- * @typedef {string} RefreshRateRegime
+ * @typedef {string} RefreshRateRegimeName
  */
 static const std::array<std::string, RefreshRateManager::RefreshRateRegime::REGIME_NUM> REFRESH_RATE_REGIME_TO_STRING =
     { { "FocusActive", "FocusInactive", "Unfocus", "Minimized", "StartUp", "ShutDown" } };
 
 /**jsdoc
- * <p>Interface operates in different modes to provide different user experiences (UX).</p>
- *
+ * <p>User experience (UX) modes.</p>
  * <table>
  *   <thead>
  *     <tr><th>UX Mode</th><th>Description</th></tr>
  *   </thead>
  *   <tbody>
- *     <tr><td><code>"Desktop"</code></td><td>Desktop user experience mode.</td></tr>
- *     <tr><td><code>"VR"</code></td><td>VR user experience mode.</td></tr>
+ *     <tr><td><code>"Desktop"</code></td><td>Desktop user experience.</td></tr>
+ *     <tr><td><code>"VR"</code></td><td>VR user experience.</td></tr>
  *   </tbody>
  * </table>
- *
- * @typedef {string} UXMode
+ * @typedef {string} UXModeName
  */
 static const std::array<std::string, RefreshRateManager::UXMode::UX_NUM> UX_MODE_TO_STRING =
     { { "Desktop", "VR" } };

interface/src/RefreshRateManager.h

@@ -31,6 +31,23 @@ public:
     };
     static bool isValidRefreshRateProfile(RefreshRateProfile value) { return (value >= RefreshRateProfile::ECO && value <= RefreshRateProfile::REALTIME); }
 
+    /**jsdoc
+     * <p>Interface states that affect the refresh rate.</p>
+     * <table>
+     *   <thead>
+     *     <tr><th>Value</th><th>Name</th><th>Description</th>
+     *   </thead>
+     *   <tbody>
+     *     <tr><td><code>0</code></td><td>FOCUS_ACTIVE</td><td>Interface has focus and the user is active or is in VR.</td></tr>
+     *     <tr><td><code>1</code></td><td>FOCUS_INACTIVE</td><td>Interface has focus and the user is inactive.</td></tr>
+     *     <tr><td><code>2</code></td><td>UNFOCUS</td><td>Interface doesn't have focus.</td></tr>
+     *     <tr><td><code>3</code></td><td>MINIMIZED</td><td>Interface is minimized.</td></tr>
+     *     <tr><td><code>4</code></td><td>STARTUP</td><td>Interface is starting up.</td></tr>
+     *     <tr><td><code>5</code></td><td>SHUTDOWN</td><td>Interface is shutting down.</td></tr>
+     *   </tbody>
+     * </table>
+     * @typedef {number} RefreshRateRegime
+     */
     enum RefreshRateRegime {
         FOCUS_ACTIVE = 0,
         FOCUS_INACTIVE,
@@ -42,6 +59,19 @@ public:
     };
     static bool isValidRefreshRateRegime(RefreshRateRegime value) { return (value >= RefreshRateRegime::FOCUS_ACTIVE && value <= RefreshRateRegime::SHUTDOWN); }
 
+    /**jsdoc
+     * <p>User experience (UX) modes.</p>
+     * <table>
+     *   <thead>
+     *     <tr><th>Value</th><th>Name</th><th>Description</th>
+     *   </thead>
+     *   <tbody>
+     *     <tr><td><code>0</code></td><td>DESKTOP</td><td>Desktop user experience.</td></tr>
+     *     <tr><td><code>1</code></td><td>VR</td><td>VR use experience.</td></tr>
+     *   </tbody>
+     * </table>
+     * @typedef {number} UXMode
+     */
     enum UXMode {
         DESKTOP = 0,
         VR,

interface/src/scripting/PerformanceScriptingInterface.h

@@ -18,6 +18,18 @@
 #include "../RefreshRateManager.h"
 
 
+/**jsdoc
+ * The <code>Performance</code> API provides control and information on graphics performance settings.
+ *
+ * @namespace Performance
+ *
+ * @hifi-interface
+ * @hifi-client-entity
+ * @hifi-avatar
+ *
+ * @property {Performance.PerformancePreset} performancePreset - The current graphics performance preset.
+ * @property {Performance.RefreshRateProfile} refreshRateProfile - The current refresh rate profile.
+ */
 class PerformanceScriptingInterface : public QObject {
     Q_OBJECT
     Q_PROPERTY(PerformancePreset performancePreset READ getPerformancePreset WRITE setPerformancePreset NOTIFY settingsChanged)
@@ -25,6 +37,23 @@ class PerformanceScriptingInterface : public QObject {
 
 public:
 
+    /**jsdoc
+     * <p>Graphics performance presets.</p>
+     * <table>
+     *   <thead>
+     *     <tr><th>Value</th><th>Name</th><th>Description</th>
+     *   </thead>
+     *   <tbody>
+     *     <tr><td><code>0</code></td><td>UNKNOWN</td><td>Custom settings of world detail, rendering effects, and refresh 
+     *       rate.</td></tr>
+     *     <tr><td><code>1</code></td><td>LOW</td><td>Low world detail, no rendering effects, lo refresh rate.</td></tr>
+     *     <tr><td><code>2</code></td><td>MID</td><td>Medium world detail, some rendering effects, medium refresh 
+     *       rate.</td></tr>
+     *     <tr><td><code>3</code></td><td>HIGH</td><td>Maximum world detail, all rendering effects, high refresh rate.</td></tr>
+     *   </tbody>
+     * </table>
+     * @typedef {number} Performance.PerformancePreset
+     */
     // PerformanceManager PerformancePreset tri state level enums
     enum PerformancePreset {
         UNKNOWN = PerformanceManager::PerformancePreset::UNKNOWN,
@@ -34,6 +63,23 @@ public:
     };
     Q_ENUM(PerformancePreset)
 
+    /**jsdoc
+     * <p>Refresh rate profile.</p>
+     * <table>
+     *   <thead>
+     *     <tr><th>Value</th><th>Name</th><th>Description</th>
+     *   </thead>
+     *   <tbody>
+     *     <tr><td><code>0</code></td><td>ECO</td><td>Low refresh rate, which is reduced when Interface doesn't have focus or 
+     *       is minimized.</td></tr>
+     *     <tr><td><code>1</code></td><td>INTERACTIVE</td><td>Medium refresh rate, which is reduced when Interface doesn't have 
+     *       focus or is minimized.</td></tr>
+     *     <tr><td><code>2</code></td><td>REALTIME</td><td>High refresh rate, even when Interface doesn't have focus or is 
+     *       minimized. </td></tr>
+     *   </tbody>
+     * </table>
+     * @typedef {number} Performance.RefreshRateProfile
+     */
     // Must match RefreshRateManager enums
     enum RefreshRateProfile {
         ECO = RefreshRateManager::RefreshRateProfile::ECO,
@@ -47,19 +93,81 @@ public:
 
 public slots:
 
+    /**jsdoc
+     * Sets graphics performance to a preset.
+     * @function Performance.setPerformancePreset
+     * @param {Performance.PerformancePreset} performancePreset - The graphics performance preset to to use.
+     */
     void setPerformancePreset(PerformancePreset performancePreset);
+
+    /**jsdoc
+     * Gets the current graphics performance preset in use.
+     * @function Performance.getPerformancePreset
+     * @returns {Performance.PerformancePreset} The current graphics performance preset in use.
+     */
     PerformancePreset getPerformancePreset() const;
+
+    /**jsdoc
+     * Gets the names of the graphics performance presets.
+     * @function Performance.getPerformancePresetNames
+     * @returns {string[]} The names of the graphics performance presets. The array index values correspond to 
+     *     {@link Performance.PerformancePreset} values.
+     */
     QStringList getPerformancePresetNames() const;
 
+
+    /**jsdoc
+     * Sets the curfrent refresh rate profile.
+     * @function Performance.setRefreshRateProfile
+     * @param {Performance.RefreshRateProfile} refreshRateProfile - The refresh rate profile.
+     */
     void setRefreshRateProfile(RefreshRateProfile refreshRateProfile);
+
+    /**jsdoc
+     * Gets the current refresh rate profile in use.
+     * @function Performance.getRefreshRateProfile
+     * @returns {Performance.RefreshRateProfile} The refresh rate profile.
+     */
     RefreshRateProfile getRefreshRateProfile() const;
+
+    /**jsdoc
+     * Gets the names of the refresh rate profiles.
+     * @function Performance.getRefreshRateProfileNames
+     * @returns {string[]} The names of the refresh rate profiles. The array index values correspond to 
+     *     {@link Performance.RefreshRateProfile} values.
+     */
     QStringList getRefreshRateProfileNames() const;
 
+
+    /**jsdoc
+     * Gets the current target refresh rate, in Hz, per the current refresh rate profile and refresh rate regime if in desktop 
+     * mode; a higher rate if in VR mode.
+     * @function Performance.getActiveRefreshRate
+     * @returns {number} The current target refresh rate, in Hz.
+     */
     int getActiveRefreshRate() const;
+
+    /**jsdoc
+     * Gets the current user experience mode.
+     * @function Performance.getUXMode
+     * @returns {UXMode} The current user experience mode.
+     */
     RefreshRateManager::UXMode getUXMode() const;
+
+    /**jsdoc
+     * Gets the current refresh rate regime that's in effect.
+     * @function Performance.getRefreshRateRegime
+     * @returns {RefreshRateRegime} The current refresh rate regime.
+     */
     RefreshRateManager::RefreshRateRegime getRefreshRateRegime() const;
 
 signals:
+
+    /**jsdoc
+     * Triggered when the performance preset or refresh rate profile is changed.
+     * @function Performance.settingsChanged
+     * @returns {Signal}
+     */
     void settingsChanged();
 
 private: