From f43e6f570524f62eb4ac6b78dbaf733a36214c81 Mon Sep 17 00:00:00 2001 From: James R T Date: Sat, 27 Aug 2022 22:36:54 +0800 Subject: [PATCH 01/11] 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 --- src/RosLib.js | 2 +- src/actionlib/ActionClient.js | 26 ++-- src/actionlib/ActionListener.js | 18 +-- src/actionlib/Goal.js | 14 +- src/actionlib/SimpleActionServer.js | 38 +++-- src/core/Message.js | 4 +- src/core/Param.js | 21 +-- src/core/Ros.js | 232 ++++++++++++++-------------- src/core/Service.js | 32 ++-- src/core/ServiceRequest.js | 4 +- src/core/ServiceResponse.js | 4 +- src/core/SocketAdapter.js | 18 +-- src/core/Topic.js | 48 +++--- src/math/Pose.js | 22 +-- src/math/Quaternion.js | 18 +-- src/math/Transform.js | 12 +- src/math/Vector3.js | 20 +-- src/node/RosTCP.js | 12 +- src/node/TopicStream.js | 12 +- src/tf/TFClient.js | 48 +++--- src/urdf/UrdfBox.js | 6 +- src/urdf/UrdfColor.js | 6 +- src/urdf/UrdfCylinder.js | 6 +- src/urdf/UrdfJoint.js | 6 +- src/urdf/UrdfLink.js | 6 +- src/urdf/UrdfMaterial.js | 6 +- src/urdf/UrdfMesh.js | 6 +- src/urdf/UrdfModel.js | 6 +- src/urdf/UrdfSphere.js | 6 +- src/urdf/UrdfVisual.js | 6 +- src/util/cborTypedArrayTags.js | 17 +- src/util/decompressPng.js | 6 +- src/util/shim/decompressPng.js | 6 +- 33 files changed, 354 insertions(+), 340 deletions(-) diff --git a/src/RosLib.js b/src/RosLib.js index fc59e80a7..81397fb84 100644 --- a/src/RosLib.js +++ b/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 || { /** diff --git a/src/actionlib/ActionClient.js b/src/actionlib/ActionClient.js index 1f63f2de2..85019cbcd 100644 --- a/src/actionlib/ActionClient.js +++ b/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 - An object with the following keys: + * @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; diff --git a/src/actionlib/ActionListener.js b/src/actionlib/ActionListener.js index 2553dc480..f5108666b 100644 --- a/src/actionlib/ActionListener.js +++ b/src/actionlib/ActionListener.js @@ -9,18 +9,18 @@ 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 - An object with the following keys: + * @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; diff --git a/src/actionlib/Goal.js b/src/actionlib/Goal.js index 881475b09..293b4de0a 100644 --- a/src/actionlib/Goal.js +++ b/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 - An object with the following keys: + * @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; diff --git a/src/actionlib/SimpleActionServer.js b/src/actionlib/SimpleActionServer.js index 6ce70a870..f2087b508 100644 --- a/src/actionlib/SimpleActionServer.js +++ b/src/actionlib/SimpleActionServer.js @@ -11,14 +11,14 @@ 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 - An object with the following keys: + * @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) { @@ -89,7 +89,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) { @@ -149,8 +149,10 @@ function SimpleActionServer(options) { SimpleActionServer.prototype.__proto__ = EventEmitter2.prototype; /** -* Set action state to succeeded and return to client -*/ + * Set action state to succeeded and return to client. + * + * @param {Object} result - The result to return to the client. + */ SimpleActionServer.prototype.setSucceeded = function(result2) { @@ -172,8 +174,10 @@ SimpleActionServer.prototype.setSucceeded = function(result2) { }; /** -* Set action state to aborted and return to client -*/ + * Set action state to aborted and return to client. + * + * @param {Object} result - The result to return to the client. + */ SimpleActionServer.prototype.setAborted = function(result2) { var resultMessage = new Message({ @@ -193,8 +197,10 @@ SimpleActionServer.prototype.setAborted = function(result2) { }; /** -* Function to send feedback -*/ + * Send a feedback message. + * + * @param {Object} feedback - The feedback to send to the client. + */ SimpleActionServer.prototype.sendFeedback = function(feedback2) { @@ -206,8 +212,8 @@ SimpleActionServer.prototype.sendFeedback = function(feedback2) { }; /** -* Handle case where client requests preemption -*/ + * Handle case where client requests preemption. + */ SimpleActionServer.prototype.setPreempted = function() { diff --git a/src/core/Message.js b/src/core/Message.js index 5cb1f7d48..4dbec3e16 100644 --- a/src/core/Message.js +++ b/src/core/Message.js @@ -1,5 +1,5 @@ /** - * @fileoverview + * @fileOverview * @author Brandon Alexander - baalexander@gmail.com */ @@ -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); diff --git a/src/core/Param.js b/src/core/Param.js index 03b85df39..f03d3caba 100644 --- a/src/core/Param.js +++ b/src/core/Param.js @@ -1,5 +1,5 @@ /** - * @fileoverview + * @fileOverview * @author Brandon Alexander - baalexander@gmail.com */ @@ -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 - An object with the following keys: + * @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({ diff --git a/src/core/Ros.js b/src/core/Ros.js index 71c2632d5..4bc792aec 100644 --- a/src/core/Ros.js +++ b/src/core/Ros.js @@ -1,5 +1,5 @@ /** - * @fileoverview + * @fileOverview * @author Brandon Alexander - baalexander@gmail.com */ @@ -17,18 +17,18 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2; * Manages connection to the server and all interactions with ROS. * * Emits the following events: - * * 'error' - there was an error with ROS - * * 'connection' - connected to the WebSocket server - * * 'close' - disconnected to the WebSocket server - * * - a message came from rosbridge with the given topic name - * * - a service response came from rosbridge with the given ID + * * 'error' - There was an error with ROS. + * * 'connection' - Connected to the WebSocket server. + * * 'close' - Disconnected to the WebSocket server. + * * <topicName> - A message came from rosbridge with the given topic name. + * * <serviceID> - A service response came from rosbridge with the given ID. * * @constructor - * @param options - possible keys include:
- * * url (optional) - (can be specified later with `connect`) the WebSocket URL for rosbridge or the node server url to connect using socket.io (if socket.io exists in the page)
- * * groovyCompatibility - don't use interfaces that changed after the last groovy release or rosbridge_suite and related tools (defaults to true) - * * transportLibrary (optional) - one of 'websocket', 'workersocket' (default), 'socket.io' or RTCPeerConnection instance controlling how the connection is created in `connect`. - * * transportOptions (optional) - the options to use use when creating a connection. Currently only used if `transportLibrary` is RTCPeerConnection. + * @param {Object} options - An object with the following keys: + * @param {string} [options.url] - The WebSocket URL for rosbridge or the node server URL to connect using socket.io (if socket.io exists in the page). Can be specified later with `connect`. + * @param {boolean} [options.groovyCompatibility] - Don't use interfaces that changed after the last groovy release or rosbridge_suite and related tools (defaults to true). + * @param {string} [options.transportLibrary] - One of 'websocket', 'workersocket' (default), 'socket.io' or RTCPeerConnection instance controlling how the connection is created in `connect`. + * @param {Object} [options.transportOptions] - The options to use when creating a connection. Currently only used if `transportLibrary` is RTCPeerConnection. */ function Ros(options) { options = options || {}; @@ -61,7 +61,7 @@ Ros.prototype.__proto__ = EventEmitter2.prototype; /** * Connect to the specified WebSocket. * - * @param url - WebSocket URL or RTCDataChannel label for Rosbridge + * @param {string} url - WebSocket URL or RTCDataChannel label for rosbridge. */ Ros.prototype.connect = function(url) { if (this.transportLibrary === 'socket.io') { @@ -96,15 +96,15 @@ Ros.prototype.close = function() { }; /** - * Sends an authorization request to the server. + * Send an authorization request to the server. * - * @param mac - MAC (hash) string given by the trusted source. - * @param client - IP of the client. - * @param dest - IP of the destination. - * @param rand - Random string given by the trusted source. - * @param t - Time of the authorization request. - * @param level - User level as a string given by the client. - * @param end - End time of the client's session. + * @param {string} mac - MAC (hash) string given by the trusted source. + * @param {string} client - IP of the client. + * @param {string} dest - IP of the destination. + * @param {string} rand - Random string given by the trusted source. + * @param {Object} t - Time of the authorization request. + * @param {string} level - User level as a string given by the client. + * @param {Object} end - End time of the client's session. */ Ros.prototype.authenticate = function(mac, client, dest, rand, t, level, end) { // create the request @@ -122,7 +122,12 @@ Ros.prototype.authenticate = function(mac, client, dest, rand, t, level, end) { this.callOnConnection(auth); }; -Ros.prototype.sendEncodedMessage= function(messageEncoded) { +/** + * Send an encoded message over the WebSocket. + * + * @param {Object} messageEncoded - The encoded message to be sent. + */ +Ros.prototype.sendEncodedMessage = function(messageEncoded) { var emitter = null; var that = this; if (this.transportLibrary === 'socket.io') { @@ -141,8 +146,10 @@ Ros.prototype.sendEncodedMessage= function(messageEncoded) { }; /** - * Sends the message over the WebSocket, but queues the message up if not yet + * Send the message over the WebSocket, but queue the message up if not yet * connected. + * + * @param {Object} message - The message to be sent. */ Ros.prototype.callOnConnection = function(message) { if (this.transportOptions.encoder) { @@ -153,10 +160,10 @@ Ros.prototype.callOnConnection = function(message) { }; /** - * Sends a set_level request to the server + * Send a set_level request to the server. * - * @param level - Status level (none, error, warning, info) - * @param id - Optional: Operation ID to change status level on + * @param {string} level - Status level (none, error, warning, info). + * @param {number} [id] - Operation ID to change status level on. */ Ros.prototype.setStatusLevel = function(level, id){ var levelMsg = { @@ -169,12 +176,12 @@ Ros.prototype.setStatusLevel = function(level, id){ }; /** - * Retrieves Action Servers in ROS as an array of string + * Retrieve a list of action servers in ROS as an array of string. * - * @param callback function with params: - * * actionservers - Array of action server names - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {function} callback - Function with the following params: + * @param {string[]} callback.actionservers - Array of action server names. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getActionServers = function(callback, failedCallback) { var getActionServers = new Service({ @@ -201,13 +208,13 @@ Ros.prototype.getActionServers = function(callback, failedCallback) { }; /** - * Retrieves list of topics in ROS as an array. + * Retrieve a list of topics in ROS as an array. * - * @param callback function with params: - * * topics - Array of topic names - * * types - Array of message type names - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {function} callback - Function with the following params: + * @param {string[]} callback.topics - Array of topic names. + * @param {string[]} callback.types - Array of message type names. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getTopics = function(callback, failedCallback) { var topicsClient = new Service({ @@ -234,13 +241,13 @@ Ros.prototype.getTopics = function(callback, failedCallback) { }; /** - * Retrieves Topics in ROS as an array as specific type + * Retrieve a list of topics in ROS as an array of a specific type. * - * @param topicType topic type to find - * @param callback function with params: - * * topics - Array of topic names - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {string} topicType - The topic type to find. + * @param {function} callback - Function with the following params: + * @param {string[]} callback.topics - Array of topic names. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getTopicsForType = function(topicType, callback, failedCallback) { var topicsForTypeClient = new Service({ @@ -269,12 +276,12 @@ Ros.prototype.getTopicsForType = function(topicType, callback, failedCallback) { }; /** - * Retrieves list of active service names in ROS. + * Retrieve a list of active service names in ROS. * - * @param callback - function with the following params: - * * services - array of service names - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {function} callback - Function with the following params: + * @param {string[]} callback.services - Array of service names. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getServices = function(callback, failedCallback) { var servicesClient = new Service({ @@ -301,13 +308,13 @@ Ros.prototype.getServices = function(callback, failedCallback) { }; /** - * Retrieves list of services in ROS as an array as specific type + * Retrieve a list of services in ROS as an array as specific type. * - * @param serviceType service type to find - * @param callback function with params: - * * topics - Array of service names - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {string} serviceType - The service type to find. + * @param {function} callback - Function with the following params: + * @param {string[]} callback.topics - Array of service names. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getServicesForType = function(serviceType, callback, failedCallback) { var servicesForTypeClient = new Service({ @@ -336,13 +343,13 @@ Ros.prototype.getServicesForType = function(serviceType, callback, failedCallbac }; /** - * Retrieves a detail of ROS service request. + * Retrieve the details of a ROS service request. * - * @param service name of service: - * @param callback - function with params: - * * type - String of the service type - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {string} type - The type of the service. + * @param {function} callback - Function with the following params: + * @param {string} callback.details - The details of the service request. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getServiceRequestDetails = function(type, callback, failedCallback) { var serviceTypeClient = new Service({ @@ -371,13 +378,13 @@ Ros.prototype.getServiceRequestDetails = function(type, callback, failedCallback }; /** - * Retrieves a detail of ROS service request. + * Retrieve the details of a ROS service response. * - * @param service name of service - * @param callback - function with params: - * * type - String of the service type - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {string} type - The type of the service. + * @param {function} callback - Function with the following params: + * @param {string} callback.details - The details of the service response. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getServiceResponseDetails = function(type, callback, failedCallback) { var serviceTypeClient = new Service({ @@ -406,12 +413,12 @@ Ros.prototype.getServiceResponseDetails = function(type, callback, failedCallbac }; /** - * Retrieves list of active node names in ROS. + * Retrieve a list of active node names in ROS. * - * @param callback - function with the following params: - * * nodes - array of node names - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {function} callback - Function with the following params: + * @param {string[]} callback.nodes - Array of node names. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getNodes = function(callback, failedCallback) { var nodesClient = new Service({ @@ -438,16 +445,16 @@ Ros.prototype.getNodes = function(callback, failedCallback) { }; /** - * Retrieves list subscribed topics, publishing topics and services of a specific node - * - * @param node name of the node: - * @param callback - function with params: - * * publications - array of published topic names - * * subscriptions - array of subscribed topic names - * * services - array of service names hosted - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS - */ + * Retrieve a list of subscribed topics, publishing topics and services of a specific node. + * + * @param {string} node - Name of the node. + * @param {function} callback - Function with the following params: + * @param {string[]} callback.subscriptions - Array of subscribed topic names. + * @param {string[]} callback.publications - Array of published topic names. + * @param {string[]} callback.services - Array of service names hosted. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. + */ Ros.prototype.getNodeDetails = function(node, callback, failedCallback) { var nodesClient = new Service({ ros : this, @@ -475,12 +482,12 @@ Ros.prototype.getNodeDetails = function(node, callback, failedCallback) { }; /** - * Retrieves list of param names from the ROS Parameter Server. + * Retrieve a list of parameter names from the ROS Parameter Server. * - * @param callback function with params: - * * params - array of param names. - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {function} callback - Function with the following params: + * @param {string[]} callback.params - Array of param names. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getParams = function(callback, failedCallback) { var paramsClient = new Service({ @@ -506,13 +513,13 @@ Ros.prototype.getParams = function(callback, failedCallback) { }; /** - * Retrieves a type of ROS topic. + * Retrieve the type of a ROS topic. * - * @param topic name of the topic: - * @param callback - function with params: - * * type - String of the topic type - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {string} topic - Name of the topic. + * @param {function} callback - Function with the following params: + * @param {string} callback.type - The type of the topic. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getTopicType = function(topic, callback, failedCallback) { var topicTypeClient = new Service({ @@ -541,13 +548,13 @@ Ros.prototype.getTopicType = function(topic, callback, failedCallback) { }; /** - * Retrieves a type of ROS service. + * Retrieve the type of a ROS service. * - * @param service name of service: - * @param callback - function with params: - * * type - String of the service type - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {string} service - Name of the service. + * @param {function} callback - Function with the following params: + * @param {string} callback.type - The type of the service. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getServiceType = function(service, callback, failedCallback) { var serviceTypeClient = new Service({ @@ -576,13 +583,13 @@ Ros.prototype.getServiceType = function(service, callback, failedCallback) { }; /** - * Retrieves a detail of ROS message. + * Retrieve the details of a ROS message. * - * @param message - String of a topic type - * @param callback - function with params: - * * details - Array of the message detail - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {string} message - The name of the message type. + * @param {function} callback - Function with the following params: + * @param {string} callback.details - An array of the message details. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getMessageDetails = function(message, callback, failedCallback) { var messageDetailClient = new Service({ @@ -611,9 +618,9 @@ Ros.prototype.getMessageDetails = function(message, callback, failedCallback) { }; /** - * Decode a typedefs into a dictionary like `rosmsg show foo/bar` + * Decode a typedef array into a dictionary like `rosmsg show foo/bar`. * - * @param defs - array of type_def dictionary + * @param {Object[]} defs - Array of type_def dictionary. */ Ros.prototype.decodeTypeDefs = function(defs) { var that = this; @@ -662,15 +669,14 @@ Ros.prototype.decodeTypeDefs = function(defs) { }; /** - * Retrieves list of topics and their associated type definitions. - * - * @param callback function with params: - * * topics - Array of topic names - * * types - Array of message type names - * * typedefs_full_text - Array of full definitions of message types, similar to `gendeps --cat` - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * Retrieve a list of topics and their associated type definitions. * + * @param {function} callback - Function with the following params: + * @param {string[]} callback.topics - Array of topic names. + * @param {string[]} callback.types - Array of message type names. + * @param {string[]} callback.typedefs_full_text - Array of full definitions of message types, similar to `gendeps --cat`. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getTopicsAndRawTypes = function(callback, failedCallback) { var topicsAndRawTypesClient = new Service({ diff --git a/src/core/Service.js b/src/core/Service.js index 33729dd0e..023758899 100644 --- a/src/core/Service.js +++ b/src/core/Service.js @@ -1,5 +1,5 @@ /** - * @fileoverview + * @fileOverview * @author Brandon Alexander - baalexander@gmail.com */ @@ -11,10 +11,10 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2; * A ROS service client. * * @constructor - * @params options - possible keys include: - * * ros - the ROSLIB.Ros connection handle - * * name - the service name, like /add_two_ints - * * serviceType - the service type, like 'rospy_tutorials/AddTwoInts' + * @param {Object} options - An object with the following keys: + * @param {Ros} options.ros - The ROSLIB.Ros connection handle. + * @param {string} options.name - The service name, like '/add_two_ints'. + * @param {string} options.serviceType - The service type, like 'rospy_tutorials/AddTwoInts'. */ function Service(options) { options = options || {}; @@ -27,14 +27,14 @@ function Service(options) { } Service.prototype.__proto__ = EventEmitter2.prototype; /** - * Calls the service. Returns the service response in the + * Call the service. Returns the service response in the * callback. Does nothing if this service is currently advertised. * - * @param request - the ROSLIB.ServiceRequest to send - * @param callback - function with params: - * * response - the response from the service request - * @param failedCallback - the callback function when the service call failed (optional). Params: - * * error - the error message reported by ROS + * @param {ServiceRequest} request - The ROSLIB.ServiceRequest to send. + * @param {function} callback - Function with the following params: + * @param {Object} callback.response - The response from the service request. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Service.prototype.callService = function(request, callback, failedCallback) { if (this.isAdvertised) { @@ -70,11 +70,11 @@ Service.prototype.callService = function(request, callback, failedCallback) { * into a server. The callback will be called with every request * that's made on this service. * - * @param callback - This works similarly to the callback for a C++ service and should take the following params: - * * request - the service request - * * response - an empty dictionary. Take care not to overwrite this. Instead, only modify the values within. - * It should return true if the service has finished successfully, - * i.e. without any fatal errors. + * @param {function} callback - This works similarly to the callback for a C++ service and should take the following params: + * @param {ServiceRequest} callback.request - The service request. + * @param {Object} callback.response - An empty dictionary. Take care not to overwrite this. Instead, only modify the values within. + * It should return true if the service has finished successfully, + * i.e., without any fatal errors. */ Service.prototype.advertise = function(callback) { if (this.isAdvertised || typeof callback !== 'function') { diff --git a/src/core/ServiceRequest.js b/src/core/ServiceRequest.js index 601f5314b..32db480ad 100644 --- a/src/core/ServiceRequest.js +++ b/src/core/ServiceRequest.js @@ -1,5 +1,5 @@ /** - * @fileoverview + * @fileOverview * @author Brandon Alexander - balexander@willowgarage.com */ @@ -9,7 +9,7 @@ var assign = require('object-assign'); * A ServiceRequest is passed into the service call. * * @constructor - * @param values - object matching the fields defined in the .srv definition file + * @param {Object} values - Object matching the fields defined in the .srv definition file. */ function ServiceRequest(values) { assign(this, values); diff --git a/src/core/ServiceResponse.js b/src/core/ServiceResponse.js index 4c0450b4a..01d8311c3 100644 --- a/src/core/ServiceResponse.js +++ b/src/core/ServiceResponse.js @@ -1,5 +1,5 @@ /** - * @fileoverview + * @fileOverview * @author Brandon Alexander - balexander@willowgarage.com */ @@ -9,7 +9,7 @@ var assign = require('object-assign'); * A ServiceResponse is returned from the service call. * * @constructor - * @param values - object matching the fields defined in the .srv definition file + * @param {Object} values - Object matching the fields defined in the .srv definition file. */ function ServiceResponse(values) { assign(this, values); diff --git a/src/core/SocketAdapter.js b/src/core/SocketAdapter.js index a5aa3f076..a4e9a3198 100644 --- a/src/core/SocketAdapter.js +++ b/src/core/SocketAdapter.js @@ -17,7 +17,7 @@ if(typeof bson !== 'undefined'){ } /** - * Events listeners for a WebSocket or TCP socket to a JavaScript + * Event listeners for a WebSocket or TCP socket to a JavaScript * ROS Client. Sets up Messages for a given topic to trigger an * event on the ROS client. * @@ -70,9 +70,9 @@ function SocketAdapter(client) { return { /** - * Emits a 'connection' event on WebSocket connection. + * Emit a 'connection' event on WebSocket connection. * - * @param event - the argument to emit with the event. + * @param {function} event - The argument to emit with the event. * @memberof SocketAdapter */ onopen: function onOpen(event) { @@ -81,9 +81,9 @@ function SocketAdapter(client) { }, /** - * Emits a 'close' event on WebSocket disconnection. + * Emit a 'close' event on WebSocket disconnection. * - * @param event - the argument to emit with the event. + * @param {function} event - The argument to emit with the event. * @memberof SocketAdapter */ onclose: function onClose(event) { @@ -92,9 +92,9 @@ function SocketAdapter(client) { }, /** - * Emits an 'error' event whenever there was an error. + * Emit an 'error' event whenever there was an error. * - * @param event - the argument to emit with the event. + * @param {function} event - The argument to emit with the event. * @memberof SocketAdapter */ onerror: function onError(event) { @@ -102,10 +102,10 @@ function SocketAdapter(client) { }, /** - * Parses message responses from rosbridge and sends to the appropriate + * Parse message responses from rosbridge and send to the appropriate * topic, service, or param. * - * @param message - the raw JSON message from rosbridge. + * @param {Object} data - The raw JSON message from rosbridge. * @memberof SocketAdapter */ onmessage: function onMessage(data) { diff --git a/src/core/Topic.js b/src/core/Topic.js index c06103d06..707a6b6c8 100644 --- a/src/core/Topic.js +++ b/src/core/Topic.js @@ -1,5 +1,5 @@ /** - * @fileoverview + * @fileOverview * @author Brandon Alexander - baalexander@gmail.com */ @@ -10,20 +10,20 @@ var Message = require('./Message'); * Publish and/or subscribe to a topic in ROS. * * Emits the following events: - * * 'warning' - if there are any warning during the Topic creation - * * 'message' - the message data from rosbridge + * * 'warning' - If there are any warning during the Topic creation. + * * 'message' - The message data from rosbridge. * * @constructor - * @param options - object with following keys: - * * ros - the ROSLIB.Ros connection handle - * * name - the topic name, like /cmd_vel - * * messageType - the message type, like 'std_msgs/String' - * * compression - the type of compression to use, like 'png', 'cbor', or 'cbor-raw' - * * throttle_rate - the rate (in ms in between messages) at which to throttle the topics - * * queue_size - the queue created at bridge side for re-publishing webtopics (defaults to 100) - * * latch - latch the topic when publishing - * * queue_length - the queue length at bridge side used when subscribing (defaults to 0, no queueing). - * * reconnect_on_close - the flag to enable resubscription and readvertisement on close event(defaults to true). + * @param {Object} options - An object with the following keys: + * @param {Ros} options.ros - The ROSLIB.Ros connection handle. + * @param {string} options.name - The topic name, like '/cmd_vel'. + * @param {string} options.messageType - The message type, like 'std_msgs/String'. + * @param {string} [options.compression] - The type of compression to use, like 'png', 'cbor', or 'cbor-raw'. + * @param {number} [options.throttle_rate] - The rate (in ms in between messages) at which to throttle the topics. + * @param {number} [options.queue_size] - The queue created at bridge side for re-publishing webtopics (defaults to 100). + * @param {boolean} [options.latch] - Latch the topic when publishing (defaults to false). + * @param {number} [options.queue_length] - The queue length at bridge side used when subscribing (defaults to 0, no queueing). + * @param {boolean} [options.reconnect_on_close] - The flag to enable resubscription and readvertisement on close event (defaults to true). */ function Topic(options) { options = options || {}; @@ -85,8 +85,8 @@ Topic.prototype.__proto__ = EventEmitter2.prototype; * Every time a message is published for the given topic, the callback * will be called with the message object. * - * @param callback - function with the following params: - * * message - the published message + * @param {function} callback - Function with the following params: + * @param {Object} callback.message - The published message. */ Topic.prototype.subscribe = function(callback) { if (typeof callback === 'function') { @@ -109,13 +109,13 @@ Topic.prototype.subscribe = function(callback) { }; /** - * Unregisters as a subscriber for the topic. Unsubscribing stop remove - * all subscribe callbacks. To remove a call back, you must explicitly - * pass the callback function in. + * Unregister as a subscriber for the topic. Unsubscribing will stop + * and remove all subscribe callbacks. To remove a call back, you must + * explicitly pass the callback function in. * - * @param callback - the optional callback to unregister, if - * * provided and other listeners are registered the topic won't - * * unsubscribe, just stop emitting to the passed listener + * @param {function} [callback] - The callback to unregister, if + * provided and other listeners are registered the topic won't + * unsubscribe, just stop emitting to the passed listener. */ Topic.prototype.unsubscribe = function(callback) { if (callback) { @@ -140,7 +140,7 @@ Topic.prototype.unsubscribe = function(callback) { /** - * Registers as a publisher for the topic. + * Register as a publisher for the topic. */ Topic.prototype.advertise = function() { if (this.isAdvertised) { @@ -166,7 +166,7 @@ Topic.prototype.advertise = function() { }; /** - * Unregisters as a publisher for the topic. + * Unregister as a publisher for the topic. */ Topic.prototype.unadvertise = function() { if (!this.isAdvertised) { @@ -187,7 +187,7 @@ Topic.prototype.unadvertise = function() { /** * Publish the message. * - * @param message - A ROSLIB.Message object. + * @param {Message} message - A ROSLIB.Message object. */ Topic.prototype.publish = function(message) { if (!this.isAdvertised) { diff --git a/src/math/Pose.js b/src/math/Pose.js index c50d15094..95d266018 100644 --- a/src/math/Pose.js +++ b/src/math/Pose.js @@ -1,5 +1,5 @@ /** - * @fileoverview + * @fileOverview * @author David Gossow - dgossow@willowgarage.com */ @@ -9,10 +9,10 @@ var Quaternion = require('./Quaternion'); /** * A Pose in 3D space. Values are copied into this object. * - * @constructor - * @param options - object with following keys: - * * position - the Vector3 describing the position - * * orientation - the ROSLIB.Quaternion describing the orientation + * @constructor + * @param {Object} options - An object with the following keys: + * @param {Vector3} options.position - The ROSLIB.Vector3 describing the position. + * @param {Quaternion} options.orientation - The ROSLIB.Quaternion describing the orientation. */ function Pose(options) { options = options || {}; @@ -24,7 +24,7 @@ function Pose(options) { /** * Apply a transform against this pose. * - * @param tf the transform + * @param {Transform} tf - The transform to be applied. */ Pose.prototype.applyTransform = function(tf) { this.position.multiplyQuaternion(tf.rotation); @@ -37,16 +37,16 @@ Pose.prototype.applyTransform = function(tf) { /** * Clone a copy of this pose. * - * @returns the cloned pose + * @returns {Pose} The cloned pose. */ Pose.prototype.clone = function() { return new Pose(this); }; /** - * Multiplies this pose with another pose without altering this pose. + * Multiply this pose with another pose without altering this pose. * - * @returns Result of multiplication. + * @returns {Pose} The result of the multiplication. */ Pose.prototype.multiply = function(pose) { var p = pose.clone(); @@ -55,9 +55,9 @@ Pose.prototype.multiply = function(pose) { }; /** - * Computes the inverse of this pose. + * Compute the inverse of this pose. * - * @returns Inverse of pose. + * @returns {Pose} The inverse of the pose. */ Pose.prototype.getInverse = function() { var inverse = this.clone(); diff --git a/src/math/Quaternion.js b/src/math/Quaternion.js index 61ea6fe91..a093a09a5 100644 --- a/src/math/Quaternion.js +++ b/src/math/Quaternion.js @@ -1,17 +1,17 @@ /** - * @fileoverview + * @fileOverview * @author David Gossow - dgossow@willowgarage.com */ /** * A Quaternion. * - * @constructor - * @param options - object with following keys: - * * x - the x value - * * y - the y value - * * z - the z value - * * w - the w value + * @constructor + * @param {Object} options - An object with the following keys: + * @param {number} [options.x] - The x value (defaults to 0). + * @param {number} [options.y] - The y value (defaults to 0). + * @param {number} [options.z] - The z value (defaults to 0). + * @param {number} [options.w] - The w value (defaults to 1). */ function Quaternion(options) { options = options || {}; @@ -67,7 +67,7 @@ Quaternion.prototype.invert = function() { /** * Set the values of this quaternion to the product of itself and the given quaternion. * - * @param q the quaternion to multiply with + * @param {Quaternion} q - The quaternion to multiply with. */ Quaternion.prototype.multiply = function(q) { var newX = this.x * q.w + this.y * q.z - this.z * q.y + this.w * q.x; @@ -83,7 +83,7 @@ Quaternion.prototype.multiply = function(q) { /** * Clone a copy of this quaternion. * - * @returns the cloned quaternion + * @returns {Quaternion} The cloned quaternion. */ Quaternion.prototype.clone = function() { return new Quaternion(this); diff --git a/src/math/Transform.js b/src/math/Transform.js index c5a2be7d8..c70e155c1 100644 --- a/src/math/Transform.js +++ b/src/math/Transform.js @@ -1,5 +1,5 @@ /** - * @fileoverview + * @fileOverview * @author David Gossow - dgossow@willowgarage.com */ @@ -9,10 +9,10 @@ var Quaternion = require('./Quaternion'); /** * A Transform in 3-space. Values are copied into this object. * - * @constructor - * @param options - object with following keys: - * * translation - the Vector3 describing the translation - * * rotation - the ROSLIB.Quaternion describing the rotation + * @constructor + * @param {Object} options - An object with the following keys: + * @param {Vector3} options.translation - The ROSLIB.Vector3 describing the translation. + * @param {Quaternion} options.rotation - The ROSLIB.Quaternion describing the rotation. */ function Transform(options) { options = options || {}; @@ -24,7 +24,7 @@ function Transform(options) { /** * Clone a copy of this transform. * - * @returns the cloned transform + * @returns {Transform} The cloned transform. */ Transform.prototype.clone = function() { return new Transform(this); diff --git a/src/math/Vector3.js b/src/math/Vector3.js index c825e567a..78ca858a7 100644 --- a/src/math/Vector3.js +++ b/src/math/Vector3.js @@ -1,16 +1,16 @@ /** - * @fileoverview + * @fileOverview * @author David Gossow - dgossow@willowgarage.com */ /** * A 3D vector. * - * @constructor - * @param options - object with following keys: - * * x - the x value - * * y - the y value - * * z - the z value + * @constructor + * @param {Object} options - An object with the following keys: + * @param {number} [options.x] - The x value (defaults to 0). + * @param {number} [options.y] - The y value (defaults to 0). + * @param {number} [options.z] - The z value (defaults to 0). */ function Vector3(options) { options = options || {}; @@ -22,7 +22,7 @@ function Vector3(options) { /** * Set the values of this vector to the sum of itself and the given vector. * - * @param v the vector to add with + * @param {Vector3} v - The vector to add with. */ Vector3.prototype.add = function(v) { this.x += v.x; @@ -33,7 +33,7 @@ Vector3.prototype.add = function(v) { /** * Set the values of this vector to the difference of itself and the given vector. * - * @param v the vector to subtract with + * @param {Vector3} v - The vector to subtract with. */ Vector3.prototype.subtract = function(v) { this.x -= v.x; @@ -44,7 +44,7 @@ Vector3.prototype.subtract = function(v) { /** * Multiply the given Quaternion with this vector. * - * @param q - the quaternion to multiply with + * @param {Quaternion} q - The quaternion to multiply with. */ Vector3.prototype.multiplyQuaternion = function(q) { var ix = q.w * this.x + q.y * this.z - q.z * this.y; @@ -59,7 +59,7 @@ Vector3.prototype.multiplyQuaternion = function(q) { /** * Clone a copy of this vector. * - * @returns the cloned vector + * @returns {Vector3} The cloned vector. */ Vector3.prototype.clone = function() { return new Vector3(this); diff --git a/src/node/RosTCP.js b/src/node/RosTCP.js index 2f2b50133..de0a1f755 100644 --- a/src/node/RosTCP.js +++ b/src/node/RosTCP.js @@ -5,9 +5,9 @@ var socketAdapter = require('../core/SocketAdapter.js'); var util = require('util'); /** - * Same as core Ros except supports TCP connections - * also can receive a socket.io instance (options.socketio) or server instance (option.http) - * to connect to the front using socket.io + * Same as core Ros except supports TCP connections. + * This can also receive a socket.io instance (options.socketio) or server instance (option.http) + * to connect to the front using socket.io. * @private */ function RosTCP(options) { @@ -33,10 +33,10 @@ function RosTCP(options) { util.inherits(RosTCP, Ros); /** - * Connects to a live socket + * Connect to a live socket. * - * * url (String|Int|Object): Address and port to connect to (see http://nodejs.org/api/net.html) - * format {host: String, port: Int} or (port:Int), or "host:port" + * @param {string|number|Object} url - Address and port to connect to (see http://nodejs.org/api/net.html). + * Format: {host: String, port: Int} or (port:Int) or "host:port". */ RosTCP.prototype.connect = function(url) { if (typeof url === 'string' && (url.slice(0, 5) === 'ws://' || url.slice(0, 6) === 'wss://')) { diff --git a/src/node/TopicStream.js b/src/node/TopicStream.js index f492e72e7..c5d0c9ea2 100644 --- a/src/node/TopicStream.js +++ b/src/node/TopicStream.js @@ -4,14 +4,12 @@ var DuplexStream = require('stream').Duplex; /** * Publish a connected ROS topic to a duplex * stream. This stream can be piped to, which will - * publish to the topic + * publish to the topic. * - * @options - * * subscribe: whether to subscribe to the topic and start emitting - * Data - * * publish: whether to register the stream as a publisher to the topic - * * transform: a function to change the data to be published - * or filter it if false is returned + * @param {Object} options - An object with the following keys: + * @param {boolean} [options.subscribe] - The flag to indicate whether to subscribe to the topic and start emitting data or not (defaults to true). + * @param {boolean} [options.publish] - The flag to indicate whether to register the stream as a publisher to the topic or not (defaults to true). + * @param {boolean} [options.transform] - A function to change the data to be published or filter it if false is returned. */ Topic.prototype.toStream = function(options) { options = options || {subscribe: true, publish: true}; diff --git a/src/tf/TFClient.js b/src/tf/TFClient.js index 9ee9ea732..0f5052a9e 100644 --- a/src/tf/TFClient.js +++ b/src/tf/TFClient.js @@ -1,5 +1,5 @@ /** - * @fileoverview + * @fileOverview * @author David Gossow - dgossow@willowgarage.com */ @@ -15,19 +15,19 @@ var Transform = require('../math/Transform'); /** * A TF Client that listens to TFs from tf2_web_republisher. * - * @constructor - * @param options - object with following keys: - * * ros - the ROSLIB.Ros connection handle - * * fixedFrame - the fixed frame, like /base_link - * * angularThres - the angular threshold for the TF republisher - * * transThres - the translation threshold for the TF republisher - * * rate - the rate for the TF republisher - * * updateDelay - the time (in ms) to wait after a new subscription - * to update the TF republisher's list of TFs - * * topicTimeout - the timeout parameter for the TF republisher - * * serverName (optional) - the name of the tf2_web_republisher server - * * repubServiceName (optional) - the name of the republish_tfs service (non groovy compatibility mode only) - * default: '/republish_tfs' + * @constructor + * @param {Object} options - An object with the following keys: + * @param {Ros} options.ros - The ROSLIB.Ros connection handle. + * @param {string} options.fixedFrame - The fixed frame, like '/base_link'. + * @param {number} options.angularThres - The angular threshold for the TF republisher (defaults to 2.0). + * @param {number} options.transThres - The translation threshold for the TF republisher (defaults to 0.01). + * @param {number} options.rate - The rate for the TF republisher (defaults to 10.0). + * @param {number} options.updateDelay - The time (in ms) to wait after a new subscription + * to update the TF republisher's list of TFs (defaults to 50). + * @param {number} options.topicTimeout - The timeout parameter for the TF republisher (defaults to 2.0). + * @param {string} [options.serverName] - The name of the tf2_web_republisher server. + * @param {string} [options.repubServiceName] - The name of the republish_tfs service (non groovy compatibility mode only). + * Default: '/republish_tfs'. */ function TFClient(options) { options = options || {}; @@ -54,7 +54,7 @@ function TFClient(options) { this._subscribeCB = null; this._isDisposed = false; - // Create an Action client + // Create an Action Client this.actionClient = new ActionClient({ ros : options.ros, serverName : this.serverName, @@ -63,7 +63,7 @@ function TFClient(options) { omitResult : true }); - // Create a Service client + // Create a Service Client this.serviceClient = new Service({ ros: options.ros, name: this.repubServiceName, @@ -75,7 +75,7 @@ function TFClient(options) { * Process the incoming TF message and send them out using the callback * functions. * - * @param tf - the TF message from the server + * @param {Object} tf - The TF message from the server. */ TFClient.prototype.processTFArray = function(tf) { var that = this; @@ -140,9 +140,9 @@ TFClient.prototype.updateGoal = function() { /** * Process the service response and subscribe to the tf republisher - * topic + * topic. * - * @param response the service response containing the topic name + * @param {Object} response - The service response containing the topic name. */ TFClient.prototype.processResponse = function(response) { // Do not setup a topic subscription if already disposed. Prevents a race condition where @@ -169,9 +169,9 @@ TFClient.prototype.processResponse = function(response) { /** * Subscribe to the given TF frame. * - * @param frameID - the TF frame to subscribe to - * @param callback - function with params: - * * transform - the transform data + * @param {string} frameID - The TF frame to subscribe to. + * @param {function} callback - Function with the following params: + * @param {Transform} callback.transform - The transform data. */ TFClient.prototype.subscribe = function(frameID, callback) { // remove leading slash, if it's there @@ -199,8 +199,8 @@ TFClient.prototype.subscribe = function(frameID, callback) { /** * Unsubscribe from the given TF frame. * - * @param frameID - the TF frame to unsubscribe from - * @param callback - the callback function to remove + * @param {string} frameID - The TF frame to unsubscribe from. + * @param {function} callback - The callback function to remove. */ TFClient.prototype.unsubscribe = function(frameID, callback) { // remove leading slash, if it's there diff --git a/src/urdf/UrdfBox.js b/src/urdf/UrdfBox.js index 637cd0992..353ba1142 100644 --- a/src/urdf/UrdfBox.js +++ b/src/urdf/UrdfBox.js @@ -1,5 +1,5 @@ /** - * @fileOverview + * @fileOverview * @author Benjamin Pitzer - ben.pitzer@gmail.com * @author Russell Toris - rctoris@wpi.edu */ @@ -11,8 +11,8 @@ var UrdfTypes = require('./UrdfTypes'); * A Box element in a URDF. * * @constructor - * @param options - object with following keys: - * * xml - the XML element to parse + * @param {Object} options - An object with the following keys: + * @param {Element} options.xml - The XML element to parse. */ function UrdfBox(options) { this.dimension = null; diff --git a/src/urdf/UrdfColor.js b/src/urdf/UrdfColor.js index 87434d95a..9f5f4ea14 100644 --- a/src/urdf/UrdfColor.js +++ b/src/urdf/UrdfColor.js @@ -1,5 +1,5 @@ /** - * @fileOverview + * @fileOverview * @author Benjamin Pitzer - ben.pitzer@gmail.com * @author Russell Toris - rctoris@wpi.edu */ @@ -8,8 +8,8 @@ * A Color element in a URDF. * * @constructor - * @param options - object with following keys: - * * xml - the XML element to parse + * @param {Object} options - An object with the following keys: + * @param {Element} options.xml - The XML element to parse. */ function UrdfColor(options) { // Parse the xml string diff --git a/src/urdf/UrdfCylinder.js b/src/urdf/UrdfCylinder.js index a963aaed5..50e4bd5be 100644 --- a/src/urdf/UrdfCylinder.js +++ b/src/urdf/UrdfCylinder.js @@ -1,5 +1,5 @@ /** - * @fileOverview + * @fileOverview * @author Benjamin Pitzer - ben.pitzer@gmail.com * @author Russell Toris - rctoris@wpi.edu */ @@ -10,8 +10,8 @@ var UrdfTypes = require('./UrdfTypes'); * A Cylinder element in a URDF. * * @constructor - * @param options - object with following keys: - * * xml - the XML element to parse + * @param {Object} options - An object with the following keys: + * @param {Element} options.xml - The XML element to parse. */ function UrdfCylinder(options) { this.type = UrdfTypes.URDF_CYLINDER; diff --git a/src/urdf/UrdfJoint.js b/src/urdf/UrdfJoint.js index b62d42252..fc7a4b4bd 100644 --- a/src/urdf/UrdfJoint.js +++ b/src/urdf/UrdfJoint.js @@ -1,6 +1,6 @@ /** * @fileOverview - * @author David V. Lu!! davidvlu@gmail.com + * @author David V. Lu!! - davidvlu@gmail.com */ var Pose = require('../math/Pose'); @@ -11,8 +11,8 @@ var Quaternion = require('../math/Quaternion'); * A Joint element in a URDF. * * @constructor - * @param options - object with following keys: - * * xml - the XML element to parse + * @param {Object} options - An object with the following keys: + * @param {Element} options.xml - The XML element to parse. */ function UrdfJoint(options) { this.name = options.xml.getAttribute('name'); diff --git a/src/urdf/UrdfLink.js b/src/urdf/UrdfLink.js index 484804bcf..786a1fba2 100644 --- a/src/urdf/UrdfLink.js +++ b/src/urdf/UrdfLink.js @@ -1,5 +1,5 @@ /** - * @fileOverview + * @fileOverview * @author Benjamin Pitzer - ben.pitzer@gmail.com * @author Russell Toris - rctoris@wpi.edu */ @@ -10,8 +10,8 @@ var UrdfVisual = require('./UrdfVisual'); * A Link element in a URDF. * * @constructor - * @param options - object with following keys: - * * xml - the XML element to parse + * @param {Object} options - An object with the following keys: + * @param {Element} options.xml - The XML element to parse. */ function UrdfLink(options) { this.name = options.xml.getAttribute('name'); diff --git a/src/urdf/UrdfMaterial.js b/src/urdf/UrdfMaterial.js index c873b4e16..c43dd39ec 100644 --- a/src/urdf/UrdfMaterial.js +++ b/src/urdf/UrdfMaterial.js @@ -1,5 +1,5 @@ /** - * @fileOverview + * @fileOverview * @author Benjamin Pitzer - ben.pitzer@gmail.com * @author Russell Toris - rctoris@wpi.edu */ @@ -10,8 +10,8 @@ var UrdfColor = require('./UrdfColor'); * A Material element in a URDF. * * @constructor - * @param options - object with following keys: - * * xml - the XML element to parse + * @param {Object} options - An object with the following keys: + * @param {Element} options.xml - The XML element to parse. */ function UrdfMaterial(options) { this.textureFilename = null; diff --git a/src/urdf/UrdfMesh.js b/src/urdf/UrdfMesh.js index c6a49a771..63a709a9f 100644 --- a/src/urdf/UrdfMesh.js +++ b/src/urdf/UrdfMesh.js @@ -1,5 +1,5 @@ /** - * @fileOverview + * @fileOverview * @author Benjamin Pitzer - ben.pitzer@gmail.com * @author Russell Toris - rctoris@wpi.edu */ @@ -11,8 +11,8 @@ var UrdfTypes = require('./UrdfTypes'); * A Mesh element in a URDF. * * @constructor - * @param options - object with following keys: - * * xml - the XML element to parse + * @param {Object} options - An object with the following keys: + * @param {Element} options.xml - The XML element to parse. */ function UrdfMesh(options) { this.scale = null; diff --git a/src/urdf/UrdfModel.js b/src/urdf/UrdfModel.js index 109f3a603..e48f03c52 100644 --- a/src/urdf/UrdfModel.js +++ b/src/urdf/UrdfModel.js @@ -16,9 +16,9 @@ var XPATH_FIRST_ORDERED_NODE_TYPE = 9; * A URDF Model can be used to parse a given URDF into the appropriate elements. * * @constructor - * @param options - object with following keys: - * * xml - the XML element to parse - * * string - the XML element to parse as a string + * @param {Object} options - An object with the following keys: + * @param {Element} options.xml - The XML element to parse. + * @param {string} options.string - The XML element to parse as a string. */ function UrdfModel(options) { options = options || {}; diff --git a/src/urdf/UrdfSphere.js b/src/urdf/UrdfSphere.js index 685b746f8..5c1d2aa75 100644 --- a/src/urdf/UrdfSphere.js +++ b/src/urdf/UrdfSphere.js @@ -1,5 +1,5 @@ /** - * @fileOverview + * @fileOverview * @author Benjamin Pitzer - ben.pitzer@gmail.com * @author Russell Toris - rctoris@wpi.edu */ @@ -10,8 +10,8 @@ var UrdfTypes = require('./UrdfTypes'); * A Sphere element in a URDF. * * @constructor - * @param options - object with following keys: - * * xml - the XML element to parse + * @param {Object} options - An object with the following keys: + * @param {Element} options.xml - The XML element to parse. */ function UrdfSphere(options) { this.type = UrdfTypes.URDF_SPHERE; diff --git a/src/urdf/UrdfVisual.js b/src/urdf/UrdfVisual.js index 1aaaef4b5..4ec3698e5 100644 --- a/src/urdf/UrdfVisual.js +++ b/src/urdf/UrdfVisual.js @@ -1,5 +1,5 @@ /** - * @fileOverview + * @fileOverview * @author Benjamin Pitzer - ben.pitzer@gmail.com * @author Russell Toris - rctoris@wpi.edu */ @@ -18,8 +18,8 @@ var UrdfSphere = require('./UrdfSphere'); * A Visual element in a URDF. * * @constructor - * @param options - object with following keys: - * * xml - the XML element to parse + * @param {Object} options - An object with the following keys: + * @param {Element} options.xml - The XML element to parse. */ function UrdfVisual(options) { var xml = options.xml; diff --git a/src/util/cborTypedArrayTags.js b/src/util/cborTypedArrayTags.js index 6ff4e084e..2a8476e02 100644 --- a/src/util/cborTypedArrayTags.js +++ b/src/util/cborTypedArrayTags.js @@ -11,7 +11,7 @@ function warnPrecision() { } /** - * Unpacks 64-bit unsigned integer from byte array. + * Unpack 64-bit unsigned integer from byte array. * @param {Uint8Array} bytes */ function decodeUint64LE(bytes) { @@ -36,7 +36,7 @@ function decodeUint64LE(bytes) { } /** - * Unpacks 64-bit signed integer from byte array. + * Unpack 64-bit signed integer from byte array. * @param {Uint8Array} bytes */ function decodeInt64LE(bytes) { @@ -62,9 +62,9 @@ function decodeInt64LE(bytes) { } /** - * Unpacks typed array from byte array. + * Unpack typed array from byte array. * @param {Uint8Array} bytes - * @param {type} ArrayType - desired output array type + * @param {type} ArrayType - Desired output array type */ function decodeNativeArray(bytes, ArrayType) { var byteLen = bytes.byteLength; @@ -74,9 +74,10 @@ function decodeNativeArray(bytes, ArrayType) { } /** - * Support a subset of draft CBOR typed array tags: - * - * Only support little-endian tags for now. + * Supports a subset of draft CBOR typed array tags: + * + * + * Only supports little-endian tags for now. */ var nativeArrayTypes = { 64: Uint8Array, @@ -98,7 +99,7 @@ var conversionArrayTypes = { }; /** - * Handles CBOR typed array tags during decoding. + * Handle CBOR typed array tags during decoding. * @param {Uint8Array} data * @param {Number} tag */ diff --git a/src/util/decompressPng.js b/src/util/decompressPng.js index 5437b413b..5b66d56c1 100644 --- a/src/util/decompressPng.js +++ b/src/util/decompressPng.js @@ -13,9 +13,9 @@ var pngparse = require('pngparse'); * the "image" as a Base64 string. * * @private - * @param data - object containing the PNG data. - * @param callback - function with params: - * * data - the uncompressed data + * @param data - An object containing the PNG data. + * @param callback - Function with the following params: + * @param callback.data - The uncompressed data. */ function decompressPng(data, callback) { var buffer = new Buffer(data, 'base64'); diff --git a/src/util/shim/decompressPng.js b/src/util/shim/decompressPng.js index f11ea5480..a3ed5e00f 100644 --- a/src/util/shim/decompressPng.js +++ b/src/util/shim/decompressPng.js @@ -14,9 +14,9 @@ var Image = Canvas.Image || window.Image; * "image" in a canvas element then decodes the * "image" as a Base64 string. * * @private - * @param data - object containing the PNG data. - * @param callback - function with params: - * * data - the uncompressed data + * @param data - An object containing the PNG data. + * @param callback - Function with the following params: + * @param callback.data - The uncompressed data. */ function decompressPng(data, callback) { // Uncompresses the data before sending it through (use image/canvas to do so). From 6cb102c6f056fdae222473e53c62226f76f69b12 Mon Sep 17 00:00:00 2001 From: James R T Date: Sat, 27 Aug 2022 22:37:14 +0800 Subject: [PATCH 02/11] Remove dead code in ActionListener --- src/actionlib/ActionListener.js | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/actionlib/ActionListener.js b/src/actionlib/ActionListener.js index f5108666b..dbe0fba4a 100644 --- a/src/actionlib/ActionListener.js +++ b/src/actionlib/ActionListener.js @@ -28,10 +28,6 @@ function ActionListener(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 From 6837bce00be413ad6ea431439bbf855d9877fffd Mon Sep 17 00:00:00 2001 From: James R T Date: Sat, 27 Aug 2022 22:37:58 +0800 Subject: [PATCH 03/11] Lint whitespace and align ActionServer param name with JSDoc --- src/actionlib/SimpleActionServer.js | 22 ++++++---------------- src/core/SocketAdapter.js | 1 - 2 files changed, 6 insertions(+), 17 deletions(-) diff --git a/src/actionlib/SimpleActionServer.js b/src/actionlib/SimpleActionServer.js index f2087b508..c05f985e8 100644 --- a/src/actionlib/SimpleActionServer.js +++ b/src/actionlib/SimpleActionServer.js @@ -20,7 +20,6 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2; * @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 || {}; @@ -128,7 +127,6 @@ function SimpleActionServer(options) { } if(that.currentGoal && isEarlier(that.currentGoal.goal_id.stamp, cancelMessage.stamp)) { - that.emit('cancel'); } } @@ -153,13 +151,10 @@ SimpleActionServer.prototype.__proto__ = EventEmitter2.prototype; * * @param {Object} result - The result to return to the client. */ - -SimpleActionServer.prototype.setSucceeded = function(result2) { - - +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); @@ -178,11 +173,10 @@ SimpleActionServer.prototype.setSucceeded = function(result2) { * * @param {Object} result - The result to return to the client. */ - -SimpleActionServer.prototype.setAborted = function(result2) { +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); @@ -201,12 +195,10 @@ SimpleActionServer.prototype.setAborted = function(result2) { * * @param {Object} feedback - The feedback to send to the client. */ - -SimpleActionServer.prototype.sendFeedback = function(feedback2) { - +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); }; @@ -214,9 +206,7 @@ SimpleActionServer.prototype.sendFeedback = function(feedback2) { /** * 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}, diff --git a/src/core/SocketAdapter.js b/src/core/SocketAdapter.js index a4e9a3198..7c7b8af0b 100644 --- a/src/core/SocketAdapter.js +++ b/src/core/SocketAdapter.js @@ -25,7 +25,6 @@ if(typeof bson !== 'undefined'){ * @private */ function SocketAdapter(client) { - var decoder = null; if (client.transportOptions.decoder) { decoder = client.transportOptions.decoder; From f3b87869d97828280d168f04161127b1fa057aae Mon Sep 17 00:00:00 2001 From: James R T Date: Sat, 27 Aug 2022 22:38:31 +0800 Subject: [PATCH 04/11] Refactor Ros.js to align callback parameters with JSDoc --- src/core/Ros.js | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/core/Ros.js b/src/core/Ros.js index 4bc792aec..d27bc0c5c 100644 --- a/src/core/Ros.js +++ b/src/core/Ros.js @@ -227,7 +227,7 @@ Ros.prototype.getTopics = function(callback, failedCallback) { if (typeof failedCallback === 'function'){ topicsClient.callService(request, function(result) { - callback(result); + callback(result.topics, result.types); }, function(message){ failedCallback(message); @@ -235,7 +235,7 @@ Ros.prototype.getTopics = function(callback, failedCallback) { ); }else{ topicsClient.callService(request, function(result) { - callback(result); + callback(result.topics, result.types); }); } }; @@ -364,7 +364,7 @@ Ros.prototype.getServiceRequestDetails = function(type, callback, failedCallback if (typeof failedCallback === 'function'){ serviceTypeClient.callService(request, function(result) { - callback(result); + callback(result.typedefs[0]); }, function(message){ failedCallback(message); @@ -372,7 +372,7 @@ Ros.prototype.getServiceRequestDetails = function(type, callback, failedCallback ); }else{ serviceTypeClient.callService(request, function(result) { - callback(result); + callback(result.typedefs[0]); }); } }; @@ -399,7 +399,7 @@ Ros.prototype.getServiceResponseDetails = function(type, callback, failedCallbac if (typeof failedCallback === 'function'){ serviceTypeClient.callService(request, function(result) { - callback(result); + callback(result.typedefs[0]); }, function(message){ failedCallback(message); @@ -407,7 +407,7 @@ Ros.prototype.getServiceResponseDetails = function(type, callback, failedCallbac ); }else{ serviceTypeClient.callService(request, function(result) { - callback(result); + callback(result.typedefs[0]); }); } }; @@ -476,7 +476,7 @@ Ros.prototype.getNodeDetails = function(node, callback, failedCallback) { ); } else { nodesClient.callService(request, function(result) { - callback(result); + callback(result.subscribing, result.publishing, result.services); }); } }; @@ -689,7 +689,7 @@ Ros.prototype.getTopicsAndRawTypes = function(callback, failedCallback) { if (typeof failedCallback === 'function'){ topicsAndRawTypesClient.callService(request, function(result) { - callback(result); + callback(result.topics, result.types, result.typedefs_full_text); }, function(message){ failedCallback(message); @@ -697,7 +697,7 @@ Ros.prototype.getTopicsAndRawTypes = function(callback, failedCallback) { ); }else{ topicsAndRawTypesClient.callService(request, function(result) { - callback(result); + callback(result.topics, result.types, result.typedefs_full_text); }); } }; From b0bb72536e8d7c6fff09d5529cd3fbe61616c954 Mon Sep 17 00:00:00 2001 From: James R T Date: Sat, 27 Aug 2022 23:07:50 +0800 Subject: [PATCH 05/11] Update check-topics tests --- test/examples/check-topics.example.js | 4 ++-- test/tcp/check-topics.examples.js | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/test/examples/check-topics.example.js b/test/examples/check-topics.example.js index 6474b18be..d4c199dae 100644 --- a/test/examples/check-topics.example.js +++ b/test/examples/check-topics.example.js @@ -15,9 +15,9 @@ describe('Example topics are live', function(done) { }); it('getTopics', function(done) { - ros.getTopics(function(result) { + ros.getTopics(function(topics, types) { expectedTopics.forEach(function(topic) { - expect(result.topics).to.contain(topic, 'Couldn\'t find topic: ' + topic); + expect(topics).to.contain(topic, 'Couldn\'t find topic: ' + topic); }); done(); }); diff --git a/test/tcp/check-topics.examples.js b/test/tcp/check-topics.examples.js index dbc52a684..52844066c 100644 --- a/test/tcp/check-topics.examples.js +++ b/test/tcp/check-topics.examples.js @@ -14,9 +14,9 @@ describe('Example topics are live', function(done) { var ros = new ROSLIB.Ros({ port: 9090 }); - ros.getTopics(function(result) { + ros.getTopics(function(topics, types) { expectedTopics.forEach(function(topic) { - expect(result.topics).to.contain(topic, 'Couldn\'t find topic: ' + topic); + expect(topics).to.contain(topic, 'Couldn\'t find topic: ' + topic); }); done(); }); From 68c115f1f275994dcf77a6be02d3ba9266a0e028 Mon Sep 17 00:00:00 2001 From: James R T Date: Sat, 27 Aug 2022 23:18:00 +0800 Subject: [PATCH 06/11] Fix check-topics example test --- test/examples/check-topics.example.js | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/test/examples/check-topics.example.js b/test/examples/check-topics.example.js index d4c199dae..164512522 100644 --- a/test/examples/check-topics.example.js +++ b/test/examples/check-topics.example.js @@ -29,16 +29,16 @@ describe('Example topics are live', function(done) { }); it('doesn\'t automatically advertise the topic', function(done) { - ros.getTopics(function(result) { - expect(result.topics).not.to.contain('/some_test_topic'); + ros.getTopics(function(topics, types) { + expect(topics).not.to.contain('/some_test_topic'); example.advertise(); done(); }); }); it('advertise broadcasts the topic', function(done) { - ros.getTopics(function(result) { - expect(result.topics).to.contain('/some_test_topic'); + ros.getTopics(function(topics, types) { + expect(topics).to.contain('/some_test_topic'); example.unadvertise(); done(); }); @@ -48,8 +48,8 @@ describe('Example topics are live', function(done) { console.log("Unadvertisement test. Wait for 15 seconds.."); this.timeout(20000); setTimeout(function() { - ros.getTopics(function(result) { - expect(result.topics).not.to.contain('/some_test_topic'); + ros.getTopics(function(topics, types) { + expect(topics).not.to.contain('/some_test_topic'); done(); }); }, 15000); From 8615745f32d1eae4fb964dbaab3ea7efac512323 Mon Sep 17 00:00:00 2001 From: James R T Date: Tue, 30 Aug 2022 13:15:46 +0800 Subject: [PATCH 07/11] Revert breaking changes and align docstring to impl as source of truth --- src/core/Ros.js | 53 +++++++++++++++++++-------- test/examples/check-topics.example.js | 16 ++++---- test/tcp/check-topics.examples.js | 4 +- 3 files changed, 47 insertions(+), 26 deletions(-) diff --git a/src/core/Ros.js b/src/core/Ros.js index d27bc0c5c..3fad7f101 100644 --- a/src/core/Ros.js +++ b/src/core/Ros.js @@ -211,8 +211,9 @@ Ros.prototype.getActionServers = function(callback, failedCallback) { * Retrieve a list of topics in ROS as an array. * * @param {function} callback - Function with the following params: - * @param {string[]} callback.topics - Array of topic names. - * @param {string[]} callback.types - Array of message type names. + * @param {Object} callback.result - The result object with the following params: + * @param {string[]} callback.result.topics - Array of topic names. + * @param {string[]} callback.result.types - Array of message type names. * @param {function} [failedCallback] - The callback function when the service call failed with params: * @param {string} failedCallback.error - The error message reported by ROS. */ @@ -227,7 +228,7 @@ Ros.prototype.getTopics = function(callback, failedCallback) { if (typeof failedCallback === 'function'){ topicsClient.callService(request, function(result) { - callback(result.topics, result.types); + callback(result); }, function(message){ failedCallback(message); @@ -235,7 +236,7 @@ Ros.prototype.getTopics = function(callback, failedCallback) { ); }else{ topicsClient.callService(request, function(result) { - callback(result.topics, result.types); + callback(result); }); } }; @@ -347,7 +348,8 @@ Ros.prototype.getServicesForType = function(serviceType, callback, failedCallbac * * @param {string} type - The type of the service. * @param {function} callback - Function with the following params: - * @param {string} callback.details - The details of the service request. + * @param {Object} callback.result - The result object with the following params: + * @param {string[]} callback.result.typedefs - An array containing the details of the service request. * @param {function} [failedCallback] - The callback function when the service call failed with params: * @param {string} failedCallback.error - The error message reported by ROS. */ @@ -364,7 +366,7 @@ Ros.prototype.getServiceRequestDetails = function(type, callback, failedCallback if (typeof failedCallback === 'function'){ serviceTypeClient.callService(request, function(result) { - callback(result.typedefs[0]); + callback(result); }, function(message){ failedCallback(message); @@ -372,7 +374,7 @@ Ros.prototype.getServiceRequestDetails = function(type, callback, failedCallback ); }else{ serviceTypeClient.callService(request, function(result) { - callback(result.typedefs[0]); + callback(result); }); } }; @@ -382,7 +384,8 @@ Ros.prototype.getServiceRequestDetails = function(type, callback, failedCallback * * @param {string} type - The type of the service. * @param {function} callback - Function with the following params: - * @param {string} callback.details - The details of the service response. + * @param {Object} callback.result - The result object with the following params: + * @param {string[]} callback.result.typedefs - An array containing the details of the service response. * @param {function} [failedCallback] - The callback function when the service call failed with params: * @param {string} failedCallback.error - The error message reported by ROS. */ @@ -399,7 +402,7 @@ Ros.prototype.getServiceResponseDetails = function(type, callback, failedCallbac if (typeof failedCallback === 'function'){ serviceTypeClient.callService(request, function(result) { - callback(result.typedefs[0]); + callback(result); }, function(message){ failedCallback(message); @@ -407,7 +410,7 @@ Ros.prototype.getServiceResponseDetails = function(type, callback, failedCallbac ); }else{ serviceTypeClient.callService(request, function(result) { - callback(result.typedefs[0]); + callback(result); }); } }; @@ -446,6 +449,8 @@ Ros.prototype.getNodes = function(callback, failedCallback) { /** * Retrieve a list of subscribed topics, publishing topics and services of a specific node. + *
+ * These are the parameters if failedCallback is defined. * * @param {string} node - Name of the node. * @param {function} callback - Function with the following params: @@ -454,6 +459,21 @@ Ros.prototype.getNodes = function(callback, failedCallback) { * @param {string[]} callback.services - Array of service names hosted. * @param {function} [failedCallback] - The callback function when the service call failed with params: * @param {string} failedCallback.error - The error message reported by ROS. + * + * @also + * + * Retrieve a list of subscribed topics, publishing topics and services of a specific node. + *
+ * These are the parameters if failedCallback is undefined. + * + * @param {string} node - Name of the node. + * @param {function} callback - Function with the following params: + * @param {Object} callback.result - The result object with the following params: + * @param {string[]} callback.result.subscribing - Array of subscribed topic names. + * @param {string[]} callback.result.publishing - Array of published topic names. + * @param {string[]} callback.result.services - Array of service names hosted. + * @param {function} [failedCallback] - The callback function when the service call failed with params: + * @param {string} failedCallback.error - The error message reported by ROS. */ Ros.prototype.getNodeDetails = function(node, callback, failedCallback) { var nodesClient = new Service({ @@ -476,7 +496,7 @@ Ros.prototype.getNodeDetails = function(node, callback, failedCallback) { ); } else { nodesClient.callService(request, function(result) { - callback(result.subscribing, result.publishing, result.services); + callback(result); }); } }; @@ -672,9 +692,10 @@ Ros.prototype.decodeTypeDefs = function(defs) { * Retrieve a list of topics and their associated type definitions. * * @param {function} callback - Function with the following params: - * @param {string[]} callback.topics - Array of topic names. - * @param {string[]} callback.types - Array of message type names. - * @param {string[]} callback.typedefs_full_text - Array of full definitions of message types, similar to `gendeps --cat`. + * @param {Object} callback.result - The result object with the following params: + * @param {string[]} callback.result.topics - Array of topic names. + * @param {string[]} callback.result.types - Array of message type names. + * @param {string[]} callback.result.typedefs_full_text - Array of full definitions of message types, similar to `gendeps --cat`. * @param {function} [failedCallback] - The callback function when the service call failed with params: * @param {string} failedCallback.error - The error message reported by ROS. */ @@ -689,7 +710,7 @@ Ros.prototype.getTopicsAndRawTypes = function(callback, failedCallback) { if (typeof failedCallback === 'function'){ topicsAndRawTypesClient.callService(request, function(result) { - callback(result.topics, result.types, result.typedefs_full_text); + callback(result); }, function(message){ failedCallback(message); @@ -697,7 +718,7 @@ Ros.prototype.getTopicsAndRawTypes = function(callback, failedCallback) { ); }else{ topicsAndRawTypesClient.callService(request, function(result) { - callback(result.topics, result.types, result.typedefs_full_text); + callback(result); }); } }; diff --git a/test/examples/check-topics.example.js b/test/examples/check-topics.example.js index 164512522..6474b18be 100644 --- a/test/examples/check-topics.example.js +++ b/test/examples/check-topics.example.js @@ -15,9 +15,9 @@ describe('Example topics are live', function(done) { }); it('getTopics', function(done) { - ros.getTopics(function(topics, types) { + ros.getTopics(function(result) { expectedTopics.forEach(function(topic) { - expect(topics).to.contain(topic, 'Couldn\'t find topic: ' + topic); + expect(result.topics).to.contain(topic, 'Couldn\'t find topic: ' + topic); }); done(); }); @@ -29,16 +29,16 @@ describe('Example topics are live', function(done) { }); it('doesn\'t automatically advertise the topic', function(done) { - ros.getTopics(function(topics, types) { - expect(topics).not.to.contain('/some_test_topic'); + ros.getTopics(function(result) { + expect(result.topics).not.to.contain('/some_test_topic'); example.advertise(); done(); }); }); it('advertise broadcasts the topic', function(done) { - ros.getTopics(function(topics, types) { - expect(topics).to.contain('/some_test_topic'); + ros.getTopics(function(result) { + expect(result.topics).to.contain('/some_test_topic'); example.unadvertise(); done(); }); @@ -48,8 +48,8 @@ describe('Example topics are live', function(done) { console.log("Unadvertisement test. Wait for 15 seconds.."); this.timeout(20000); setTimeout(function() { - ros.getTopics(function(topics, types) { - expect(topics).not.to.contain('/some_test_topic'); + ros.getTopics(function(result) { + expect(result.topics).not.to.contain('/some_test_topic'); done(); }); }, 15000); diff --git a/test/tcp/check-topics.examples.js b/test/tcp/check-topics.examples.js index 52844066c..dbc52a684 100644 --- a/test/tcp/check-topics.examples.js +++ b/test/tcp/check-topics.examples.js @@ -14,9 +14,9 @@ describe('Example topics are live', function(done) { var ros = new ROSLIB.Ros({ port: 9090 }); - ros.getTopics(function(topics, types) { + ros.getTopics(function(result) { expectedTopics.forEach(function(topic) { - expect(topics).to.contain(topic, 'Couldn\'t find topic: ' + topic); + expect(result.topics).to.contain(topic, 'Couldn\'t find topic: ' + topic); }); done(); }); From c40e15b9d2c340a91fec3c0f30393357a09661d1 Mon Sep 17 00:00:00 2001 From: Matthijs van der Burgh Date: Tue, 30 Aug 2022 19:28:46 +0200 Subject: [PATCH 08/11] Remove 'An object with the following keys' --- src/actionlib/ActionClient.js | 2 +- src/actionlib/ActionListener.js | 2 +- src/actionlib/Goal.js | 4 ++-- src/actionlib/SimpleActionServer.js | 6 +++--- src/core/Param.js | 6 +++--- src/core/Ros.js | 8 ++++---- src/core/Service.js | 2 +- src/core/Topic.js | 2 +- src/math/Pose.js | 4 ++-- src/math/Quaternion.js | 2 +- src/math/Transform.js | 4 ++-- src/math/Vector3.js | 4 ++-- src/node/TopicStream.js | 8 ++++---- src/tf/TFClient.js | 2 +- src/urdf/UrdfBox.js | 4 ++-- src/urdf/UrdfColor.js | 4 ++-- src/urdf/UrdfCylinder.js | 4 ++-- src/urdf/UrdfJoint.js | 2 +- src/urdf/UrdfLink.js | 4 ++-- src/urdf/UrdfMaterial.js | 2 +- src/urdf/UrdfMesh.js | 4 ++-- src/urdf/UrdfModel.js | 2 +- src/urdf/UrdfSphere.js | 4 ++-- src/urdf/UrdfVisual.js | 4 ++-- 24 files changed, 45 insertions(+), 45 deletions(-) diff --git a/src/actionlib/ActionClient.js b/src/actionlib/ActionClient.js index 85019cbcd..e0772c1e0 100644 --- a/src/actionlib/ActionClient.js +++ b/src/actionlib/ActionClient.js @@ -17,7 +17,7 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2; * * 'result' - The result returned from the action server. * * @constructor - * @param {Object} options - An object with the following keys: + * @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'. diff --git a/src/actionlib/ActionListener.js b/src/actionlib/ActionListener.js index dbe0fba4a..0000944d7 100644 --- a/src/actionlib/ActionListener.js +++ b/src/actionlib/ActionListener.js @@ -17,7 +17,7 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2; * * 'result' - The result returned from the action server. * * @constructor - * @param {Object} options - An object with the following keys: + * @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'. diff --git a/src/actionlib/Goal.js b/src/actionlib/Goal.js index 293b4de0a..6cdd5af41 100644 --- a/src/actionlib/Goal.js +++ b/src/actionlib/Goal.js @@ -13,7 +13,7 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2; * * 'timeout' - If a timeout occurred while sending a goal. * * @constructor - * @param {Object} options - An object with the following keys: + * @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. */ @@ -86,4 +86,4 @@ Goal.prototype.cancel = function() { this.actionClient.cancelTopic.publish(cancelMessage); }; -module.exports = Goal; \ No newline at end of file +module.exports = Goal; diff --git a/src/actionlib/SimpleActionServer.js b/src/actionlib/SimpleActionServer.js index c05f985e8..f23a9064a 100644 --- a/src/actionlib/SimpleActionServer.js +++ b/src/actionlib/SimpleActionServer.js @@ -15,7 +15,7 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2; * * 'cancel' - Action client has canceled the request. * * @constructor - * @param {Object} options - An object with the following keys: + * @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'. @@ -76,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 @@ -222,4 +222,4 @@ SimpleActionServer.prototype.setPreempted = function() { } }; -module.exports = SimpleActionServer; \ No newline at end of file +module.exports = SimpleActionServer; diff --git a/src/core/Param.js b/src/core/Param.js index f03d3caba..65416eae8 100644 --- a/src/core/Param.js +++ b/src/core/Param.js @@ -10,7 +10,7 @@ var ServiceRequest = require('./ServiceRequest'); * A ROS parameter. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Ros} options.ros - The ROSLIB.Ros connection handle. * @param {string} options.name - The param name, like max_vel_x. */ @@ -66,7 +66,7 @@ Param.prototype.set = function(value, callback) { /** * Delete this parameter on the ROS server. - * + * * @param {function} callback - The callback function. */ Param.prototype.delete = function(callback) { @@ -83,4 +83,4 @@ Param.prototype.delete = function(callback) { paramClient.callService(request, callback); }; -module.exports = Param; \ No newline at end of file +module.exports = Param; diff --git a/src/core/Ros.js b/src/core/Ros.js index 3fad7f101..43231b752 100644 --- a/src/core/Ros.js +++ b/src/core/Ros.js @@ -24,7 +24,7 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2; * * <serviceID> - A service response came from rosbridge with the given ID. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {string} [options.url] - The WebSocket URL for rosbridge or the node server URL to connect using socket.io (if socket.io exists in the page). Can be specified later with `connect`. * @param {boolean} [options.groovyCompatibility] - Don't use interfaces that changed after the last groovy release or rosbridge_suite and related tools (defaults to true). * @param {string} [options.transportLibrary] - One of 'websocket', 'workersocket' (default), 'socket.io' or RTCPeerConnection instance controlling how the connection is created in `connect`. @@ -459,13 +459,13 @@ Ros.prototype.getNodes = function(callback, failedCallback) { * @param {string[]} callback.services - Array of service names hosted. * @param {function} [failedCallback] - The callback function when the service call failed with params: * @param {string} failedCallback.error - The error message reported by ROS. - * + * * @also - * + * * Retrieve a list of subscribed topics, publishing topics and services of a specific node. *
* These are the parameters if failedCallback is undefined. - * + * * @param {string} node - Name of the node. * @param {function} callback - Function with the following params: * @param {Object} callback.result - The result object with the following params: diff --git a/src/core/Service.js b/src/core/Service.js index 023758899..a0b2f79e7 100644 --- a/src/core/Service.js +++ b/src/core/Service.js @@ -11,7 +11,7 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2; * A ROS service client. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Ros} options.ros - The ROSLIB.Ros connection handle. * @param {string} options.name - The service name, like '/add_two_ints'. * @param {string} options.serviceType - The service type, like 'rospy_tutorials/AddTwoInts'. diff --git a/src/core/Topic.js b/src/core/Topic.js index 707a6b6c8..2c2504387 100644 --- a/src/core/Topic.js +++ b/src/core/Topic.js @@ -14,7 +14,7 @@ var Message = require('./Message'); * * 'message' - The message data from rosbridge. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Ros} options.ros - The ROSLIB.Ros connection handle. * @param {string} options.name - The topic name, like '/cmd_vel'. * @param {string} options.messageType - The message type, like 'std_msgs/String'. diff --git a/src/math/Pose.js b/src/math/Pose.js index 95d266018..0dd09a5d9 100644 --- a/src/math/Pose.js +++ b/src/math/Pose.js @@ -10,7 +10,7 @@ var Quaternion = require('./Quaternion'); * A Pose in 3D space. Values are copied into this object. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Vector3} options.position - The ROSLIB.Vector3 describing the position. * @param {Quaternion} options.orientation - The ROSLIB.Quaternion describing the orientation. */ @@ -69,4 +69,4 @@ Pose.prototype.getInverse = function() { return inverse; }; -module.exports = Pose; \ No newline at end of file +module.exports = Pose; diff --git a/src/math/Quaternion.js b/src/math/Quaternion.js index a093a09a5..b9b479039 100644 --- a/src/math/Quaternion.js +++ b/src/math/Quaternion.js @@ -7,7 +7,7 @@ * A Quaternion. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {number} [options.x] - The x value (defaults to 0). * @param {number} [options.y] - The y value (defaults to 0). * @param {number} [options.z] - The z value (defaults to 0). diff --git a/src/math/Transform.js b/src/math/Transform.js index c70e155c1..8f3581d91 100644 --- a/src/math/Transform.js +++ b/src/math/Transform.js @@ -10,7 +10,7 @@ var Quaternion = require('./Quaternion'); * A Transform in 3-space. Values are copied into this object. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Vector3} options.translation - The ROSLIB.Vector3 describing the translation. * @param {Quaternion} options.rotation - The ROSLIB.Quaternion describing the rotation. */ @@ -30,4 +30,4 @@ Transform.prototype.clone = function() { return new Transform(this); }; -module.exports = Transform; \ No newline at end of file +module.exports = Transform; diff --git a/src/math/Vector3.js b/src/math/Vector3.js index 78ca858a7..9b246a1ef 100644 --- a/src/math/Vector3.js +++ b/src/math/Vector3.js @@ -7,7 +7,7 @@ * A 3D vector. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {number} [options.x] - The x value (defaults to 0). * @param {number} [options.y] - The y value (defaults to 0). * @param {number} [options.z] - The z value (defaults to 0). @@ -65,4 +65,4 @@ Vector3.prototype.clone = function() { return new Vector3(this); }; -module.exports = Vector3; \ No newline at end of file +module.exports = Vector3; diff --git a/src/node/TopicStream.js b/src/node/TopicStream.js index c5d0c9ea2..32d7fa624 100644 --- a/src/node/TopicStream.js +++ b/src/node/TopicStream.js @@ -6,7 +6,7 @@ var DuplexStream = require('stream').Duplex; * stream. This stream can be piped to, which will * publish to the topic. * - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {boolean} [options.subscribe] - The flag to indicate whether to subscribe to the topic and start emitting data or not (defaults to true). * @param {boolean} [options.publish] - The flag to indicate whether to register the stream as a publisher to the topic or not (defaults to true). * @param {boolean} [options.transform] - A function to change the data to be published or filter it if false is returned. @@ -21,7 +21,7 @@ Topic.prototype.toStream = function(options) { objectMode: true }); stream._read = function() {}; - + // Publish to the topic if someone pipes to stream stream._write = function(chunk, encoding, callback) { if (hasTransform) { @@ -32,7 +32,7 @@ Topic.prototype.toStream = function(options) { } callback(); }; - + if (options.subscribe) { this.subscribe(function(message) { stream.push(message); @@ -47,4 +47,4 @@ Topic.prototype.toStream = function(options) { return stream; }; -module.exports = Topic; \ No newline at end of file +module.exports = Topic; diff --git a/src/tf/TFClient.js b/src/tf/TFClient.js index 0f5052a9e..b1a925078 100644 --- a/src/tf/TFClient.js +++ b/src/tf/TFClient.js @@ -16,7 +16,7 @@ var Transform = require('../math/Transform'); * A TF Client that listens to TFs from tf2_web_republisher. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Ros} options.ros - The ROSLIB.Ros connection handle. * @param {string} options.fixedFrame - The fixed frame, like '/base_link'. * @param {number} options.angularThres - The angular threshold for the TF republisher (defaults to 2.0). diff --git a/src/urdf/UrdfBox.js b/src/urdf/UrdfBox.js index 353ba1142..cf9ba5a69 100644 --- a/src/urdf/UrdfBox.js +++ b/src/urdf/UrdfBox.js @@ -11,7 +11,7 @@ var UrdfTypes = require('./UrdfTypes'); * A Box element in a URDF. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Element} options.xml - The XML element to parse. */ function UrdfBox(options) { @@ -27,4 +27,4 @@ function UrdfBox(options) { }); } -module.exports = UrdfBox; \ No newline at end of file +module.exports = UrdfBox; diff --git a/src/urdf/UrdfColor.js b/src/urdf/UrdfColor.js index 9f5f4ea14..e7b492cd0 100644 --- a/src/urdf/UrdfColor.js +++ b/src/urdf/UrdfColor.js @@ -8,7 +8,7 @@ * A Color element in a URDF. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Element} options.xml - The XML element to parse. */ function UrdfColor(options) { @@ -20,4 +20,4 @@ function UrdfColor(options) { this.a = parseFloat(rgba[3]); } -module.exports = UrdfColor; \ No newline at end of file +module.exports = UrdfColor; diff --git a/src/urdf/UrdfCylinder.js b/src/urdf/UrdfCylinder.js index 50e4bd5be..17fe36038 100644 --- a/src/urdf/UrdfCylinder.js +++ b/src/urdf/UrdfCylinder.js @@ -10,7 +10,7 @@ var UrdfTypes = require('./UrdfTypes'); * A Cylinder element in a URDF. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Element} options.xml - The XML element to parse. */ function UrdfCylinder(options) { @@ -19,4 +19,4 @@ function UrdfCylinder(options) { this.radius = parseFloat(options.xml.getAttribute('radius')); } -module.exports = UrdfCylinder; \ No newline at end of file +module.exports = UrdfCylinder; diff --git a/src/urdf/UrdfJoint.js b/src/urdf/UrdfJoint.js index fc7a4b4bd..02c95c021 100644 --- a/src/urdf/UrdfJoint.js +++ b/src/urdf/UrdfJoint.js @@ -11,7 +11,7 @@ var Quaternion = require('../math/Quaternion'); * A Joint element in a URDF. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Element} options.xml - The XML element to parse. */ function UrdfJoint(options) { diff --git a/src/urdf/UrdfLink.js b/src/urdf/UrdfLink.js index 786a1fba2..b259857ab 100644 --- a/src/urdf/UrdfLink.js +++ b/src/urdf/UrdfLink.js @@ -10,7 +10,7 @@ var UrdfVisual = require('./UrdfVisual'); * A Link element in a URDF. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Element} options.xml - The XML element to parse. */ function UrdfLink(options) { @@ -25,4 +25,4 @@ function UrdfLink(options) { } } -module.exports = UrdfLink; \ No newline at end of file +module.exports = UrdfLink; diff --git a/src/urdf/UrdfMaterial.js b/src/urdf/UrdfMaterial.js index c43dd39ec..4c65f9700 100644 --- a/src/urdf/UrdfMaterial.js +++ b/src/urdf/UrdfMaterial.js @@ -10,7 +10,7 @@ var UrdfColor = require('./UrdfColor'); * A Material element in a URDF. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Element} options.xml - The XML element to parse. */ function UrdfMaterial(options) { diff --git a/src/urdf/UrdfMesh.js b/src/urdf/UrdfMesh.js index 63a709a9f..719843ed2 100644 --- a/src/urdf/UrdfMesh.js +++ b/src/urdf/UrdfMesh.js @@ -11,7 +11,7 @@ var UrdfTypes = require('./UrdfTypes'); * A Mesh element in a URDF. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Element} options.xml - The XML element to parse. */ function UrdfMesh(options) { @@ -33,4 +33,4 @@ function UrdfMesh(options) { } } -module.exports = UrdfMesh; \ No newline at end of file +module.exports = UrdfMesh; diff --git a/src/urdf/UrdfModel.js b/src/urdf/UrdfModel.js index e48f03c52..a7e68eba9 100644 --- a/src/urdf/UrdfModel.js +++ b/src/urdf/UrdfModel.js @@ -16,7 +16,7 @@ var XPATH_FIRST_ORDERED_NODE_TYPE = 9; * A URDF Model can be used to parse a given URDF into the appropriate elements. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Element} options.xml - The XML element to parse. * @param {string} options.string - The XML element to parse as a string. */ diff --git a/src/urdf/UrdfSphere.js b/src/urdf/UrdfSphere.js index 5c1d2aa75..e2d7ea0b7 100644 --- a/src/urdf/UrdfSphere.js +++ b/src/urdf/UrdfSphere.js @@ -10,7 +10,7 @@ var UrdfTypes = require('./UrdfTypes'); * A Sphere element in a URDF. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Element} options.xml - The XML element to parse. */ function UrdfSphere(options) { @@ -18,4 +18,4 @@ function UrdfSphere(options) { this.radius = parseFloat(options.xml.getAttribute('radius')); } -module.exports = UrdfSphere; \ No newline at end of file +module.exports = UrdfSphere; diff --git a/src/urdf/UrdfVisual.js b/src/urdf/UrdfVisual.js index 4ec3698e5..3d052f9a7 100644 --- a/src/urdf/UrdfVisual.js +++ b/src/urdf/UrdfVisual.js @@ -18,7 +18,7 @@ var UrdfSphere = require('./UrdfSphere'); * A Visual element in a URDF. * * @constructor - * @param {Object} options - An object with the following keys: + * @param {Object} options * @param {Element} options.xml - The XML element to parse. */ function UrdfVisual(options) { @@ -127,4 +127,4 @@ function UrdfVisual(options) { } } -module.exports = UrdfVisual; \ No newline at end of file +module.exports = UrdfVisual; From 98a331d89199cfc0884cb1b983ed58ad41992c76 Mon Sep 17 00:00:00 2001 From: James R T Date: Wed, 31 Aug 2022 19:29:40 +0800 Subject: [PATCH 09/11] Specify default param values explicitly in docstring Co-authored-by: Matthijs van der Burgh --- src/core/Ros.js | 6 +++--- src/core/Topic.js | 2 +- src/math/Quaternion.js | 8 ++++---- src/math/Vector3.js | 6 +++--- src/tf/TFClient.js | 19 +++++++++---------- 5 files changed, 20 insertions(+), 21 deletions(-) diff --git a/src/core/Ros.js b/src/core/Ros.js index 43231b752..ea34d519e 100644 --- a/src/core/Ros.js +++ b/src/core/Ros.js @@ -26,9 +26,9 @@ var EventEmitter2 = require('eventemitter2').EventEmitter2; * @constructor * @param {Object} options * @param {string} [options.url] - The WebSocket URL for rosbridge or the node server URL to connect using socket.io (if socket.io exists in the page). Can be specified later with `connect`. - * @param {boolean} [options.groovyCompatibility] - Don't use interfaces that changed after the last groovy release or rosbridge_suite and related tools (defaults to true). - * @param {string} [options.transportLibrary] - One of 'websocket', 'workersocket' (default), 'socket.io' or RTCPeerConnection instance controlling how the connection is created in `connect`. - * @param {Object} [options.transportOptions] - The options to use when creating a connection. Currently only used if `transportLibrary` is RTCPeerConnection. + * @param {boolean} [options.groovyCompatibility=true] - Don't use interfaces that changed after the last groovy release or rosbridge_suite and related tools. + * @param {string} [options.transportLibrary=websocket] - One of 'websocket', 'workersocket', 'socket.io' or RTCPeerConnection instance controlling how the connection is created in `connect`. + * @param {Object} [options.transportOptions={}] - The options to use when creating a connection. Currently only used if `transportLibrary` is RTCPeerConnection. */ function Ros(options) { options = options || {}; diff --git a/src/core/Topic.js b/src/core/Topic.js index 2c2504387..6840ddad7 100644 --- a/src/core/Topic.js +++ b/src/core/Topic.js @@ -110,7 +110,7 @@ Topic.prototype.subscribe = function(callback) { /** * Unregister as a subscriber for the topic. Unsubscribing will stop - * and remove all subscribe callbacks. To remove a call back, you must + * and remove all subscribe callbacks. To remove a callback, you must * explicitly pass the callback function in. * * @param {function} [callback] - The callback to unregister, if diff --git a/src/math/Quaternion.js b/src/math/Quaternion.js index b9b479039..5c70a2a8a 100644 --- a/src/math/Quaternion.js +++ b/src/math/Quaternion.js @@ -8,10 +8,10 @@ * * @constructor * @param {Object} options - * @param {number} [options.x] - The x value (defaults to 0). - * @param {number} [options.y] - The y value (defaults to 0). - * @param {number} [options.z] - The z value (defaults to 0). - * @param {number} [options.w] - The w value (defaults to 1). + * @param {number} [options.x=0] - The x value. + * @param {number} [options.y=0] - The y value. + * @param {number} [options.z=0] - The z value. + * @param {number} [options.w=1] - The w value. */ function Quaternion(options) { options = options || {}; diff --git a/src/math/Vector3.js b/src/math/Vector3.js index 9b246a1ef..398d1c8ea 100644 --- a/src/math/Vector3.js +++ b/src/math/Vector3.js @@ -8,9 +8,9 @@ * * @constructor * @param {Object} options - * @param {number} [options.x] - The x value (defaults to 0). - * @param {number} [options.y] - The y value (defaults to 0). - * @param {number} [options.z] - The z value (defaults to 0). + * @param {number} [options.x=0] - The x value. + * @param {number} [options.y=0] - The y value. + * @param {number} [options.z=0] - The z value. */ function Vector3(options) { options = options || {}; diff --git a/src/tf/TFClient.js b/src/tf/TFClient.js index b1a925078..912dc418e 100644 --- a/src/tf/TFClient.js +++ b/src/tf/TFClient.js @@ -18,16 +18,15 @@ var Transform = require('../math/Transform'); * @constructor * @param {Object} options * @param {Ros} options.ros - The ROSLIB.Ros connection handle. - * @param {string} options.fixedFrame - The fixed frame, like '/base_link'. - * @param {number} options.angularThres - The angular threshold for the TF republisher (defaults to 2.0). - * @param {number} options.transThres - The translation threshold for the TF republisher (defaults to 0.01). - * @param {number} options.rate - The rate for the TF republisher (defaults to 10.0). - * @param {number} options.updateDelay - The time (in ms) to wait after a new subscription - * to update the TF republisher's list of TFs (defaults to 50). - * @param {number} options.topicTimeout - The timeout parameter for the TF republisher (defaults to 2.0). - * @param {string} [options.serverName] - The name of the tf2_web_republisher server. - * @param {string} [options.repubServiceName] - The name of the republish_tfs service (non groovy compatibility mode only). - * Default: '/republish_tfs'. + * @param {string} [options.fixedFrame=base_link] - The fixed frame'. + * @param {number} [options.angularThres=2.0] - The angular threshold for the TF republisher. + * @param {number} [options.transThres=0.01] - The translation threshold for the TF republisher. + * @param {number} [options.rate=10.0] - The rate for the TF republisher. + * @param {number} [options.updateDelay=50] - The time (in ms) to wait after a new subscription + * to update the TF republisher's list of TFs. + * @param {number} [options.topicTimeout=2.0] - The timeout parameter for the TF republisher. + * @param {string} [options.serverName=/tf2_web_republisher] - The name of the tf2_web_republisher server. + * @param {string} [options.repubServiceName=/republish_tfs] - The name of the republish_tfs service (non groovy compatibility mode only). */ function TFClient(options) { options = options || {}; From 71142e1a58b7d892ea176f81aee3ed2d0bc97cad Mon Sep 17 00:00:00 2001 From: James R T Date: Wed, 31 Aug 2022 19:31:28 +0800 Subject: [PATCH 10/11] Fix typos --- src/tf/TFClient.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/tf/TFClient.js b/src/tf/TFClient.js index 912dc418e..3f674f7b9 100644 --- a/src/tf/TFClient.js +++ b/src/tf/TFClient.js @@ -31,7 +31,7 @@ var Transform = require('../math/Transform'); function TFClient(options) { options = options || {}; this.ros = options.ros; - this.fixedFrame = options.fixedFrame || '/base_link'; + this.fixedFrame = options.fixedFrame || 'base_link'; this.angularThres = options.angularThres || 2.0; this.transThres = options.transThres || 0.01; this.rate = options.rate || 10.0; @@ -178,7 +178,7 @@ TFClient.prototype.subscribe = function(frameID, callback) { { frameID = frameID.substring(1); } - // if there is no callback registered for the given frame, create emtpy callback list + // if there is no callback registered for the given frame, create empty callback list if (!this.frameInfos[frameID]) { this.frameInfos[frameID] = { cbs: [] @@ -188,7 +188,7 @@ TFClient.prototype.subscribe = function(frameID, callback) { this.republisherUpdateRequested = true; } } - // if we already have a transform, call back immediately + // if we already have a transform, callback immediately else if (this.frameInfos[frameID].transform) { callback(this.frameInfos[frameID].transform); } From 5b4774f209dbae53e8698949af516bf7ac4e51cd Mon Sep 17 00:00:00 2001 From: James R T Date: Wed, 31 Aug 2022 19:48:51 +0800 Subject: [PATCH 11/11] Specify more default param values --- src/core/Topic.js | 12 ++++++------ src/node/TopicStream.js | 4 ++-- src/tf/TFClient.js | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/core/Topic.js b/src/core/Topic.js index 6840ddad7..1804de3bd 100644 --- a/src/core/Topic.js +++ b/src/core/Topic.js @@ -18,12 +18,12 @@ var Message = require('./Message'); * @param {Ros} options.ros - The ROSLIB.Ros connection handle. * @param {string} options.name - The topic name, like '/cmd_vel'. * @param {string} options.messageType - The message type, like 'std_msgs/String'. - * @param {string} [options.compression] - The type of compression to use, like 'png', 'cbor', or 'cbor-raw'. - * @param {number} [options.throttle_rate] - The rate (in ms in between messages) at which to throttle the topics. - * @param {number} [options.queue_size] - The queue created at bridge side for re-publishing webtopics (defaults to 100). - * @param {boolean} [options.latch] - Latch the topic when publishing (defaults to false). - * @param {number} [options.queue_length] - The queue length at bridge side used when subscribing (defaults to 0, no queueing). - * @param {boolean} [options.reconnect_on_close] - The flag to enable resubscription and readvertisement on close event (defaults to true). + * @param {string} [options.compression=none] - The type of compression to use, like 'png', 'cbor', or 'cbor-raw'. + * @param {number} [options.throttle_rate=0] - The rate (in ms in between messages) at which to throttle the topics. + * @param {number} [options.queue_size=100] - The queue created at bridge side for re-publishing webtopics. + * @param {boolean} [options.latch=false] - Latch the topic when publishing. + * @param {number} [options.queue_length=0] - The queue length at bridge side used when subscribing. + * @param {boolean} [options.reconnect_on_close=true] - The flag to enable resubscription and readvertisement on close event. */ function Topic(options) { options = options || {}; diff --git a/src/node/TopicStream.js b/src/node/TopicStream.js index 32d7fa624..0c1808acf 100644 --- a/src/node/TopicStream.js +++ b/src/node/TopicStream.js @@ -7,8 +7,8 @@ var DuplexStream = require('stream').Duplex; * publish to the topic. * * @param {Object} options - * @param {boolean} [options.subscribe] - The flag to indicate whether to subscribe to the topic and start emitting data or not (defaults to true). - * @param {boolean} [options.publish] - The flag to indicate whether to register the stream as a publisher to the topic or not (defaults to true). + * @param {boolean} [options.subscribe=true] - The flag to indicate whether to subscribe to the topic and start emitting data or not. + * @param {boolean} [options.publish=true] - The flag to indicate whether to register the stream as a publisher to the topic or not. * @param {boolean} [options.transform] - A function to change the data to be published or filter it if false is returned. */ Topic.prototype.toStream = function(options) { diff --git a/src/tf/TFClient.js b/src/tf/TFClient.js index 3f674f7b9..a6e2848bb 100644 --- a/src/tf/TFClient.js +++ b/src/tf/TFClient.js @@ -18,7 +18,7 @@ var Transform = require('../math/Transform'); * @constructor * @param {Object} options * @param {Ros} options.ros - The ROSLIB.Ros connection handle. - * @param {string} [options.fixedFrame=base_link] - The fixed frame'. + * @param {string} [options.fixedFrame=base_link] - The fixed frame. * @param {number} [options.angularThres=2.0] - The angular threshold for the TF republisher. * @param {number} [options.transThres=0.01] - The translation threshold for the TF republisher. * @param {number} [options.rate=10.0] - The rate for the TF republisher.