Fix Docs (#89)

MatthijsBurgh · web-flow · commit e9d35c4a8039 · 2022-05-03T15:23:09.000+02:00
* Add fileoverview tags

* Add library revision docstring

* (jsdoc) add markdown parser for option structures

* Convert first markdown option structure to correct jsdoc docs
diff --git a/Gruntfile.js b/Gruntfile.js
@@ -70,7 +70,8 @@ module.exports = function(grunt) {
           './src/**/*.js'
         ],
         options: {
-          destination: './doc'
+          destination: './doc',
+          configure: 'jsdoc_conf.json'
         }
       }
     }
diff --git a/jsdoc_conf.json b/jsdoc_conf.json
@@ -0,0 +1,6 @@
+{
+  "plugins": [ "plugins/markdown" ],
+  "markdown": {
+    "parser": "gfm"
+  }
+}
diff --git a/src/Ros2D.js b/src/Ros2D.js
@@ -1,8 +1,12 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  */
 
 var ROS2D = ROS2D || {
+  /**
+   * @description Library version
+   */
   REVISION : '0.9.0'
 };
 
diff --git a/src/maps/ImageMap.js b/src/maps/ImageMap.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  */
 
diff --git a/src/maps/ImageMapClient.js b/src/maps/ImageMapClient.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  */
 
diff --git a/src/maps/OccupancyGrid.js b/src/maps/OccupancyGrid.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  */
 
