From 42d0620fd1a0b4f04673cc3ac6362ce55e709953 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Fri, 11 May 2018 20:56:00 +1200
Subject: [PATCH] EntityViewer API JSDoc stubs

---
 .../src/entities/EntityTreeHeadlessViewer.h   |  7 ++
 .../src/octree/OctreeHeadlessViewer.h         | 72 +++++++++++++++++++
 tools/jsdoc/plugins/hifi.js                   |  2 +
 3 files changed, 81 insertions(+)

diff --git a/assignment-client/src/entities/EntityTreeHeadlessViewer.h b/assignment-client/src/entities/EntityTreeHeadlessViewer.h
index 17bb37186a..f4d5911821 100644
--- a/assignment-client/src/entities/EntityTreeHeadlessViewer.h
+++ b/assignment-client/src/entities/EntityTreeHeadlessViewer.h
@@ -23,6 +23,13 @@
 
 class EntitySimulation;
 
+/**jsdoc
+ * @namespace EntityViewer
+ *
+ * @hifi-assignment-client
+ */
+// API functions are defined in OctreeHeadlessViewer.
+
 // Generic client side Octree renderer class.
 class EntityTreeHeadlessViewer : public OctreeHeadlessViewer {
     Q_OBJECT
diff --git a/assignment-client/src/octree/OctreeHeadlessViewer.h b/assignment-client/src/octree/OctreeHeadlessViewer.h
index dea91ce66f..a1d0331e26 100644
--- a/assignment-client/src/octree/OctreeHeadlessViewer.h
+++ b/assignment-client/src/octree/OctreeHeadlessViewer.h
@@ -26,28 +26,100 @@ public:
     static void trackIncomingOctreePacket(const QByteArray& packet, const SharedNodePointer& sendingNode, bool wasStatsPacket);
 
 public slots:
+
+    /**jsdoc
+     * @function EntityViewer.queryOctree
+     */
     void queryOctree();
 
+
     // setters for camera attributes
+
+    /**jsdoc
+     * @function EntityViewer.setPosition
+     * @param {Vec3} position
+     */
     void setPosition(const glm::vec3& position) { _hasViewFrustum = true; _viewFrustum.setPosition(position); }
+
+    /**jsdoc
+     * @function EntityViewer.setOrientation
+     * @param {Quat} orientation
+     */
     void setOrientation(const glm::quat& orientation) { _hasViewFrustum = true; _viewFrustum.setOrientation(orientation); }
+
+    /**jsdoc
+     * @function EntityViewer.setCenterRadius
+     * @param {number} radius
+     */
     void setCenterRadius(float radius) { _hasViewFrustum = true; _viewFrustum.setCenterRadius(radius); }
+
+    /**jsdoc
+     * @function EntityViewer.setKeyholeRadius
+     * @param {number} radius
+     * @deprecated Use {@link EntityViewer.setCenterRadius|setCenterRadius} instead.
+     */
     void setKeyholeRadius(float radius) { _hasViewFrustum = true; _viewFrustum.setCenterRadius(radius); } // TODO: remove this legacy support
 
+
     // setters for LOD and PPS
+
+    /**jsdoc
+     * @function EntityViewer.setVoxelSizeScale
+     * @param {number} sizeScale
+     */
     void setVoxelSizeScale(float sizeScale) { _octreeQuery.setOctreeSizeScale(sizeScale) ; }
+
+    /**jsdoc
+     * @function EntityViewer.setBoundaryLevelAdjust
+     * @param {number} boundaryLevelAdjust
+     */
     void setBoundaryLevelAdjust(int boundaryLevelAdjust) { _octreeQuery.setBoundaryLevelAdjust(boundaryLevelAdjust); }
+
+    /**jsdoc
+     * @function EntityViewer.setMaxPacketsPerSecond
+     * @param {number} maxPacketsPerSecond
+     */
     void setMaxPacketsPerSecond(int maxPacketsPerSecond) { _octreeQuery.setMaxQueryPacketsPerSecond(maxPacketsPerSecond); }
 
     // getters for camera attributes
+
+    /**jsdoc
+     * @function EntityViewer.getPosition
+     * @returns {Vec3}
+     */
     const glm::vec3& getPosition() const { return _viewFrustum.getPosition(); }
+
+    /**jsdoc
+     * @function EntityViewer.getOrientation
+     * @returns {Quat}
+     */
     const glm::quat& getOrientation() const { return _viewFrustum.getOrientation(); }
 
+
     // getters for LOD and PPS
+
+    /**jsdoc
+     * @function EntityViewer.getVoxelSizeScale
+     * @returns {number}
+     */
     float getVoxelSizeScale() const { return _octreeQuery.getOctreeSizeScale(); }
+
+    /**jsdoc
+     * @function EntityViewer.
+     * @returns {number}
+     */
     int getBoundaryLevelAdjust() const { return _octreeQuery.getBoundaryLevelAdjust(); }
+    /**jsdoc
+     * @function EntityViewer.getMaxPacketsPerSecond
+     * @returns {number}
+     */
     int getMaxPacketsPerSecond() const { return _octreeQuery.getMaxQueryPacketsPerSecond(); }
 
+
+    /**jsdoc
+     * @function EntityViewer.getOctreeElementsCount
+     * @returns {number}
+     */
     unsigned getOctreeElementsCount() const { return _tree->getOctreeElementsCount(); }
 
 private:
diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js
index eb47bec430..de53f52f32 100644
--- a/tools/jsdoc/plugins/hifi.js
+++ b/tools/jsdoc/plugins/hifi.js
@@ -21,6 +21,8 @@ exports.handlers = {
         // directories to scan for jsdoc comments
         var dirList = [
             '../../assignment-client/src',
+            '../../assignment-client/src/entities',
+            '../../assignment-client/src/octree',
             '../../interface/src',
             '../../interface/src/assets',
             '../../interface/src/audio',