Standardize and improve docstring (RobotWebTools#562)

* Standardize JSDoc format and add proper types to JSDoc

- Fix typos
- For method JSDoc starting with a verb, standardize the verbs to be without the `-s` suffix
- Add proper capitalization to JSDoc
- Rephrase some JSDoc to make it clearer
- Add parameter and return types to JSDoc
- Add proper indication of optional parameters to JSDoc

* Remove dead code in ActionListener

* Lint whitespace and align ActionServer param name with JSDoc

* Refactor Ros.js to align callback parameters with JSDoc

* Update check-topics tests

* Fix check-topics example test

* Revert breaking changes and align docstring to impl as source of truth

* Remove 'An object with the following keys'

* Specify default param values explicitly in docstring

Co-authored-by: Matthijs van der Burgh <[email protected]>

* Fix typos

* Specify more default param values

Co-authored-by: Matthijs van der Burgh <[email protected]>
Co-authored-by: Matthijs van der Burgh <[email protected]>

src/RosLib.js

@@ -6,7 +6,7 @@
 /**
  * If you use roslib in a browser, all the classes will be exported to a global variable called ROSLIB.
  *
- * If you use nodejs, this is the variable you get when you require('roslib')
+ * If you use nodejs, this is the variable you get when you require('roslib').
  */
 var ROSLIB = this.ROSLIB || {
   /**

src/actionlib/ActionClient.js

@@ -11,20 +11,20 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2;
  * An actionlib action client.
  *
  * Emits the following events:
- *  * 'timeout' - if a timeout occurred while sending a goal
- *  * 'status' - the status messages received from the action server
- *  * 'feedback' -  the feedback messages received from the action server
- *  * 'result' - the result returned from the action server
+ *  * 'timeout' - If a timeout occurred while sending a goal.
+ *  * 'status' - The status messages received from the action server.
+ *  * 'feedback' - The feedback messages received from the action server.
+ *  * 'result' - The result returned from the action server.
  *
- *  @constructor
- *  @param options - object with following keys:
- *   * ros - the ROSLIB.Ros connection handle
- *   * serverName - the action server name, like /fibonacci
- *   * actionName - the action message name, like 'actionlib_tutorials/FibonacciAction'
- *   * timeout - the timeout length when connecting to the action server
- *   * omitFeedback - the boolean flag to indicate whether to omit the feedback channel or not
- *   * omitStatus - the boolean flag to indicate whether to omit the status channel or not
- *   * omitResult - the boolean flag to indicate whether to omit the result channel or not
+ * @constructor
+ * @param {Object} options
+ * @param {Ros} options.ros - The ROSLIB.Ros connection handle.
+ * @param {string} options.serverName - The action server name, like '/fibonacci'.
+ * @param {string} options.actionName - The action message name, like 'actionlib_tutorials/FibonacciAction'.
+ * @param {number} [options.timeout] - The timeout length when connecting to the action server.
+ * @param {boolean} [options.omitFeedback] - The flag to indicate whether to omit the feedback channel or not.
+ * @param {boolean} [options.omitStatus] - The flag to indicate whether to omit the status channel or not.
+ * @param {boolean} [options.omitResult] - The flag to indicate whether to omit the result channel or not.
  */
 function ActionClient(options) {
   var that = this;

src/actionlib/ActionListener.js

@@ -9,29 +9,25 @@ var Message = require('../core/Message');
 var EventEmitter2 = require('eventemitter2').EventEmitter2;
 
 /**
- * An actionlib action listener
+ * An actionlib action listener.
  *
  * Emits the following events:
- *  * 'status' - the status messages received from the action server
- *  * 'feedback' -  the feedback messages received from the action server
- *  * 'result' - the result returned from the action server
+ *  * 'status' - The status messages received from the action server.
+ *  * 'feedback' - The feedback messages received from the action server.
+ *  * 'result' - The result returned from the action server.
  *
- *  @constructor
- *  @param options - object with following keys:
- *   * ros - the ROSLIB.Ros connection handle
- *   * serverName - the action server name, like /fibonacci
- *   * actionName - the action message name, like 'actionlib_tutorials/FibonacciAction'
+ * @constructor
+ * @param {Object} options
+ * @param {Ros} options.ros - The ROSLIB.Ros connection handle.
+ * @param {string} options.serverName - The action server name, like '/fibonacci'.
+ * @param {string} options.actionName - The action message name, like 'actionlib_tutorials/FibonacciAction'.
  */
 function ActionListener(options) {
   var that = this;
   options = options || {};
   this.ros = options.ros;
   this.serverName = options.serverName;
   this.actionName = options.actionName;
-  this.timeout = options.timeout;
-  this.omitFeedback = options.omitFeedback;
-  this.omitStatus = options.omitStatus;
-  this.omitResult = options.omitResult;
 
 
   // create the topics associated with actionlib

src/actionlib/Goal.js

@@ -7,15 +7,15 @@ var Message = require('../core/Message');
 var EventEmitter2 = require('eventemitter2').EventEmitter2;
 
 /**
- * An actionlib goal goal is associated with an action server.
+ * An actionlib goal that is associated with an action server.
  *
  * Emits the following events:
- *  * 'timeout' - if a timeout occurred while sending a goal
+ *  * 'timeout' - If a timeout occurred while sending a goal.
  *
- *  @constructor
- *  @param object with following keys:
- *   * actionClient - the ROSLIB.ActionClient to use with this goal
- *   * goalMessage - The JSON object containing the goal for the action server
+ * @constructor
+ * @param {Object} options
+ * @param {ActionClient} options.actionClient - The ROSLIB.ActionClient to use with this goal.
+ * @param {Object} options.goalMessage - The JSON object containing the goal for the action server.
  */
 function Goal(options) {
   var that = this;
@@ -62,7 +62,7 @@ Goal.prototype.__proto__ = EventEmitter2.prototype;
 /**
  * Send the goal to the action server.
  *
- * @param timeout (optional) - a timeout length for the goal's result
+ * @param {number} [timeout] - A timeout length for the goal's result.
  */
 Goal.prototype.send = function(timeout) {
   var that = this;
@@ -86,4 +86,4 @@ Goal.prototype.cancel = function() {
   this.actionClient.cancelTopic.publish(cancelMessage);
 };
 
-module.exports = Goal;
+module.exports = Goal;

src/actionlib/SimpleActionServer.js

@@ -11,16 +11,15 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2;
  * An actionlib action server client.
  *
  * Emits the following events:
- *  * 'goal' - goal sent by action client
- *  * 'cancel' - action client has canceled the request
+ *  * 'goal' - Goal sent by action client.
+ *  * 'cancel' - Action client has canceled the request.
  *
- *  @constructor
- *  @param options - object with following keys:
- *   * ros - the ROSLIB.Ros connection handle
- *   * serverName - the action server name, like /fibonacci
- *   * actionName - the action message name, like 'actionlib_tutorials/FibonacciAction'
+ * @constructor
+ * @param {Object} options
+ * @param {Ros} options.ros - The ROSLIB.Ros connection handle.
+ * @param {string} options.serverName - The action server name, like '/fibonacci'.
+ * @param {string} options.actionName - The action message name, like 'actionlib_tutorials/FibonacciAction'.
  */
-
 function SimpleActionServer(options) {
     var that = this;
     options = options || {};
@@ -77,7 +76,7 @@ function SimpleActionServer(options) {
     this.nextGoal = null; // the one that'll be preempting
 
     goalListener.subscribe(function(goalMessage) {
-        
+
     if(that.currentGoal) {
             that.nextGoal = goalMessage;
             // needs to happen AFTER rest is set up
@@ -89,7 +88,7 @@ function SimpleActionServer(options) {
     }
     });
 
-    // helper function for determing ordering of timestamps
+    // helper function to determine ordering of timestamps
     // returns t1 < t2
     var isEarlier = function(t1, t2) {
         if(t1.secs > t2.secs) {
@@ -128,7 +127,6 @@ function SimpleActionServer(options) {
             }
             if(that.currentGoal && isEarlier(that.currentGoal.goal_id.stamp,
                                              cancelMessage.stamp)) {
-
                 that.emit('cancel');
             }
         }
@@ -149,15 +147,14 @@ function SimpleActionServer(options) {
 SimpleActionServer.prototype.__proto__ = EventEmitter2.prototype;
 
 /**
-*  Set action state to succeeded and return to client
-*/
-
-SimpleActionServer.prototype.setSucceeded = function(result2) {
-
-
+ * Set action state to succeeded and return to client.
+ *
+ * @param {Object} result - The result to return to the client.
+ */
+SimpleActionServer.prototype.setSucceeded = function(result) {
     var resultMessage = new Message({
         status : {goal_id : this.currentGoal.goal_id, status : 3},
-        result : result2
+        result : result
     });
     this.resultPublisher.publish(resultMessage);
 
@@ -172,13 +169,14 @@ SimpleActionServer.prototype.setSucceeded = function(result2) {
 };
 
 /**
-*  Set action state to aborted and return to client
-*/
-
-SimpleActionServer.prototype.setAborted = function(result2) {
+ * Set action state to aborted and return to client.
+ *
+ * @param {Object} result - The result to return to the client.
+ */
+SimpleActionServer.prototype.setAborted = function(result) {
     var resultMessage = new Message({
         status : {goal_id : this.currentGoal.goal_id, status : 4},
-        result : result2
+        result : result
     });
     this.resultPublisher.publish(resultMessage);
 
@@ -193,24 +191,22 @@ SimpleActionServer.prototype.setAborted = function(result2) {
 };
 
 /**
-*  Function to send feedback
-*/
-
-SimpleActionServer.prototype.sendFeedback = function(feedback2) {
-
+ * Send a feedback message.
+ *
+ * @param {Object} feedback - The feedback to send to the client.
+ */
+SimpleActionServer.prototype.sendFeedback = function(feedback) {
     var feedbackMessage = new Message({
         status : {goal_id : this.currentGoal.goal_id, status : 1},
-        feedback : feedback2
+        feedback : feedback
     });
     this.feedbackPublisher.publish(feedbackMessage);
 };
 
 /**
-*  Handle case where client requests preemption
-*/
-
+ * Handle case where client requests preemption.
+ */
 SimpleActionServer.prototype.setPreempted = function() {
-
     this.statusMessage.status_list = [];
     var resultMessage = new Message({
         status : {goal_id : this.currentGoal.goal_id, status : 2},
@@ -226,4 +222,4 @@ SimpleActionServer.prototype.setPreempted = function() {
     }
 };
 
-module.exports = SimpleActionServer;
+module.exports = SimpleActionServer;

src/core/Message.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview
+ * @fileOverview
  * @author Brandon Alexander - [email protected]
  */
 
@@ -9,7 +9,7 @@ var assign = require('object-assign');
  * Message objects are used for publishing and subscribing to and from topics.
  *
  * @constructor
- * @param values - object matching the fields defined in the .msg definition file
+ * @param {Object} values - An object matching the fields defined in the .msg definition file.
  */
 function Message(values) {
   assign(this, values);

src/core/Param.js

@@ -1,5 +1,5 @@
 /**
- * @fileoverview
+ * @fileOverview
  * @author Brandon Alexander - [email protected]
  */
 
@@ -10,9 +10,9 @@ var ServiceRequest = require('./ServiceRequest');
  * A ROS parameter.
  *
  * @constructor
- * @param options - possible keys include:
- *   * ros - the ROSLIB.Ros connection handle
- *   * name - the param name, like max_vel_x
+ * @param {Object} options
+ * @param {Ros} options.ros - The ROSLIB.Ros connection handle.
+ * @param {string} options.name - The param name, like max_vel_x.
  */
 function Param(options) {
   options = options || {};
@@ -21,10 +21,10 @@ function Param(options) {
 }
 
 /**
- * Fetches the value of the param.
+ * Fetch the value of the param.
  *
- * @param callback - function with the following params:
- *  * value - the value of the param from ROS.
+ * @param {function} callback - Function with the following params:
+ * @param {Object} callback.value - The value of the param from ROS.
  */
 Param.prototype.get = function(callback) {
   var paramClient = new Service({
@@ -44,9 +44,10 @@ Param.prototype.get = function(callback) {
 };
 
 /**
- * Sets the value of the param in ROS.
+ * Set the value of the param in ROS.
  *
- * @param value - value to set param to.
+ * @param {Object} value - The value to set param to.
+ * @param {function} callback - The callback function.
  */
 Param.prototype.set = function(value, callback) {
   var paramClient = new Service({
@@ -65,6 +66,8 @@ Param.prototype.set = function(value, callback) {
 
 /**
  * Delete this parameter on the ROS server.
+ *
+ * @param {function} callback - The callback function.
  */
 Param.prototype.delete = function(callback) {
   var paramClient = new Service({
@@ -80,4 +83,4 @@ Param.prototype.delete = function(callback) {
   paramClient.callService(request, callback);
 };
 
-module.exports = Param;
+module.exports = Param;