@@ -63,7 +64,7 @@ ROS2D.OccupancyGrid = function(options) {
   createjs.Bitmap.call(this, canvas);
   // change Y direction
   this.y = -this.height * message.info.resolution;
-  
+
   // scale the image
   this.scaleX = message.info.resolution;
   this.scaleY = message.info.resolution;
diff --git a/src/maps/OccupancyGridClient.js b/src/maps/OccupancyGridClient.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  */
 
diff --git a/src/maps/OccupancyGridSrvClient.js b/src/maps/OccupancyGridSrvClient.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Jihoon Lee- jihoonlee.in@gmail.com
  * @author Russell Toris - rctoris@wpi.edu
  */
diff --git a/src/models/ArrowShape.js b/src/models/ArrowShape.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Bart van Vliet - bart@dobots.nl
  */
 
@@ -7,12 +8,12 @@
  * Aims to the left at 0 rotation, as would be expected.
  *
  * @constructor
- * @param options - object with following keys:
- *   * size (optional) - the size of the marker
- *   * strokeSize (optional) - the size of the outline
- *   * strokeColor (optional) - the createjs color for the stroke
- *   * fillColor (optional) - the createjs color for the fill
- *   * pulse (optional) - if the marker should "pulse" over time
+ * @param {Object} options
+ * @param {Int} [options.size] - The size of the marker
+ * @param {Int} [options.strokeSize] - The size of the outline
+ * @param {String} [options.strokeColor] - The createjs color for the stroke
+ * @param {String} [options.fillColor] - The createjs color for the fill
+ * @param {Bool} [options.pulse] - If the marker should "pulse" over time
  */
 ROS2D.ArrowShape = function(options) {
 	var that = this;
@@ -22,29 +23,29 @@ ROS2D.ArrowShape = function(options) {
 	var strokeColor = options.strokeColor || createjs.Graphics.getRGB(0, 0, 0);
 	var fillColor = options.fillColor || createjs.Graphics.getRGB(255, 0, 0);
 	var pulse = options.pulse;
-	
+
 	// draw the arrow
 	var graphics = new createjs.Graphics();
-	
+
 	var headLen = size / 3.0;
 	var headWidth = headLen * 2.0 / 3.0;
-	
+
 	graphics.setStrokeStyle(strokeSize);
 	graphics.beginStroke(strokeColor);
 	graphics.moveTo(0, 0);
 	graphics.lineTo(size-headLen, 0);
-	
+
 	graphics.beginFill(fillColor);
 	graphics.moveTo(size, 0);
 	graphics.lineTo(size-headLen, headWidth / 2.0);
 	graphics.lineTo(size-headLen, -headWidth / 2.0);
 	graphics.closePath();
 	graphics.endFill();
 	graphics.endStroke();
-	
+
 	// create the shape
 	createjs.Shape.call(this, graphics);
-	
+
 	// check if we are pulsing
 	if (pulse) {
 		// have the model "pulse"
diff --git a/src/models/Grid.js b/src/models/Grid.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Raffaello Bonghi - raffaello.bonghi@officinerobotiche.it
  */
 
diff --git a/src/models/NavigationArrow.js b/src/models/NavigationArrow.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Russell Toris - rctoris@wpi.edu
  */
 
@@ -37,7 +38,7 @@ ROS2D.NavigationArrow = function(options) {
 
   // create the shape
   createjs.Shape.call(this, graphics);
-  
+
   // check if we are pulsing
   if (pulse) {
     // have the model "pulse"
diff --git a/src/models/NavigationImage.js b/src/models/NavigationImage.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Inigo Gonzalez - ingonza85@gmail.com
  */
 
diff --git a/src/models/PathShape.js b/src/models/PathShape.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Bart van Vliet - bart@dobots.nl
  */
 
@@ -16,10 +17,10 @@ ROS2D.PathShape = function(options) {
 	var path = options.path;
 	this.strokeSize = options.strokeSize || 3;
 	this.strokeColor = options.strokeColor || createjs.Graphics.getRGB(0, 0, 0);
-	
+
 	// draw the line
 	this.graphics = new createjs.Graphics();
-	
+
 	if (path !== null && typeof path !== 'undefined') {
 		this.graphics.setStrokeStyle(this.strokeSize);
 		this.graphics.beginStroke(this.strokeColor);
@@ -29,7 +30,7 @@ ROS2D.PathShape = function(options) {
 		}
 		this.graphics.endStroke();
 	}
-	
+
 	// create the shape
 	createjs.Shape.call(this, this.graphics);
 };
diff --git a/src/models/PolygonShape.js b/src/models/PolygonShape.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Bart van Vliet - bart@dobots.nl
  */
 
@@ -26,20 +27,20 @@ ROS2D.PolygonMarker = function(options) {
 	this.fillColor = options.pointColor || createjs.Graphics.getRGB(0, 255, 0, 0.33);
 	this.lineCallBack = options.lineCallBack;
 	this.pointCallBack = options.pointCallBack;
-	
+
 	// Array of point shapes
 //	this.points = [];
 	this.pointContainer = new createjs.Container();
-	
+
 	// Array of line shapes
 //	this.lines = [];
 	this.lineContainer = new createjs.Container();
-	
+
 	this.fillShape = new createjs.Shape();
-	
+
 	// Container with all the lines and points
 	createjs.Container.call(this);
-	
+
 	this.addChild(this.fillShape);
 	this.addChild(this.lineContainer);
 	this.addChild(this.pointContainer);
@@ -55,14 +56,14 @@ ROS2D.PolygonMarker.prototype.createLineShape = function(startPoint, endPoint) {
 //	line.graphics.moveTo(startPoint.x, startPoint.y);
 //	line.graphics.lineTo(endPoint.x, endPoint.y);
 	this.editLineShape(line, startPoint, endPoint);
-	
+
 	var that = this;
 	line.addEventListener('mousedown', function(event) {
 		if (that.lineCallBack !== null && typeof that.lineCallBack !== 'undefined') {
 			that.lineCallBack('mousedown', event, that.lineContainer.getChildIndex(event.target));
 		}
 	});
-	
+
 	return line;
 };
 
@@ -86,14 +87,14 @@ ROS2D.PolygonMarker.prototype.createPointShape = function(pos) {
 	point.graphics.drawCircle(0, 0, this.pointSize);
 	point.x = pos.x;
 	point.y = -pos.y;
-	
+
 	var that = this;
 	point.addEventListener('mousedown', function(event) {
 		if (that.pointCallBack !== null && typeof that.pointCallBack !== 'undefined') {
 			that.pointCallBack('mousedown', event, that.pointContainer.getChildIndex(event.target));
 		}
 	});
-	
+
 	return point;
 };
 
@@ -106,13 +107,13 @@ ROS2D.PolygonMarker.prototype.addPoint = function(pos) {
 	var point = this.createPointShape(pos);
 	this.pointContainer.addChild(point);
 	var numPoints = this.pointContainer.getNumChildren();
-	
+
 	// 0 points -> 1 point, 0 lines
 	// 1 point  -> 2 points, lines: add line between previous and new point, add line between new point and first point
 	// 2 points -> 3 points, 3 lines: change last line, add line between new point and first point
 	// 3 points -> 4 points, 4 lines: change last line, add line between new point and first point
 	// etc
-	
+
 	if (numPoints < 2) {
 		// Now 1 point
 	}
@@ -130,7 +131,7 @@ ROS2D.PolygonMarker.prototype.addPoint = function(pos) {
 		var lineEnd = this.createLineShape(point, this.pointContainer.getChildAt(0));
 		this.lineContainer.addChild(lineEnd);
 	}
-	
+
 	this.drawFill();
 };
 
@@ -150,18 +151,18 @@ ROS2D.PolygonMarker.prototype.remPoint = function(obj) {
 		index = obj;
 //		point = this.pointContainer.getChildAt(index);
 	}
-	
+
 	// 0 points -> 0 points, 0 lines
 	// 1 point  -> 0 points, 0 lines
 	// 2 points -> 1 point,  0 lines: remove all lines
 	// 3 points -> 2 points, 2 lines: change line before point to remove, remove line after point to remove
 	// 4 points -> 3 points, 3 lines: change line before point to remove, remove line after point to remove
 	// etc
-	
+
 	var numPoints = this.pointContainer.getNumChildren();
-	
+
 	if (numPoints < 2) {
-		
+
 	}
 	else if (numPoints < 3) {
 		// 2 points: remove all lines
@@ -178,7 +179,7 @@ ROS2D.PolygonMarker.prototype.remPoint = function(obj) {
 	}
 	this.pointContainer.removeChildAt(index);
 //	this.points.splice(index, 1);
-	
+
 	this.drawFill();
 };
 
@@ -201,18 +202,18 @@ ROS2D.PolygonMarker.prototype.movePoint = function(obj, newPos) {
 	}
 	point.x = newPos.x;
 	point.y = -newPos.y;
-	
+
 	var numPoints = this.pointContainer.getNumChildren();
 	if (numPoints > 1) {
 		// line before moved point
 		var line1 = this.lineContainer.getChildAt((index-1+numPoints)%numPoints);
 		this.editLineShape(line1, this.pointContainer.getChildAt((index-1+numPoints)%numPoints), point);
-		
+
 		// line after moved point
 		var line2 = this.lineContainer.getChildAt(index);
 		this.editLineShape(line2, point, this.pointContainer.getChildAt((index+1)%numPoints));
 	}
-	
+
 	this.drawFill();
 };
 
@@ -240,19 +241,19 @@ ROS2D.PolygonMarker.prototype.splitLine = function(obj) {
 	var xh = (xs+xe)/2.0;
 	var yh = (ys+ye)/2.0;
 	var pos = new ROSLIB.Vector3({ x:xh, y:-yh });
-	
+
 	// Add a point in the center of the line to split
 	var point = this.createPointShape(pos);
 	this.pointContainer.addChildAt(point, index+1);
 	++numPoints;
-	
+
 	// Add a line between the new point and the end of the line to split
 	var lineNew = this.createLineShape(point, this.pointContainer.getChildAt((index+2)%numPoints));
 	this.lineContainer.addChildAt(lineNew, index+1);
 
 	// Set the endpoint of the line to split to the new point
 	this.editLineShape(line, this.pointContainer.getChildAt(index), point);
-	
+
 	this.drawFill();
 };
 
diff --git a/src/models/TraceShape.js b/src/models/TraceShape.js
@@ -1,4 +1,5 @@
 /**
+ * @fileOverview
  * @author Bart van Vliet - bart@dobots.nl
  */
 
@@ -21,24 +22,24 @@ ROS2D.TraceShape = function(options) {
 	this.strokeColor = options.strokeColor || createjs.Graphics.getRGB(0, 0, 0);
 	this.maxPoses = options.maxPoses || 100;
 	this.minDist = options.minDist || 0.05;
-	
+
 	// Store minDist as the square of it
 	this.minDist = this.minDist*this.minDist;
-	
+
 	// Array of the poses
 	// TODO: do we need this?
 	this.poses = [];
-	
+
 	// Create the graphics
 	this.graphics = new createjs.Graphics();
 	this.graphics.setStrokeStyle(this.strokeSize);
 	this.graphics.beginStroke(this.strokeColor);
-	
+
 	// Add first pose if given
 	if (pose !== null && typeof pose !== 'undefined') {
 		this.poses.push(pose);
 	}
-	
+
 	// Create the shape
 	createjs.Shape.call(this, this.graphics);
 };
diff --git a/src/visualization/PanView.js b/src/visualization/PanView.js
diff --git a/src/visualization/Viewer.js b/src/visualization/Viewer.js
diff --git a/src/visualization/ZoomView.js b/src/visualization/ZoomView.js

Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,8 @@ module.exports = function(grunt) {`
`70`	`70`	`'./src/*/.js'`
`71`	`71`	`],`
`72`	`72`	`options: {`
`73`		`- destination: './doc'`
	`73`	`+ destination: './doc',`
	`74`	`+ configure: 'jsdoc_conf.json'`
`74`	`75`	`}`
`75`	`76`	`}`
`76`	`77`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`/**`
	`2`	`+ * @fileOverview`
`2`	`3`	`* @author Russell Toris - [email protected]`
`3`	`4`	`*/`
`4`	`5`