Merge branch 'DOC-55-C' into api-docs

Author: ctrlaltdavid

interface/src/Application.cpp

@@ -693,10 +693,17 @@ class ApplicationMeshProvider : public scriptable::ModelProviderFactory  {
  *   </thead>
  *   <tbody>
  *     <tr><td><code>CameraFirstPerson</code></td><td>number</td><td>number</td><td>The camera is in first-person mode.
- *       </td></tr>
+ *       <em>Legacy first person camera mode.</em></td></tr>
+ *     <tr><td><code>CameraFirstPersonLookAt</code></td><td>number</td><td>number</td><td>The camera is in first-person mode.
+ *       <em>Default first person camera mode.</em></td></tr>
  *     <tr><td><code>CameraThirdPerson</code></td><td>number</td><td>number</td><td>The camera is in third-person mode.
- *       </td></tr>
- *     <tr><td><code>CameraFSM</code></td><td>number</td><td>number</td><td>The camera is in full screen mirror mode.</td></tr>
+ *       <em>Legacy third person camera mode.</em></td></tr>
+ *     <tr><td><code>CameraLookAt</code></td><td>number</td><td>number</td><td>The camera is in third-person mode.
+ *       <em>Default third person camera mode.</em></td></tr>
+ *     <tr><td><code>CameraFSM</code></td><td>number</td><td>number</td><td>The camera is in full screen mirror mode.
+ *       <em>Legacy "look at myself" behavior.</em></td></tr>
+ *     <tr><td><code>CameraSelfie</code></td><td>number</td><td>number</td><td>The camera is in selfie mode.
+ *       <em>Default "look at myself" camera mode.</em></td></tr>
  *     <tr><td><code>CameraIndependent</code></td><td>number</td><td>number</td><td>The camera is in independent mode.</td></tr>
  *     <tr><td><code>CameraEntity</code></td><td>number</td><td>number</td><td>The camera is in entity mode.</td></tr>
  *     <tr><td><code>InHMD</code></td><td>number</td><td>number</td><td>The user is in HMD mode.</td></tr>

interface/src/AvatarBookmarks.cpp

@@ -187,7 +187,7 @@ void AvatarBookmarks::updateAvatarEntities(const QVariantList &avatarEntities) {
  * @property {number} avatarScale - The target scale of the avatar.
  * @property {Array<Object<"properties",Entities.EntityProperties>>} [avatarEntites] - The avatar entities included with the 
  *     bookmark.
- * @property {MyAvatar.AttachmentData[]} [attachments] - The attachments included with the bookmark.
+ * @property {AttachmentData[]} [attachments] - The attachments included with the bookmark.
  *     <p class="important">Deprecated: Use avatar entities instead.
  */
 

interface/src/avatar/MyAvatar.h

@@ -52,8 +52,9 @@
  *     <em>Read-only.</em>
  *     <p><strong>Warning:</strong> Not yet implemented.</p>
  *
- * @property {FilterFlags} PICK_BYPASS_IGNORE - Allows pick to intersect entities even when their ignorePickIntersection property is 'true'.
- *     For debug purposes. <em>Read-only.</em>
+ * @property {FilterFlags} PICK_BYPASS_IGNORE - Allows pick to intersect entities even when their 
+ *     <code>ignorePickIntersection</code> property value is <code>true</code>. For debug purposes.
+ *     <em>Read-only.</em>
  *
  * @property {IntersectionType} INTERSECTED_NONE - Intersected nothing. <em>Read-only.</em>
  * @property {IntersectionType} INTERSECTED_ENTITY - Intersected an entity. <em>Read-only.</em>

interface/src/raypick/PickScriptingInterface.h

@@ -167,7 +167,7 @@ class PointerScriptingInterface : public QObject, public Dependency {
     * of the pointer, see {@link Pointers.getPointerProperties}.
     * @function Pointers.getPointerScriptParameters
     * @param {number} id - The ID of the pointer.
-    * @returns {Pointers.RayPointerProperties|Picks.ParabolaPointerProperties|Picks.StylusPointerProperties} 
+    * @returns {Pointers.RayPointerProperties|Pointers.ParabolaPointerProperties|Pointers.StylusPointerProperties} 
     *     Script-provided properties, per the pointer <code>type</code>.
     */
     Q_INVOKABLE QVariantMap getPointerScriptParameters(unsigned int uid) const;

interface/src/raypick/PointerScriptingInterface.h

@@ -30,21 +30,6 @@
  * @property {InteractiveWindow.DockArea} LEFT - Dock to the left edge of the Interface window.
  * @property {InteractiveWindow.DockArea} RIGHT - Dock to the right edge of the Interface window.
  */
-/**jsdoc
- * <p>A docking location of an <code>InteractiveWindow</code>.</p>
- * <table>
- *   <thead>
- *     <tr><th>Value</th><th>Name</th><th>Description</th></tr>
- *   </thead>
- *   <tbody>
- *     <tr><td><code>0</code></td><td>TOP</td><td>Dock to the top edge of the Interface window.</td></tr>
- *     <tr><td><code>1</code></td><td>BOTTOM</td><td>Dock to the bottom edge of the Interface window.</td></tr>
- *     <tr><td><code>2</code></td><td>LEFT</td><td>Dock to the left edge of the Interface window.</td></tr>
- *     <tr><td><code>3</code></td><td>RIGHT</td><td>Dock to the right edge of the Interface window.</td></tr>
- *   <tbody>
- * </table>
- * @typedef {number} InteractiveWindow.DockArea
- */
 static const QVariantMap DOCK_AREA {
     { "TOP", DockArea::TOP },
     { "BOTTOM", DockArea::BOTTOM },
@@ -53,13 +38,17 @@ static const QVariantMap DOCK_AREA {
 };
 
 /**jsdoc
- * The possible "relative position anchors" of an <code>InteractiveWindow</code>. Used when defining the `relativePosition` property of an `InteractiveWindow`.
+ * The possible relative position anchors of an <code>InteractiveWindow</code> relative to the Interface window.
  * @typedef {object} InteractiveWindow.RelativePositionAnchors
- * @property {InteractiveWindow.RelativePositionAnchor} NO_ANCHOR - Specifies that the position of the `InteractiveWindow` will not be relative to any part of the Interface window.
- * @property {InteractiveWindow.RelativePositionAnchor} TOP_LEFT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the top left of the Interface window.
- * @property {InteractiveWindow.RelativePositionAnchor} TOP_RIGHT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the top right of the Interface window.
- * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_RIGHT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the bottom right of the Interface window.
- * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_LEFT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the bottom left of the Interface window.
+ * @property {InteractiveWindow.RelativePositionAnchor} NO_ANCHOR - Position is not relative to any part of the Interface 
+ *     window.
+ * @property {InteractiveWindow.RelativePositionAnchor} TOP_LEFT - Position is offset from the top left of the Interface window.
+ * @property {InteractiveWindow.RelativePositionAnchor} TOP_RIGHT - Position is offset from the top right of the Interface 
+ *     window.
+ * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_RIGHT - Position offset from the bottom right of the Interface 
+ *     window.
+ * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_LEFT - Position is offset from the bottom left of the Interface 
+ *     window.
  */
 static const QVariantMap RELATIVE_POSITION_ANCHOR {
     { "NO_ANCHOR", RelativePositionAnchor::NO_ANCHOR },
@@ -89,21 +78,6 @@ int DesktopScriptingInterface::getHeight() {
  * @property {InteractiveWindow.PresentationMode} NATIVE - The window is displayed separately from the Interface window, as its 
  *     own separate window.
  */
-/**jsdoc
- * <p>A display mode for an <code>InteractiveWindow</code>.</p>
- * <table>
- *   <thead>
- *     <tr><th>Value</th><th>Name</th><th>Description</th></tr>
- *   </thead>
- *   <tbody>
- *     <tr><td><code>0</code></td><td>VIRTUAL</td><td>The window is displayed inside Interface: in the desktop window in 
- *       desktop mode or on the HUD surface in HMD mode.</td></tr>
- *     <tr><td><code>1</code></td><td>NATIVE</td><td>The window is displayed separately from the Interface window, as its 
- *     own separate window.</td></tr>
- *   <tbody>
- * </table>
- * @typedef {number} InteractiveWindow.PresentationMode
- */
 QVariantMap DesktopScriptingInterface::getPresentationMode() {
     static QVariantMap presentationModes {
         { "VIRTUAL", Virtual },

interface/src/scripting/DesktopScriptingInterface.cpp

@@ -42,8 +42,8 @@
  * @property {InteractiveWindow.DockAreas} DockArea - The possible docking locations of an {@link InteractiveWindow}: top, 
  *     bottom, left, or right of the Interface window. 
  *     <em>Read-only.</em>
- * @property {InteractiveWindow.RelativePositionAnchors} RelativePositionAnchor - The possible "relative position anchors" for an {@link InteractiveWindow}: top left, 
- *     top right, bottom right, or bottom left of the Interface window. 
+ * @property {InteractiveWindow.RelativePositionAnchors} RelativePositionAnchor - The possible relative position anchors for an 
+ *     {@link InteractiveWindow}: none, top left, top right, bottom right, or bottom left of the Interface window. 
  *     <em>Read-only.</em>
  */
 class DesktopScriptingInterface : public QObject, public Dependency {
@@ -84,7 +84,7 @@ class DesktopScriptingInterface : public QObject, public Dependency {
      * @param {string} url - The QML file that specifies the window content. The QML file can use a <code>WebView</code> 
      *     control (defined by "WebView.qml" included in the Interface install) to embed an HTML web page (complete with  
      *     <code>EventBridge</code> object).
-     * @param {InteractiveWindow.Properties} [properties] - Initial window properties.
+     * @param {InteractiveWindow.WindowProperties} [properties] - Initial window properties.
      * @returns {InteractiveWindow} A new window object.
      * @example <caption>Open a dialog in its own window separate from Interface.</caption>
      * var nativeWindow = Desktop.createWindow(Script.resourcesPath() + 'qml/OverlayWindowTest.qml', {

interface/src/scripting/DesktopScriptingInterface.h

@@ -818,8 +818,12 @@ private slots:
     /**jsdoc
      * Triggered when "minimized" state of the Interface window changes.
      * @function Window.minimizedChanged
-     * @param {bool} isMinimized - true if the Interface window is now minimized; false otherwise.
+     * @param {boolean} isMinimized - <code>true</code> if the Interface window is minimized, <code>false</code> if it isn't.
      * @returns {Signal}
+     * @example <caption>Report the "minimized" state of the Interface window when it changes.</caption>
+     * function onWindowMinimizedChanged(minimized) {
+     *     print("Window minimized: " + minimized);
+     * }
      *
      * Window.minimizedChanged.connect(onWindowMinimizedChanged);
      */

interface/src/scripting/WindowScriptingInterface.h

@@ -129,8 +129,8 @@ void InteractiveWindow::emitMainWindowResizeEvent() {
 }
 
 /**jsdoc
- * A set of properties used when creating an <code>InteractiveWindow</code>.
- * @typedef {object} InteractiveWindow.Properties
+ * Property values used when creating an <code>InteractiveWindow</code>.
+ * @typedef {object} InteractiveWindow.WindowProperties
  * @property {string} [title="InteractiveWindow] - The title of the window.
  * @property {Vec2} [position] - The initial position of the window, in pixels.
  * @property {Vec2} [size] - The initial size of the window, in pixels
@@ -142,13 +142,36 @@ void InteractiveWindow::emitMainWindowResizeEvent() {
  * @property {InteractiveWindow.PresentationWindowInfo} [presentationWindowInfo] - Controls how a <code>NATIVE</code> window is
  *     displayed. If used, the window is docked to the specified edge of the Interface window, otherwise the window is
  *     displayed as its own separate window.
- * @property {InteractiveWindow.AdditionalFlags} [additionalFlags=0] - Window behavior flags in addition to "native window flags" (minimize/maximize/close),
- *     set at window creation. Possible flag values are provided as {@link Desktop|Desktop.ALWAYS_ON_TOP} and {@link Desktop|Desktop.CLOSE_BUTTON_HIDES}.
- *     Additional flag values can be found on Qt's website at https://doc.qt.io/qt-5/qt.html#WindowType-enum.
- * @property {InteractiveWindow.OverrideFlags} [overrideFlags=0] - Window behavior flags instead of the default window flags.
- *     Set at window creation. Possible flag values are provided as {@link Desktop|Desktop.ALWAYS_ON_TOP} and {@link Desktop|Desktop.CLOSE_BUTTON_HIDES}.
- *     Additional flag values can be found on Qt's website at https://doc.qt.io/qt-5/qt.html#WindowType-enum.
+ * @property {InteractiveWindow.Flags} [additionalFlags=0] - Customizes window behavior.
+ * @property {InteractiveWindow.OverrideFlags} [overrideFlags=0] - Customizes window controls.
+
+  * @property {InteractiveWindow.RelativePositionAnchor} [relativePositionAnchor] - he anchor for the 
+  *     <code>relativePosition</code>, if used.
+  * @property {Vec2} [relativePosition] - The position of the window, relative to the <code>relativePositionAnchor</code>, in 
+  *     pixels. Excludes the window frame.
+  * @property {boolean} [isFullScreenWindow] - <code>true</code> to make the window full screen.
  */
+/**jsdoc
+ * <p>A set of flags customizing <code>InteractiveWindow</code> controls. The value is constructed by using the <code>|</code> 
+ * (bitwise OR) operator on the individual flag values.</code>.</p>
+ * <table>
+ *   <thead>
+ *     <tr><th>Value</th><th>Name</th><th>Description</th></tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr><td><code>0x00000001</code></td><td>Window</td><td>Displays the window as a window rather than a dialog.</td></tr>
+ *     <tr><td><code>0x00001000</code></td><td>WindowTitleHint</td><td>Adds a title bar.</td><td>
+ *     <tr><td><code>0x00002000</code></td><td>WindowSystemMenuHint</td><td>Adds a window system menu.</td><td>
+ *     <tr><td><code>0x00004000</code></td><td>WindowMinimizeButtonHint</td><td>Adds a minimize button.</td><td>
+ *     <tr><td><code>0x00008000</code></td><td>WindowMaximizeButtonHint</td><td>Adds a maximize button.</td><td>
+ *     <tr><td><code>0x00040000</code></td><td>WindowStaysOnTopHint</td><td>The window stays on top of other windows.
+ *       <em>Not used on Windows.</em>
+ *     <tr><td><code>0x08000000</code></td><td>WindowCloseButtonHint</td><td>Adds a close button.</td><td>
+ *   <tbody>
+ * </table>
+ * @typedef {number} InteractiveWindow.OverrideFlags
+ */
+// OverrideFlags is per InteractiveWindow.qml.
 InteractiveWindow::InteractiveWindow(const QString& sourceUrl, const QVariantMap& properties, bool restricted) {
     InteractiveWindowPresentationMode presentationMode = InteractiveWindowPresentationMode::Native;
 

interface/src/ui/InteractiveWindow.cpp

@@ -76,12 +76,42 @@ namespace InteractiveWindowEnums {
     };
     Q_ENUM_NS(InteractiveWindowFlags);
 
+    /**jsdoc
+     * <p>A display mode for an <code>InteractiveWindow</code>.</p>
+     * <table>
+     *   <thead>
+     *     <tr><th>Value</th><th>Name</th><th>Description</th></tr>
+     *   </thead>
+     *   <tbody>
+     *     <tr><td><code>0</code></td><td>VIRTUAL</td><td>The window is displayed inside Interface: in the desktop window in
+     *       desktop mode or on the HUD surface in HMD mode.</td></tr>
+     *     <tr><td><code>1</code></td><td>NATIVE</td><td>The window is displayed separately from the Interface window, as its
+     *     own separate window.</td></tr>
+     *   <tbody>
+     * </table>
+     * @typedef {number} InteractiveWindow.PresentationMode
+     */
     enum InteractiveWindowPresentationMode {
         Virtual,
         Native
     };
     Q_ENUM_NS(InteractiveWindowPresentationMode);
 
+    /**jsdoc
+     * <p>A docking location of an <code>InteractiveWindow</code>.</p>
+     * <table>
+     *   <thead>
+     *     <tr><th>Value</th><th>Name</th><th>Description</th></tr>
+     *   </thead>
+     *   <tbody>
+     *     <tr><td><code>0</code></td><td>TOP</td><td>Dock to the top edge of the Interface window.</td></tr>
+     *     <tr><td><code>1</code></td><td>BOTTOM</td><td>Dock to the bottom edge of the Interface window.</td></tr>
+     *     <tr><td><code>2</code></td><td>LEFT</td><td>Dock to the left edge of the Interface window.</td></tr>
+     *     <tr><td><code>3</code></td><td>RIGHT</td><td>Dock to the right edge of the Interface window.</td></tr>
+     *   <tbody>
+     * </table>
+     * @typedef {number} InteractiveWindow.DockArea
+     */
     enum DockArea {
         TOP,
         BOTTOM,
@@ -90,6 +120,24 @@ namespace InteractiveWindowEnums {
     };
     Q_ENUM_NS(DockArea);
 
+    /**jsdoc
+     * <p>The anchor for a relative position of an <code>InteractiveWindow</code>.</p>
+     * <table>
+     *   <thead>
+     *     <tr><th>Value</th><th>Name</th><th>Description</th></tr>
+     *   </thead>
+     *   <tbody>
+     *     <tr><td><code>0</code></td><td>NO_ANCHOR</td><td>Position is not relative to any part of the Interface window.</td></tr>
+     *     <tr><td><code>1</code></td><td>TOP_LEFT</td><td>Position is offset from the top left of the Interface window.</td></tr>
+     *     <tr><td><code>2</code></td><td>TOP_RIGHT</td><td>Position is offset from the top right of the Interface window.</td></tr>
+     *     <tr><td><code>3</code></td><td>BOTTOM_RIGHT</td><td>Position offset from the bottom right of the Interface
+     *     window.</td></tr>
+     *     <tr><td><code>4</code></td><td>BOTTOM_LEFFT</td><td>Position is offset from the bottom left of the Interface
+     *         window.</td></tr>
+     *   <tbody>
+     * </table>
+     * @typedef {number} InteractiveWindow.RelativePositionAnchor
+     */
     enum RelativePositionAnchor {
         NO_ANCHOR,
         TOP_LEFT,
@@ -117,7 +165,11 @@ using namespace InteractiveWindowEnums;
  * @hifi-avatar
  *
  * @property {string} title - The title of the window.
- * @property {Vec2} position - The position of the window, in pixels.
+ * @property {Vec2} position - The absolute position of the window, in pixels.
+ * @property {InteractiveWindow.RelativePositionAnchor} relativePositionAnchor -  The anchor for the 
+ *     <code>relativePosition</code>, if used.
+ * @property {Vec2} relativePosition - The position of the window, relative to the <code>relativePositionAnchor</code>, in 
+ *     pixels. Excludes the window frame.
  * @property {Vec2} size - The size of the window, in pixels.
  * @property {boolean} visible - <code>true</code> if the window is visible, <code>false</code> if it isn't.
  * @property {InteractiveWindow.PresentationMode} presentationMode - The presentation mode of the window: 

interface/src/ui/InteractiveWindow.h

@@ -1920,6 +1920,13 @@ void Avatar::setParentJointIndex(quint16 parentJointIndex) {
     }
 }
 
+/**jsdoc
+ * Information about a joint in an avatar's skeleton hierarchy.
+ * @typedef {object} SkeletonJoint
+ * @property {string} name - Joint name.
+ * @property {number} index - Joint index.
+ * @property {number} parentIndex - Index of this joint's parent (-1 if no parent).
+ */
 QList<QVariant> Avatar::getSkeleton() {
     SkeletonModelPointer skeletonModel = _skeletonModel;
     if (skeletonModel) {