Merge pull request #15363 from ctrlaltdavid/M22068

Case 22068: Clipboard JSDoc

interface/src/scripting/ClipboardScriptingInterface.h

@@ -18,7 +18,7 @@
 #include <EntityItemID.h>
 
 /**jsdoc
- * The Clipboard API enables you to export and import entities to and from JSON files.
+ * The <code>Clipboard</code> API enables you to export and import entities to and from JSON files.
  *
  * @namespace Clipboard
  *
@@ -33,56 +33,92 @@ public:
 
 public:
     /**jsdoc
-     * Compute the extents of the contents held in the clipboard.
+     * Gets the extents of the entities held in the clipboard.
      * @function Clipboard.getContentsDimensions
-     * @returns {Vec3} The extents of the contents held in the clipboard.
+     * @returns {Vec3} The extents of the content held in the clipboard.
+     * @example <caption>Import entities to the clipboard and report their overall dimensions.</caption>
+     * var filename = Window.browse("Import entities to clipboard", "", "*.json");
+     * if (filename) {
+     *     if (Clipboard.importEntities(filename)) {
+     *         print("Clipboard dimensions: " + JSON.stringify(Clipboard.getContentsDimensions()));
+     *     }
+     * }
      */
     Q_INVOKABLE glm::vec3 getContentsDimensions();
 
     /**jsdoc
-     * Compute the largest dimension of the extents of the contents held in the clipboard.
+     * Gets the largest dimension of the extents of the entities held in the clipboard.
      * @function Clipboard.getClipboardContentsLargestDimension
-     * @returns {number} The largest dimension computed.
+     * @returns {number} The largest dimension of the extents of the content held in the clipboard.
      */
     Q_INVOKABLE float getClipboardContentsLargestDimension();
 
     /**jsdoc
-     * Import entities from a JSON file containing entity data into the clipboard.
-     * You can generate a JSON file using {@link Clipboard.exportEntities}.
+     * Imports entities from a JSON file into the clipboard.
      * @function Clipboard.importEntities
-     * @param {string} filename Path and name of file to import.
-     * @param {boolean} does the ResourceRequestObserver observe this request?
-     * @param {number} optional internal id of object causing this import.
+     * @param {string} filename - The path and name of the JSON file to import.
+     * @param {boolean} [isObservable=true] - <code>true</code> if the {@link ResourceRequestObserver} can observe this 
+     *     request, <code>false</code> if it can't.
+     * @param {number} [callerID=-1] - An integer ID that is passed through to the {@link ResourceRequestObserver}.
      * @returns {boolean} <code>true</code> if the import was successful, otherwise <code>false</code>.
+     * @example <caption>Import entities and paste into the domain.</caption>
+     * var filename = Window.browse("Import entities to clipboard", "", "*.json");
+     * if (filename) {
+     *     if (Clipboard.importEntities(filename)) {
+     *         pastedEntities = Clipboard.pasteEntities(Vec3.sum(MyAvatar.position,
+     *             Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })));
+     *         print("Entities pasted: " + JSON.stringify(pastedEntities));
+     *     }
+     * }
      */
     Q_INVOKABLE bool importEntities(const QString& filename, const bool isObservable = true, const qint64 callerId = -1);
 
     /**jsdoc
-     * Export the entities specified to a JSON file.
+     * Exports specified entities to a JSON file.
      * @function Clipboard.exportEntities
-     * @param {string} filename Path and name of the file to export the entities to. Should have the extension ".json".
-     * @param {Uuid[]} entityIDs Array of IDs of the entities to export.
-     * @returns {boolean} <code>true</code> if the export was successful, otherwise <code>false</code>.
+     * @param {string} filename - Path and name of the file to export the entities to. Should have the extension ".json".
+     * @param {Uuid[]} entityIDs - The IDs of the entities to export.
+     * @returns {boolean} <code>true</code> if entities were found and the file was written, otherwise <code>false</code>.
+     * @example <caption>Create and export a cube and a sphere.</caption>
+     * // Create entities.
+     * var box = Entities.addEntity({
+     *     type: "Box",
+     *     position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.2, y: 0, z: -3 })),
+     *     lifetime: 300 // Delete after 5 minutes.
+     * });
+     * var sphere = Entities.addEntity({
+     *     type: "Sphere",
+     *     position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0.2, y: 0, z: -3 })),
+     *     lifetime: 300 // Delete after 5 minutes.
+     * });
+     * 
+     * // Export entities.
+     * var filename = Window.save("Export entities to JSON file", Paths.resources, "*.json");
+     * if (filename) {
+     *     Clipboard.exportEntities(filename, [box, sphere]);
+     * }
      */
     Q_INVOKABLE bool exportEntities(const QString& filename, const QVector<QUuid>& entityIDs);
     
     /**jsdoc
-    * Export the entities with centers within a cube to a JSON file.
+    * Exports all entities that have centers within a cube to a JSON file.
     * @function Clipboard.exportEntities
-    * @param {string} filename Path and name of the file to export the entities to. Should have the extension ".json".
-    * @param {number} x X-coordinate of the cube center.
-    * @param {number} y Y-coordinate of the cube center.
-    * @param {number} z Z-coordinate of the cube center.
-    * @param {number} scale Half dimension of the cube.
-    * @returns {boolean} <code>true</code> if the export was successful, otherwise <code>false</code>.
+    * @variation 0
+    * @param {string} filename - Path and name of the file to export the entities to. Should have the extension ".json".
+    * @param {number} x - X-coordinate of the cube center.
+    * @param {number} y - Y-coordinate of the cube center.
+    * @param {number} z - Z-coordinate of the cube center.
+    * @param {number} scale - Half dimension of the cube.
+    * @returns {boolean} <code>true</code> if entities were found and the file was written, otherwise <code>false</code>.
     */
     Q_INVOKABLE bool exportEntities(const QString& filename, float x, float y, float z, float scale);
 
     /**jsdoc
-     * Paste the contents of the clipboard into the world.
+     * Pastes the contents of the clipboard into the domain.
      * @function Clipboard.pasteEntities
-     * @param {Vec3} position Position to paste the clipboard contents at.
-     * @returns {Uuid[]} Array of entity IDs for the new entities that were created as a result of the paste operation.
+     * @param {Vec3} position -  The position to paste the clipboard contents at.
+     * @returns {Uuid[]} The IDs of the new entities that were created as a result of the paste operation. If entities couldn't 
+     *     be created then an empty array is returned.
      */
     Q_INVOKABLE QVector<EntityItemID> pasteEntities(glm::vec3 position);
 };

