Merge pull request #16251 from ctrlaltdavid/DOC-155

DOC-155: EntityViewer JSDoc

assignment-client/src/entities/EntityTreeHeadlessViewer.h

@@ -24,6 +24,9 @@
 class EntitySimulation;
 
 /**jsdoc
+ * The <code>EntityViewer</code> API provides a headless viewer for assignment client scripts, so that they can "see" entities 
+ * in order for them to be available in the {@link Entities} API.
+ *
  * @namespace EntityViewer
  *
  * @hifi-assignment-client

assignment-client/src/octree/OctreeHeadlessViewer.h

@@ -28,6 +28,7 @@ public:
 public slots:
 
     /**jsdoc
+     * Updates the entities currently in view.
      * @function EntityViewer.queryOctree
      */
     void queryOctree();
@@ -36,26 +37,30 @@ public slots:
     // setters for camera attributes
 
     /**jsdoc
+     * Sets the position of the view frustum.
      * @function EntityViewer.setPosition
-     * @param {Vec3} position
+     * @param {Vec3} position - The position of the view frustum.
      */
     void setPosition(const glm::vec3& position) { _hasViewFrustum = true; _viewFrustum.setPosition(position); }
 
     /**jsdoc
+     * Sets the orientation of the view frustum.
      * @function EntityViewer.setOrientation
-     * @param {Quat} orientation
+     * @param {Quat} orientation - The orientation of the view frustum.
      */
     void setOrientation(const glm::quat& orientation) { _hasViewFrustum = true; _viewFrustum.setOrientation(orientation); }
 
     /**jsdoc
+     * Sets the radius of the center "keyhole" in the view frustum.
      * @function EntityViewer.setCenterRadius
-     * @param {number} radius
+     * @param {number} radius - The radius of the center "keyhole" in the view frustum.
      */
     void setCenterRadius(float radius) { _hasViewFrustum = true; _viewFrustum.setCenterRadius(radius); }
 
     /**jsdoc
+     * Sets the radius of the center "keyhole" in the view frustum.
      * @function EntityViewer.setKeyholeRadius
-     * @param {number} radius
+     * @param {number} radius - The radius of the center "keyhole" in the view frustum.
      * @deprecated This function is deprecated and will be removed. Use {@link EntityViewer.setCenterRadius|setCenterRadius} 
      *     instead.
      */
@@ -66,33 +71,38 @@ public slots:
 
     /**jsdoc
      * @function EntityViewer.setVoxelSizeScale
-     * @param {number} sizeScale
+     * @param {number} sizeScale - The voxel size scale.
+     * @deprecated This function is deprecated and will be removed.
      */
     void setVoxelSizeScale(float sizeScale) { _octreeQuery.setOctreeSizeScale(sizeScale) ; }
 
     /**jsdoc
      * @function EntityViewer.setBoundaryLevelAdjust
-     * @param {number} boundaryLevelAdjust
+     * @param {number} boundaryLevelAdjust - The boundary level adjust factor.
+     * @deprecated This function is deprecated and will be removed.
      */
     void setBoundaryLevelAdjust(int boundaryLevelAdjust) { _octreeQuery.setBoundaryLevelAdjust(boundaryLevelAdjust); }
 
     /**jsdoc
+     * Sets the maximum number of entity packets to receive from the domain server per second.
      * @function EntityViewer.setMaxPacketsPerSecond
-     * @param {number} maxPacketsPerSecond
+     * @param {number} maxPacketsPerSecond - The maximum number of entity packets to receive per second.
      */
     void setMaxPacketsPerSecond(int maxPacketsPerSecond) { _octreeQuery.setMaxQueryPacketsPerSecond(maxPacketsPerSecond); }
 
     // getters for camera attributes
 
     /**jsdoc
+     * Gets the position of the view frustum.
      * @function EntityViewer.getPosition
-     * @returns {Vec3}
+     * @returns {Vec3} The position of the view frustum.
      */
     const glm::vec3& getPosition() const { return _viewFrustum.getPosition(); }
 
     /**jsdoc
+     * Gets the orientation of the view frustum.
      * @function EntityViewer.getOrientation
-     * @returns {Quat}
+     * @returns {Quat} The orientation of the view frustum.
      */
     const glm::quat& getOrientation() const { return _viewFrustum.getOrientation(); }
 
@@ -101,26 +111,30 @@ public slots:
 
     /**jsdoc
      * @function EntityViewer.getVoxelSizeScale
-     * @returns {number}
+     * @returns {number} The voxel size scale.
+     * @deprecated This function is deprecated and will be removed.
      */
     float getVoxelSizeScale() const { return _octreeQuery.getOctreeSizeScale(); }
 
     /**jsdoc
      * @function EntityViewer.getBoundaryLevelAdjust
-     * @returns {number}
+     * @returns {number} The boundary level adjust factor.
+     * @deprecated This function is deprecated and will be removed.
      */
     int getBoundaryLevelAdjust() const { return _octreeQuery.getBoundaryLevelAdjust(); }
 
     /**jsdoc
+     * Gets the maximum number of entity packets to receive from the domain server per second.
      * @function EntityViewer.getMaxPacketsPerSecond
-     * @returns {number}
+     * @returns {number} The maximum number of entity packets to receive per second.
      */
     int getMaxPacketsPerSecond() const { return _octreeQuery.getMaxQueryPacketsPerSecond(); }
 
 
     /**jsdoc
+     * Gets the number of nodes in the octree.
      * @function EntityViewer.getOctreeElementsCount
-     * @returns {number}
+     * @returns {number} The number of nodes in the octree.
      */
     unsigned getOctreeElementsCount() const { return _tree->getOctreeElementsCount(); }
 

libraries/entities/src/EntityScriptingInterface.h

@@ -106,8 +106,9 @@ public:
  * "domain" entities, travel to different domains with a user as "avatar" entities, or be visible only to an individual user as 
  * "local" entities (a.k.a. "overlays").
  *
- * <p>Note: For Interface scripts, the entities available to scripts are those that Interface has displayed and so knows 
- * about.</p>
+ * <p>Note: For Interface, avatar, and client entity scripts, the entities available to scripts are those that Interface has 
+ * displayed and so knows about. For assignment client scripts, the entities available are those that are "seen" by the 
+ * {@link EntityViewer}. For entity server scripts, all entities are available.</p>
  *
  * <h3>Entity Methods</h3>
  *