Merge pull request #15950 from ctrlaltdavid/DOC-121

DOC-121: AvatarBookmarks JSDoc

interface/src/AvatarBookmarks.cpp

@@ -179,6 +179,18 @@ void AvatarBookmarks::updateAvatarEntities(const QVariantList &avatarEntities) {
     }
 }
 
+/**jsdoc
+ * Details of an avatar bookmark.
+ * @typedef {object} AvatarBookmarks.BookmarkData
+ * @property {number} version - The version of the bookmark data format.
+ * @property {string} avatarUrl - The URL of the avatar model.
+ * @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.
+ *     <p class="important">Deprecated: Use avatar entities instead.
+ */
+
 void AvatarBookmarks::loadBookmark(const QString& bookmarkName) {
     if (QThread::currentThread() != thread()) {
         BLOCKING_INVOKE_METHOD(this, "loadBookmark", Q_ARG(QString, bookmarkName));

interface/src/AvatarBookmarks.h

@@ -16,7 +16,9 @@
 #include "Bookmarks.h"
 
 /**jsdoc 
- * This API helps manage adding and deleting avatar bookmarks.
+ * The <code>AvatarBookmarks</code> API provides facilities for working with avatar bookmarks ("favorites" in the Avatar app). 
+ * An avatar bookmark associates a name with an avatar model, scale, and avatar entities (wearables).
+ *
  * @namespace AvatarBookmarks
  *
  * @hifi-interface
@@ -32,41 +34,100 @@ class AvatarBookmarks: public Bookmarks, public  Dependency {
 public:
     AvatarBookmarks();
     void setupMenus(Menu* menubar, MenuWrapper* menu) override {};
+
+    /**jsdoc
+     * Gets the details of an avatar bookmark.
+     * @function AvatarBookmarks.getBookmark
+     * @param {string} bookmarkName - The name of the avatar bookmark (case sensitive).
+     * @returns {AvatarBookmarks.BookmarkData|{}} The bookmark data if the bookmark exists, <code>{}</code> if it doesn't.
+     */
     Q_INVOKABLE QVariantMap getBookmark(const QString& bookmarkName);
 
 public slots:
     /**jsdoc 
-     * Add the current Avatar to your avatar bookmarks.
-     * @function AvatarBookmarks.addBookMark
+     * Adds a new (or updates an existing) avatar bookmark with your current avatar model, scale, and avatar entities.
+     * @function AvatarBookmarks.addBookmark
+     * @param {string} bookmarkName - The name of the avatar bookmark (case sensitive).
+     * @example <caption>Add a new avatar bookmark and report the bookmark data.</caption>
+     * var bookmarkName = "New Bookmark";
+     * AvatarBookmarks.addBookmark(bookmarkName);
+     * var bookmarkData = AvatarBookmarks.getBookmark(bookmarkName);
+     * print("Bookmark data: " + JSON.stringify(bookmarkData));
      */
     void addBookmark(const QString& bookmarkName);
+
+    /**jsdoc
+     * Updates an existing bookmark with your current avatar model, scale, and wearables. No action is taken if the bookmark 
+     * doesn't exist.
+     * @function AvatarBookmarks.saveBookmark
+     * @param {string} bookmarkName - The name of the avatar bookmark (case sensitive).
+     */
     void saveBookmark(const QString& bookmarkName);
+
+    /**jsdoc
+     * Loads an avatar bookmark, setting your avatar model, scale, and avatar entities (or attachments if an old bookmark) to 
+     * those in the bookmark.
+     * @function AvatarBookmarks.loadBookmark
+     * @param {string} bookmarkName - The name of the avatar bookmark to load (case sensitive).
+     */
     void loadBookmark(const QString& bookmarkName);
+
+    /**jsdoc
+     * Deletes an avatar bookmark.
+     * @function AvatarBookmarks.removeBookmark
+     * @param {string} bookmarkName - The name of the avatar bookmark to delete (case sensitive).
+     */
     void removeBookmark(const QString& bookmarkName);
+
+    /**jsdoc
+     * Updates the avatar entities and their properties. Current avatar entities not included in the list provided are deleted.
+     * @function AvatarBookmarks.updateAvatarEntities
+     * @param {MyAvatar.AvatarEntityData[]} avatarEntities - The avatar entity IDs and properties.
+     * @deprecated This function is deprecated and will be removed. Use the {@link MyAvatar} API instead.
+     */
     void updateAvatarEntities(const QVariantList& avatarEntities);
+
+    /**jsdoc
+     * Gets the details of all avatar bookmarks.
+     * @function AvatarBookmarks.getBookmarks
+     * @returns {Object<string,AvatarBookmarks.BookmarkData>} The current avatar bookmarks in an object where the keys are the 
+     *     bookmark names and the values are the bookmark details.
+     * @example <caption>List the names and URLs of all the avatar bookmarks.</caption>
+     * var bookmarks = AvatarBookmarks.getBookmarks();
+     * print("Avatar bookmarks:");
+     * for (var key in bookmarks) {
+     *     print("- " + key + " " + bookmarks[key].avatarUrl);
+     * };
+     */
     QVariantMap getBookmarks() { return _bookmarks; }
 
 signals:
     /**jsdoc
-     * This function gets triggered after avatar loaded from bookmark
+     * Triggered when an avatar bookmark is loaded, setting your avatar model, scale, and avatar entities (or attachments if an 
+     * old bookmark) to those in the bookmark.
      * @function AvatarBookmarks.bookmarkLoaded
-     * @param {string} bookmarkName
+     * @param {string} bookmarkName - The name of the avatar bookmark loaded.
      * @returns {Signal}
      */
     void bookmarkLoaded(const QString& bookmarkName);
 
     /**jsdoc
-     * This function gets triggered after avatar bookmark deleted
+     * Triggered when an avatar bookmark is deleted.
      * @function AvatarBookmarks.bookmarkDeleted
-     * @param {string} bookmarkName
+     * @param {string} bookmarkName - The name of the avatar bookmark deleted.
      * @returns {Signal}
+     * @example <caption>Report when a bookmark is deleted.</caption>
+     * AvatarBookmarks.bookmarkDeleted.connect(function (bookmarkName) {
+     *     print("Bookmark deleted: " + bookmarkName);
+     * });
      */
     void bookmarkDeleted(const QString& bookmarkName);
 
     /**jsdoc
-     * This function gets triggered after avatar bookmark added
+     * Triggered when a new avatar bookmark is added or an existing avatar bookmark is updated, using 
+     * {@link AvatarBookmarks.addBookmark|addBookmark}.
      * @function AvatarBookmarks.bookmarkAdded
-     * @param {string} bookmarkName
+     * @param {string} bookmarkName - The name of the avatar bookmark added or updated.
      * @returns {Signal}
      */
     void bookmarkAdded(const QString& bookmarkName);
@@ -77,6 +138,11 @@ protected:
     QVariantMap getAvatarDataToBookmark();
 
 protected slots: 
+    /**jsdoc
+     * Performs no action.
+     * @function AvatarBookmarks.deleteBookmark
+     * @deprecated This function is deprecated and will be removed.
+     */
     void deleteBookmark() override;
 
 private:

interface/src/avatar/AvatarManager.h

@@ -238,7 +238,7 @@ public:
      * @function AvatarManager.getPalData
      * @param {string[]} [avatarIDs=[]] - The IDs of the avatars to get the PAL data for. If empty, then PAL data is obtained 
      *     for all avatars.
-     * @returns {object<"data", AvatarManager.PalData[]>} An array of objects, each object being the PAL data for an avatar.
+     * @returns {Object<"data", AvatarManager.PalData[]>} An array of objects, each object being the PAL data for an avatar.
      * @example <caption>Report the PAL data for an avatar nearby.</caption>
      * var palData = AvatarManager.getPalData();
      * print("PAL data for one avatar: " + JSON.stringify(palData.data[0]));

interface/src/avatar/MyAvatar.h

@@ -1369,9 +1369,9 @@ public:
     bool hasDriveInput() const;
 
     /**jsdoc
-     * Gets the list of avatar entities and their properties.
+     * Gets the current avatar entity IDs and their properties.
      * @function MyAvatar.getAvatarEntitiesVariant
-     * @returns {MyAvatar.AvatarEntityData[]} The list of avatar entities and their properties.
+     * @returns {MyAvatar.AvatarEntityData[]} The current avatar entity IDs and their properties.
      */
     Q_INVOKABLE QVariantList getAvatarEntitiesVariant();
 

libraries/avatars/src/AvatarData.cpp

@@ -2861,7 +2861,7 @@ glm::vec3 AvatarData::getAbsoluteJointTranslationInObjectFrame(int index) const
  * Information on an attachment worn by the avatar.
  * @typedef {object} AttachmentData
  * @property {string} modelUrl - The URL of the model file. Models can be FBX or OBJ format.
- * @property {string} jointName - The offset to apply to the model relative to the joint position.
+ * @property {string} jointName - The name of the joint that the attachment is parented to.
  * @property {Vec3} translation - The offset from the joint that the attachment is positioned at.
  * @property {Vec3} rotation - The rotation applied to the model relative to the joint orientation.
  * @property {number} scale - The scale applied to the attachment model.

libraries/avatars/src/AvatarData.h

@@ -1292,7 +1292,7 @@ public:
      *     jointName: "Head",
      *     translation: {"x": 0, "y": 0.25, "z": 0},
      *     rotation: {"x": 0, "y": 0, "z": 0, "w": 1},
-     *     scale: 1,
+     *     scale: 0.01,
      *     isSoft: false
      * };
      *