From c22650edabda628afb4286882fe283354bba2454 Mon Sep 17 00:00:00 2001 From: Derek Cicerone Date: Sat, 20 Dec 2014 13:07:29 -0500 Subject: [PATCH] Fix types for promises in selenium-webdriver The webdriver promises were recently made generic (that whole commit is actually pretty impressive!) but I think the definitions for the then methods are slightly incorrect. Looking at the original jsdoc (which I assume was imported from the original closure annotations) some edits appear to be necessary: 1. The return type of the success callback should match the returned promise's generic type. 2. The success callback can return a promise that will automatically be unwrapped. I also made some other housekeeping edits: * removed @param type information and @template since TypeScript puts type annotations directly in the code * my editor removes trailing whitespace and adds a newline at the EOF Once TypeScript 1.4 is out, these definitions can likely be simplified by using union types. --- selenium-webdriver/selenium-webdriver.d.ts | 110 +++++++++++++++------ 1 file changed, 82 insertions(+), 28 deletions(-) diff --git a/selenium-webdriver/selenium-webdriver.d.ts b/selenium-webdriver/selenium-webdriver.d.ts index a1b777d596..c4af933c96 100644 --- a/selenium-webdriver/selenium-webdriver.d.ts +++ b/selenium-webdriver/selenium-webdriver.d.ts @@ -505,10 +505,10 @@ declare module firefox { } declare module executors { - /** - * Creates a command executor that uses WebDriver's JSON wire protocol. - * @param url The server's URL, or a promise that will resolve to that URL. - * @returns {!webdriver.CommandExecutor} The new command executor. + /** + * Creates a command executor that uses WebDriver's JSON wire protocol. + * @param url The server's URL, or a promise that will resolve to that URL. + * @returns {!webdriver.CommandExecutor} The new command executor. */ function createExecutor(url: string): webdriver.CommandExecutor; function createExecutor(url: webdriver.promise.Promise): webdriver.CommandExecutor; @@ -1055,17 +1055,30 @@ declare module webdriver { /** * Registers listeners for when this instance is resolved. * - * @param {?(function(T): (R|webdriver.promise.Promise.))=} opt_callback The + * @param opt_callback The * function to call if this promise is successfully resolved. The function * should expect a single argument: the promise's resolved value. - * @param {?(function(*): (R|webdriver.promise.Promise.))=} opt_errback The + * @param opt_errback The * function to call if this promise is rejected. The function should expect * a single argument: the rejection reason. - * @return {!webdriver.promise.Promise.} A new promise which will be + * @return A new promise which will be * resolved with the result of the invoked callback. - * @template R */ - then(opt_callback?: (value: T) => any, opt_errback?: (error: any) => any): Promise; + then(opt_callback?: (value: T) => Promise, opt_errback?: (error: any) => any): Promise; + + /** + * Registers listeners for when this instance is resolved. + * + * @param opt_callback The + * function to call if this promise is successfully resolved. The function + * should expect a single argument: the promise's resolved value. + * @param opt_errback The + * function to call if this promise is rejected. The function should expect + * a single argument: the rejection reason. + * @return A new promise which will be + * resolved with the result of the invoked callback. + */ + then(opt_callback?: (value: T) => R, opt_errback?: (error: any) => any): Promise; /** @@ -1161,17 +1174,30 @@ declare module webdriver { /** * Registers listeners for when this instance is resolved. * - * @param {?(function(T): (R|webdriver.promise.Promise.))=} opt_callback The + * @param opt_callback The * function to call if this promise is successfully resolved. The function * should expect a single argument: the promise's resolved value. - * @param {?(function(*): (R|webdriver.promise.Promise.))=} opt_errback The + * @param opt_errback The * function to call if this promise is rejected. The function should expect * a single argument: the rejection reason. - * @return {!webdriver.promise.Promise.} A new promise which will be + * @return A new promise which will be * resolved with the result of the invoked callback. - * @template R */ - then(opt_callback?: (value: T) => any, opt_errback?: (error: any) => any): Promise; + then(opt_callback?: (value: T) => Promise, opt_errback?: (error: any) => any): Promise; + + /** + * Registers listeners for when this instance is resolved. + * + * @param opt_callback The + * function to call if this promise is successfully resolved. The function + * should expect a single argument: the promise's resolved value. + * @param opt_errback The + * function to call if this promise is rejected. The function should expect + * a single argument: the rejection reason. + * @return A new promise which will be + * resolved with the result of the invoked callback. + */ + then(opt_callback?: (value: T) => R, opt_errback?: (error: any) => any): Promise; /** @@ -1304,16 +1330,31 @@ declare module webdriver { * Registers listeners for when this instance is resolved. This function most * overridden by subtypes. * - * @param {Function=} opt_callback The function to call if this promise is + * @param opt_callback The function to call if this promise is * successfully resolved. The function should expect a single argument: the * promise's resolved value. - * @param {Function=} opt_errback The function to call if this promise is + * @param opt_errback The function to call if this promise is * rejected. The function should expect a single argument: the rejection * reason. - * @return {!webdriver.promise.Promise} A new promise which will be resolved + * @return A new promise which will be resolved * with the result of the invoked callback. */ - then(opt_callback?: (value: T) => any, opt_errback?: (error: any) => any): Promise; + then(opt_callback?: (value: T) => Promise, opt_errback?: (error: any) => any): Promise; + + /** + * Registers listeners for when this instance is resolved. This function most + * overridden by subtypes. + * + * @param opt_callback The function to call if this promise is + * successfully resolved. The function should expect a single argument: the + * promise's resolved value. + * @param opt_errback The function to call if this promise is + * rejected. The function should expect a single argument: the rejection + * reason. + * @return A new promise which will be resolved + * with the result of the invoked callback. + */ + then(opt_callback?: (value: T) => R, opt_errback?: (error: any) => any): Promise; /** @@ -1762,7 +1803,7 @@ declare module webdriver { module until { /** - * Defines a condition to + * Defines a condition to */ class Condition { /** @@ -3536,7 +3577,7 @@ declare module webdriver { * capabilities for the new session. * @param {webdriver.promise.ControlFlow=} opt_flow The control flow all driver * commands should execute under, including the initial session creation. - * Defaults to the {@link webdriver.promise.controlFlow() currently active} + * Defaults to the {@link webdriver.promise.controlFlow() currently active} * control flow. * @return {!webdriver.WebDriver} The driver for the newly created session. */ @@ -4554,17 +4595,30 @@ declare module webdriver { /** * Registers listeners for when this instance is resolved. * - * @param {?(function(T): (R|webdriver.promise.Promise.))=} opt_callback The + * @param opt_callback The * function to call if this promise is successfully resolved. The function * should expect a single argument: the promise's resolved value. - * @param {?(function(*): (R|webdriver.promise.Promise.))=} opt_errback The + * @param opt_errback The * function to call if this promise is rejected. The function should expect * a single argument: the rejection reason. - * @return {!webdriver.promise.Promise.} A new promise which will be + * @return A new promise which will be * resolved with the result of the invoked callback. - * @template R */ - then(opt_callback?: (value: WebElement) => any, opt_errback?: (error: any) => any): webdriver.promise.Promise; + then(opt_callback?: (value: WebElement) => webdriver.promise.Promise, opt_errback?: (error: any) => any): webdriver.promise.Promise; + + /** + * Registers listeners for when this instance is resolved. + * + * @param opt_callback The + * function to call if this promise is successfully resolved. The function + * should expect a single argument: the promise's resolved value. + * @param opt_errback The + * function to call if this promise is rejected. The function should expect + * a single argument: the rejection reason. + * @return A new promise which will be + * resolved with the result of the invoked callback. + */ + then(opt_callback?: (value: WebElement) => R, opt_errback?: (error: any) => any): webdriver.promise.Promise; /** @@ -4795,11 +4849,11 @@ declare module 'selenium-webdriver/chrome' { declare module 'selenium-webdriver/firefox' { export = firefox; -} +} declare module 'selenium-webdriver/executors' { export = executors; -} +} declare module 'selenium-webdriver' { export = webdriver; @@ -4807,4 +4861,4 @@ declare module 'selenium-webdriver' { declare module 'selenium-webdriver/testing' { export = testing; -} \ No newline at end of file +}