fix(service): fix several serious invalid api signatures and docs #157

* fix invalid documention entries

BREAKING CHANGE The argument `failureHandler` of `EventBus.send()` has been removed

This callback has been obsolete since vertx-eventbus 3.1.0+.
Solves #152

BREAKING CHANGE Remove fallback in signatures again. `headers` is not skipable anymore.

Author: knalli

src/lib/adapter/EventBusAdapter.js

@@ -257,18 +257,12 @@ export default class EventBusAdapter extends BaseAdapter {
    *
    * @param {string} address target address
    * @param {object} message payload message
-   * @param {object=} headers optional headers
+   * @param {object} headers optional headers
    * @param {function=} replyHandler optional callback
-   * @param {function=} failureHandler optional callback (since Vert.x 3.0.0)
    */
-  send(address, message, headers, replyHandler, failureHandler) {
+  send(address, message, headers, replyHandler) {
     if (this.instance) {
-      if (angular.isFunction(headers)) {
-        failureHandler = replyHandler;
-        replyHandler = headers;
-        headers = undefined;
-      }
-      this.instance.send(address, message, headers, replyHandler, failureHandler);
+      this.instance.send(address, message, headers, replyHandler);
     }
   }
 

src/lib/service/Delegator.js

@@ -22,11 +22,21 @@ export default class Delegator {
     }
   }
 
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#registerHandler
+   *
+   * @description
+   * Registers a callback handler for the specified address match.
+   *
+   * @param {string} address target address
+   * @param {object} headers optional headers
+   * @param {function} callback handler with params `(message, replyTo)`
+   * @returns {function} deconstructor
+   */
   registerHandler(address, headers, callback) {
-    if (angular.isFunction(headers) && !callback) {
-      callback = headers;
-      headers = undefined;
-    }
     if (!this.handlers[address]) {
       this.handlers[address] = [];
     }
@@ -57,26 +67,47 @@ export default class Delegator {
     deconstructor.displayName = `${moduleName}.service.registerHandler.deconstructor`;
     return deconstructor;
   }
+
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#on
+   *
+   * @description
+   * See (using {@link knalli.angular-vertxbus.vertxEventBusService#methods_registerHandler registerHandler()})
+   */
   on(address, headers, callback) {
-    if (typeof headers === 'function' && !callback) {
-      callback = headers;
-      headers = undefined;
-    }
     return this.registerHandler(address, headers, callback);
   }
+
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#addListener
+   *
+   * @description
+   * See (using {@link knalli.angular-vertxbus.vertxEventBusService#methods_registerHandler registerHandler()})
+   */
   addListener(address, headers, callback) {
-    if (typeof headers === 'function' && !callback) {
-      callback = headers;
-      headers = undefined;
-    }
     return this.registerHandler(address, headers, callback);
   }
 
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#unregisterHandler
+   *
+   * @description
+   * Removes a callback handler for the specified address match.
+   *
+   * @param {string} address target address
+   * @param {object} headers optional headers
+   * @param {function} callback handler with params `(message, replyTo)`
+   */
   unregisterHandler(address, headers, callback) {
-    if (typeof headers === 'function' && !callback) {
-      callback = headers;
-      headers = undefined;
-    }
     // Remove from internal map
     if (this.handlers[address]) {
       var index = this.handlers[address].indexOf({headers, callback});
@@ -92,58 +123,190 @@ export default class Delegator {
       this.delegate.unregisterHandler(address, headers, callback);
     }
   }
+
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#un
+   *
+   * @description
+   * See (using {@link knalli.angular-vertxbus.vertxEventBusService#methods_registerHandler unregisterHandler()})
+   */
   un(address, headers, callback) {
-    if (typeof headers === 'function' && !callback) {
-      callback = headers;
-      headers = undefined;
-    }
     return this.unregisterHandler(address, headers, callback);
   }
+
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#removeListener
+   *
+   * @description
+   * See (using {@link knalli.angular-vertxbus.vertxEventBusService#methods_registerHandler unregisterHandler()})
+   */
   removeListener(address, headers, callback) {
-    if (typeof headers === 'function' && !callback) {
-      callback = headers;
-      headers = undefined;
-    }
     return this.unregisterHandler(address, headers, callback);
   }
 
-  send(address, message, options = {}) {
-
-    // FALLBACK: signature change since 2.0
-    if (!angular.isObject(options)) {
-      this.$log.error(`${moduleName}: Signature of vertxEventBusService.send() has been changed!`);
-      return this.send(address, message, {
-        timeout: arguments[2] !== undefined ? arguments[2] : 10000,
-        expectReply: arguments[3] !== undefined ? arguments[3] : true
-      });
-    }
-
-    return this.delegate.send(address, message, options.timeout, options.expectReply);
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#send
+   *
+   * @description
+   * Sends a message to the specified address (using {@link knalli.angular-vertxbus.vertxEventBus#methods_send vertxEventBus.send()}).
+   *
+   * @param {string} address target address
+   * @param {object} message payload message
+   * @param {object} headers headers
+   * @param {number=} [options.timeout=10000] (in ms) after which the promise will be rejected
+   * @param {boolean=} [options.expectReply=true] if false, the promise will be resolved directly and
+   *                                       no replyHandler will be created
+   * @returns {object} promise
+   */
+  send(address, message, headers = {}, options = {timeout: 10000, expectReply: true}) {
+    return this.delegate.send(address, message, headers, options.timeout, options.expectReply);
   }
 
-  publish(address, message) {
-    return this.delegate.publish(address, message);
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#publish
+   *
+   * @description
+   * Publishes a message to the specified address (using {@link knalli.angular-vertxbus.vertxEventBus#methods_publish vertxEventBus.publish()}).
+   *
+   * @param {string} address target address
+   * @param {object} message payload message
+   * @param {object=} headers headers
+   * @returns {boolean} false if cannot be send or queued
+   */
+  publish(address, message, headers = {}) {
+    return this.delegate.publish(address, message, headers);
   }
-  emit(address, message) {
-    return this.publish(address, message);
+
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#emit
+   *
+   * @description
+   * See (using {@link knalli.angular-vertxbus.vertxEventBusService#methods_publish publish()})
+   */
+  emit(address, message, headers = {}) {
+    return this.publish(address, message, headers);
   }
 
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#getConnectionState
+   *
+   * @description
+   * Returns the current connection state. The state is being cached internally.
+   *
+   * @returns {number} state type of vertx.EventBus
+   */
   getConnectionState() {
     return this.delegate.getConnectionState();
   }
 
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#readyState
+   *
+   * @description
+   * See (using {@link knalli.angular-vertxbus.vertxEventBusService#methods_getConnectionState getConnectionState()})
+   */
   readyState() {
     return this.getConnectionState();
   }
 
+
+
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#isConnectionOpen
+   *
+   * @description
+   * Returns true if the current connection state ({@link knalli.angular-vertxbus.vertxEventBusService#methods_getConnectionState getConnectionState()}) is `OPEN`.
+   *
+   * @returns {boolean} connection open state
+   */
+  isConnectionOpen() {
+    return this.isConnectionOpen();
+  }
+
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#isEnabled
+   *
+   * @description
+   * Returns true if service is being enabled.
+   *
+   * @returns {boolean} state
+   */
   isEnabled() {
     return this.delegate.isEnabled();
   }
 
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#isConnected
+   *
+   * @description
+   * Returns true if service (and the eventbus) is being connected.
+   *
+   * @returns {boolean} state
+   */
   isConnected() {
     return this.delegate.isConnected();
   }
 
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#isValidSession
+   *
+   * @description
+   * Returns true if the session is valid
+   *
+   * @returns {boolean} state
+   */
+  isValidSession() {
+    return this.delegate.isValidSession();
+  }
+
+  /**
+   * @ngdoc method
+   * @module knalli.angular-vertxbus
+   * @methodOf knalli.angular-vertxbus.vertxEventBusService
+   * @name .#getMessageQueueLength
+   *
+   * @description
+   * Returns the current amount of messages in the internal buffer.
+   *
+   * @returns {number} amount
+   */
+  getMessageQueueLength() {
+    return this.delegate.getMessageQueueLength();
+  }
+
   login(username, password, timeout) {
     return this.delegate.login(username, password, timeout);
   }

src/lib/service/delegate/BaseDelegate.js

@@ -1,5 +1,7 @@
 export default class BaseDelegate {
 
+  observe() {}
+
   getConnectionState() {
     return 3; // CLOSED
   }