libraries/shared/src/ResourceRequestObserver.cpp

@@ -16,6 +16,13 @@
 #include <QString>
 #include <QUrl>
 
+/**jsdoc
+ * Information about a resource request.
+ * @typedef {object} ResourceRequestObserver.ResourceRequest
+ * @property {string} url - The URL of the resource request.
+ * @property {number} callerId - An ID identifying the request.
+ * @property {string} extra - Extra information about the request.
+ */
 void ResourceRequestObserver::update(const QUrl& requestUrl,
     const qint64 callerId,
     const QString& extra) {

libraries/shared/src/ResourceRequestObserver.h

@@ -16,7 +16,15 @@
 
 #include "DependencyManager.h"
 
-
+/**jsdoc
+ * The <code>ResourceRequestObserver</code> API provides notifications when an observable resource request is made.
+ *
+ * @namespace ResourceRequestObserver
+ * 
+ * @hifi-interface
+ * @hifi-client-entity
+ * @hifi-avatar
+ */
 class ResourceRequestObserver : public QObject, public Dependency {
     Q_OBJECT
     SINGLETON_DEPENDENCY
@@ -25,5 +33,29 @@ public:
     void update(const QUrl& requestUrl, const qint64 callerId = -1, const QString& extra = "");
 
 signals:
+    /**jsdoc
+     * Triggered when an observable resource request is made.
+     * @function ResourceRequestObserver.resourceRequestEvent
+     * @param {ResourceRequestObserver.ResourceRequest} request - Information about the resource request.
+     * @returns {Signal}
+     * @example <caption>Report when a particular Clipboard.importEntities() resource request is made.</caption>
+     * ResourceRequestObserver.resourceRequestEvent.connect(function (request) {
+     *     if (request.callerId === 100) {
+     *         print("Resource request: " + JSON.stringify(request));
+     *     }
+     * });
+     * 
+     * function importEntities() {
+     *     var filename = Window.browse("Import entities to clipboard", "", "*.json");
+     *     if (filename) {
+     *         Clipboard.importEntities(filename, true, 100);
+     *         pastedEntities = Clipboard.pasteEntities(Vec3.sum(MyAvatar.position,
+     *             Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })));
+     *         print("Entities pasted: " + JSON.stringify(pastedEntities));
+     *     }
+     * }
+     * 
+     * Script.setTimeout(importEntities, 2000);
+     */
     void resourceRequestEvent(QVariantMap result);
 };