Improve docs (#533)

MatthijsBurgh · web-flow · commit bd8c7008aafa · 2022-05-03T14:58:21.000+02:00
* Add fileoverview tags

* Fix docstrings of global lib functions
diff --git a/examples/js/ColladaLoader.js b/examples/js/ColladaLoader.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author mrdoob / http://mrdoob.com/
  * @author Mugen87 / https://github.com/Mugen87
  *
diff --git a/shims/three/ColladaLoader.js b/shims/three/ColladaLoader.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author mrdoob / http://mrdoob.com/
  * @author Mugen87 / https://github.com/Mugen87
  *
diff --git a/shims/three/MTLLoader.js b/shims/three/MTLLoader.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * Loads a Wavefront .mtl file specifying materials
  *
  * @author angelxuanchang
diff --git a/shims/three/OBJLoader.js b/shims/three/OBJLoader.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author mrdoob / http://mrdoob.com/
  *
  * @Modified by Jose Rojas from OBJLoader.js@r106
diff --git a/shims/three/STLLoader.js b/shims/three/STLLoader.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author aleeper / http://adamleeper.com/
  * @author mrdoob / http://mrdoob.com/
  * @author gero3 / https://github.com/gero3
@@ -321,4 +322,4 @@ THREE.STLLoader.prototype = {
 
   }
 
-};
+};
diff --git a/src/Ros3D.js b/src/Ros3D.js
@@ -1,9 +1,13 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  * @author David Gossow - dgossow@willowgarage.com
  */
 
 var ROS3D = ROS3D || {
+  /**
+   * @description Library version
+   */
   REVISION : '1.1.0'
 };
 
@@ -47,7 +51,8 @@ ROS3D.INTERACTIVE_MARKER_FIXED = 1;
 ROS3D.INTERACTIVE_MARKER_VIEW_FACING = 2;
 
 /**
- * Create a THREE material based on the given RGBA values.
+ * @function makeColorMaterial
+ * @description Create a THREE material based on the given RGBA values.
  *
  * @param r - the red value
  * @param g - the green value
@@ -79,7 +84,8 @@ ROS3D.makeColorMaterial = function(r, g, b, a) {
 };
 
 /**
- * Return the intersection between the mouseray and the plane.
+ * @function intersectPlane
+ * @description Return the intersection between the mouseray and the plane.
  *
  * @param mouseRay - the mouse ray
  * @param planeOrigin - the origin of the plane
@@ -105,7 +111,8 @@ ROS3D.intersectPlane = function(mouseRay, planeOrigin, planeNormal) {
 };
 
 /**
- * Find the closest point on targetRay to any point on mouseRay. Math taken from
+ * @function findClosestPoint
+ * @description Find the closest point on targetRay to any point on mouseRay. Math taken from
  * http://paulbourke.net/geometry/lineline3d/
  *
  * @param targetRay - the target ray to use
@@ -135,7 +142,8 @@ ROS3D.findClosestPoint = function(targetRay, mouseRay) {
 };
 
 /**
- * Find the closest point between the axis and the mouse.
+ * @function closestAxisPoint
+ * @description Find the closest point between the axis and the mouse.
  *
  * @param axisRay - the ray from the axis
  * @param camera - the camera to project from
diff --git a/src/depthcloud/DepthCloud.js b/src/depthcloud/DepthCloud.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Julius Kammerl - jkammerl@willowgarage.com
  */
 
diff --git a/src/interactivemarkers/InteractiveMarker.js b/src/interactivemarkers/InteractiveMarker.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  */
 
diff --git a/src/interactivemarkers/InteractiveMarkerClient.js b/src/interactivemarkers/InteractiveMarkerClient.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  */
 
diff --git a/src/interactivemarkers/InteractiveMarkerControl.js b/src/interactivemarkers/InteractiveMarkerControl.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  */
 
diff --git a/src/interactivemarkers/InteractiveMarkerHandle.js b/src/interactivemarkers/InteractiveMarkerHandle.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  */
 
diff --git a/src/interactivemarkers/InteractiveMarkerMenu.js b/src/interactivemarkers/InteractiveMarkerMenu.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  */
 
diff --git a/src/markers/Marker.js b/src/markers/Marker.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  * @author Russell Toris - rctoris@wpi.edu
  */
diff --git a/src/markers/MarkerArrayClient.js b/src/markers/MarkerArrayClient.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  * @author Nils Berg - berg.nils@gmail.com
  */
diff --git a/src/markers/MarkerClient.js b/src/markers/MarkerClient.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  */
 
diff --git a/src/models/Arrow.js b/src/models/Arrow.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  */
 
diff --git a/src/models/Arrow2.js b/src/models/Arrow2.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Jihoon Lee - lee@magazino.eu
  */
 
diff --git a/src/models/Axes.js b/src/models/Axes.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  */
 
diff --git a/src/models/Grid.js b/src/models/Grid.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  */
 
diff --git a/src/models/MeshLoader.js b/src/models/MeshLoader.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Jose Rojas - jrojas@redlinesolutions.co
  */
 
diff --git a/src/models/MeshResource.js b/src/models/MeshResource.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Jihoon Lee - jihoonlee.in@gmail.com
  * @author Russell Toris - rctoris@wpi.edu
  */
diff --git a/src/models/TriangleList.js b/src/models/TriangleList.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  */
 
diff --git a/src/navigation/ColorOcTree.js b/src/navigation/ColorOcTree.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Peter Sari - sari@photoneo.com
  */
 
diff --git a/src/navigation/OcTree.js b/src/navigation/OcTree.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Peter Sari - sari@photoneo.com
  */
 
diff --git a/src/navigation/OcTreeBase.js b/src/navigation/OcTreeBase.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Peter Sari - sari@photoneo.com
  */
 
diff --git a/src/navigation/OcTreeBaseNode.js b/src/navigation/OcTreeBaseNode.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Peter Sari - sari@photoneo.com
  */
 
diff --git a/src/navigation/OcTreeClient.js b/src/navigation/OcTreeClient.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Peter Sari - sari@photoneo.com
  */
 
diff --git a/src/navigation/OccupancyGrid.js b/src/navigation/OccupancyGrid.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  */
 
diff --git a/src/navigation/OccupancyGridClient.js b/src/navigation/OccupancyGridClient.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  */
 
diff --git a/src/navigation/Odometry.js b/src/navigation/Odometry.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David V. Lu!! - davidvlu@gmail.com
  */
 
diff --git a/src/navigation/Path.js b/src/navigation/Path.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David V. Lu!! - davidvlu@gmail.com
  */
 
diff --git a/src/navigation/Point.js b/src/navigation/Point.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David V. Lu!! - davidvlu@gmail.com
  */
 
diff --git a/src/navigation/Polygon.js b/src/navigation/Polygon.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David V. Lu!! - davidvlu@gmail.com
  */
 
diff --git a/src/navigation/Pose.js b/src/navigation/Pose.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David V. Lu!! - davidvlu@gmail.com
  */
 
diff --git a/src/navigation/PoseArray.js b/src/navigation/PoseArray.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David V. Lu!! - davidvlu@gmail.com
  */
 
diff --git a/src/navigation/PoseWithCovariance.js b/src/navigation/PoseWithCovariance.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David V. Lu!! - davidvlu@gmail.com
  */
 
diff --git a/src/sensors/LaserScan.js b/src/sensors/LaserScan.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David V. Lu!! - davidvlu@gmail.com
  */
 
diff --git a/src/sensors/NavSatFix.js b/src/sensors/NavSatFix.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Mathieu Bredif - mathieu.bredif@ign.fr
  */
 
diff --git a/src/sensors/PointCloud2.js b/src/sensors/PointCloud2.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David V. Lu!! - davidvlu@gmail.com
  * @author Mathieu Bredif - mathieu.bredif@ign.fr
  */
diff --git a/src/sensors/Points.js b/src/sensors/Points.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David V. Lu!! - davidvlu@gmail.com
  * @author Mathieu Bredif - mathieu.bredif@ign.fr
  */
diff --git a/src/sensors/TFAxes.js b/src/sensors/TFAxes.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Jihoon Lee - jihoon.lee@kakaobrain.com
  */
 /**
diff --git a/src/urdf/Urdf.js b/src/urdf/Urdf.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Jihoon Lee - jihoonlee.in@gmail.com
  * @author Russell Toris - rctoris@wpi.edu
  */
diff --git a/src/urdf/UrdfClient.js b/src/urdf/UrdfClient.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Jihoon Lee - jihoonlee.in@gmail.com
  * @author Russell Toris - rctoris@wpi.edu
  */
diff --git a/src/visualization/SceneNode.js b/src/visualization/SceneNode.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Jihoon Lee - jihoonlee.in@gmail.com
  * @author Russell Toris - rctoris@wpi.edu
  */
diff --git a/src/visualization/Viewer.js b/src/visualization/Viewer.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  * @author Russell Toris - rctoris@wpi.edu
  * @author Jihoon Lee - jihoonlee.in@gmail.com
diff --git a/src/visualization/interaction/Highlighter.js b/src/visualization/interaction/Highlighter.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  */
 
diff --git a/src/visualization/interaction/MouseHandler.js b/src/visualization/interaction/MouseHandler.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  */
 
diff --git a/src/visualization/interaction/OrbitControls.js b/src/visualization/interaction/OrbitControls.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author David Gossow - dgossow@willowgarage.com
  * @author Xueqiao Xu - xueqiaoxu@gmail.com
  * @author Mr.doob - http://mrdoob.com

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`/**`
	`2`	`+ * @fileOverview`
`2`	`3`	`* @author mrdoob / http://mrdoob.com/`
`3`	`4`	`* @author Mugen87 / https://github.com/Mugen87`
`4`	`5`	`*`