From bb560329b92bbb6a2a085bb4244c937637595da2 Mon Sep 17 00:00:00 2001 From: ltlombardi Date: Thu, 20 Dec 2018 16:49:18 -0200 Subject: [PATCH] Add JSDoc to more methods @knockout (#31507) * Add JSDoc to observableArray methods I added JSDoc to all the observableArray methods and fixed some spacing irregularities in the file(extra or missing space) * - add jsdoc for more methods. * - add two missing methods: getDependenciesCount(): number; and isActive(): boolean; - small fixes in verb conjugation for JSDOC - more JSDOC - improvements in ignoreDependencies method signature * this is a test * new test with different author * this is a test of author * test 2 * yet again * 4th is the charm * It was a breaking change I'll leave to a separate branch * small fixes * -split KnockoutComputedDefine in two interfaces. One used together with evaluatorFunction and other when read property is required * Small fixes * Revert "-split KnockoutComputedDefine in two interfaces." This reverts commit 41a7986e94f3e5772a711c4b4f1dd8f52125d945. changes for another PR --- types/knockout/index.d.ts | 192 ++++++++++++++++++++++++++++++++++---- 1 file changed, 176 insertions(+), 16 deletions(-) diff --git a/types/knockout/index.d.ts b/types/knockout/index.d.ts index e6d180c2c4..047258539a 100644 --- a/types/knockout/index.d.ts +++ b/types/knockout/index.d.ts @@ -48,7 +48,7 @@ interface KnockoutObservableArrayFunctions extends KnockoutReadonlyObservable * Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements. * @param start The zero-based location in the array from which to start removing elements. * @param deleteCount The number of elements to remove. - * @param ...items Elements to insert into the array in place of the deleted elements. + * @param items Elements to insert into the array in place of the deleted elements. */ splice(start: number, deleteCount: number, ...items: T[]): T[]; /** @@ -57,7 +57,7 @@ interface KnockoutObservableArrayFunctions extends KnockoutReadonlyObservable pop(): T; /** * Adds a new item to the end of array. - * @param ...items Items to be added + * @param items Items to be added */ push(...items: T[]): void; /** @@ -66,7 +66,7 @@ interface KnockoutObservableArrayFunctions extends KnockoutReadonlyObservable shift(): T; /** * Inserts a new item at the beginning of the array. - * @param ...items Items to be added + * @param items Items to be added */ unshift(...items: T[]): number; /** @@ -96,7 +96,7 @@ interface KnockoutObservableArrayFunctions extends KnockoutReadonlyObservable */ remove(item: T): T[]; /** - * Removes all values and returns them as an array. + * Removes all values and returns them as an array. * @param removeFunction A function used to determine true if item should be removed and fasle otherwise */ remove(removeFunction: (item: T) => boolean): T[]; @@ -139,24 +139,70 @@ interface KnockoutSubscribableStatic { } interface KnockoutSubscription { + /** + * Terminates a subscription + */ dispose(): void; } interface KnockoutSubscribable extends KnockoutSubscribableFunctions { - subscribe(callback: (newValue: T) => void, target: any, event: "beforeChange"): KnockoutSubscription; + /** + * Registers to be notified after the observable's value changes + * @param callback Function that is called whenever the notification happens + * @param target Defines the value of 'this' in the callback function + * @param event The name of the event to receive notification for + */ subscribe(callback: (newValue: T) => void, target?: any, event?: "change"): KnockoutSubscription; + /** + * Registers to be notified before the observable's value changes + * @param callback Function that is called whenever the notification happens + * @param target Defines the value of 'this' in the callback function + * @param event The name of the event to receive notification for + */ + subscribe(callback: (newValue: T) => void, target: any, event: "beforeChange"): KnockoutSubscription; + /** + * Registers to be notified when the observable's value changes + * @param callback Function that is called whenever the notification happens + * @param target Defines the value of 'this' in the callback function + * @param event The name of the event to receive notification for + */ subscribe(callback: (newValue: TEvent) => void, target: any, event: string): KnockoutSubscription; - + /** + * Customizes observables basic functionality + * @param requestedExtenders Name of the extender feature and its value, e.g. { notify: 'always' }, { rateLimit: 50 } + */ extend(requestedExtenders: { [key: string]: any; }): KnockoutSubscribable; + /** + * Gets total number of subscribers + */ getSubscriptionsCount(): number; + /** + * Gets number of subscribers of a particular event + * @param event Event name + */ + getSubscriptionsCount(event: string): number; } interface KnockoutComputedStatic { fn: KnockoutComputedFunctions; + /** + * Creates computed observable + */ (): KnockoutComputed; - (func: () => T, context?: any, options?: any): KnockoutComputed; - (def: KnockoutComputedDefine, context?: any): KnockoutComputed; + /** + * Creates computed observable + * @param evaluatorFunction Function that computes the observable value + * @param context Defines the value of 'this' when evaluating the computed observable + * @param options An object with further properties for the computed observable + */ + (evaluatorFunction: () => T, context?: any, options?: any): KnockoutComputed; + /** + * Creates computed observable + * @param options An object that defines the computed observable options and behavior + * @param context Defines the value of 'this' when evaluating the computed observable + */ + (options: KnockoutComputedDefine, context?: any): KnockoutComputed; } interface KnockoutReadonlyComputed extends KnockoutReadonlyObservable { @@ -167,11 +213,27 @@ interface KnockoutReadonlyComputed extends KnockoutReadonlyObservable { interface KnockoutComputed extends KnockoutReadonlyComputed, KnockoutObservable, KnockoutComputedFunctions { fn: KnockoutComputedFunctions; - // It's possible for a to be undefined, since the equalityComparer is run on the initial + // It's possible for 'a' to be undefined, since the equalityComparer is run on the initial // computation with undefined as the first argument. This is user-relevant for deferred computeds. equalityComparer(a: T | undefined, b: T): boolean; - + /** + * Manually disposes the computed observable, clearing all subscriptions to dependencies. + * This function is useful if you want to stop a computed observable from being updated or want to clean up memory for a + * computed observable that has dependencies on observables that won’t be cleaned. + */ dispose(): void; + /** + * Returns whether the computed observable may be updated in the future. A computed observable is inactive if it has no dependencies. + */ + isActive(): boolean; + /** + * Returns the current number of dependencies of the computed observable. + */ + getDependenciesCount(): number; + /** + * Customizes observables basic functionality + * @param requestedExtenders Name of the extender feature and it's value, e.g. { notify: 'always' }, { rateLimit: 50 } + */ extend(requestedExtenders: { [key: string]: any; }): KnockoutComputed; } @@ -222,6 +284,10 @@ interface KnockoutObservableStatic { interface KnockoutReadonlyObservable extends KnockoutSubscribable, KnockoutObservableFunctions { (): T; + + /** + * Returns the current value of the computed observable without creating a dependency + */ peek(): T; valueHasMutated?: { (): void; }; valueWillMutate?: { (): void; }; @@ -235,12 +301,38 @@ interface KnockoutObservable extends KnockoutReadonlyObservable { } interface KnockoutComputedDefine { + /** + * A function that is used to evaluate the computed observable’s current value. + */ read(): T; + /** + * Makes the computed observable writable. This is a function that receives values that other code is trying to write to your computed observable. + * It’s up to you to supply custom logic to handle the incoming values, typically by writing the values to some underlying observable(s). + * @param value + */ write?(value: T): void; + /** + * Disposal of the computed observable will be triggered when the specified DOM node is removed by KO. + * This feature is used to dispose computed observables used in bindings when nodes are removed by the template and control-flow bindings. + */ disposeWhenNodeIsRemoved?: Node; + /** + * This function is executed before each re-evaluation to determine if the computed observable should be disposed. + * A true-ish result will trigger disposal of the computed observable. + */ disposeWhen?(): boolean; + /** + * Defines the value of 'this' whenever KO invokes your 'read' or 'write' callbacks. + */ owner?: any; + /** + * If true, then the value of the computed observable will not be evaluated until something actually attempts to access its value or manually subscribes to it. + * By default, a computed observable has its value determined immediately during creation. + */ deferEvaluation?: boolean; + /** + * If true, the computed observable will be set up as a purecomputed observable. This option is an alternative to the ko.pureComputed constructor. + */ pure?: boolean; } @@ -547,7 +639,17 @@ interface KnockoutStatic { observable: KnockoutObservableStatic; computed: KnockoutComputedStatic; + /** + * Creates a pure computed observable + * @param evaluatorFunction Function that computes the observable value + * @param context Defines the value of 'this' when evaluating the computed observable + */ pureComputed(evaluatorFunction: () => T, context?: any): KnockoutComputed; + /** + * Creates a pure computed observable + * @param options An object that defines the computed observable options and behavior + * @param context Defines the value of 'this' when evaluating the computed observable + */ pureComputed(options: KnockoutComputedDefine, context?: any): KnockoutComputed; observableArray: KnockoutObservableArrayStatic; @@ -557,14 +659,35 @@ interface KnockoutStatic { toJSON(viewModel: any, replacer?: Function, space?: any): string; toJS(viewModel: any): any; - + /** + * Determine if argument is an observable. Returns true for observables, observable arrays, and all computed observables. + * @param instance Object to be checked + */ isObservable(instance: any): instance is KnockoutObservable; + /** + * Determine if argument is an observable. Returns true for observables, observable arrays, and all computed observables. + * @param instance Object to be checked + */ isObservable(instance: KnockoutObservable | T): instance is KnockoutObservable; - + /** + * Determine if argument is a writable observable. Returns true for observables, observable arrays, and writable computed observables. + * @param instance Object to be checked + */ isWriteableObservable(instance: any): instance is KnockoutObservable; + /** + * Determine if argument is a writable observable. Returns true for observables, observable arrays, and writable computed observables. + * @param instance Object to be checked + */ isWriteableObservable(instance: KnockoutObservable | T): instance is KnockoutObservable; - + /** + * Determine if argument is a computed observable + * @param instance Object to be checked + */ isComputed(instance: any): instance is KnockoutComputed; + /** + * Determine if argument is a computed observable + * @param instance Object to be checked + */ isComputed(instance: KnockoutObservable | T): instance is KnockoutComputed; dataFor(node: any): any; @@ -575,6 +698,9 @@ interface KnockoutStatic { unwrap(value: KnockoutObservable | T): T; unwrap(value: KnockoutObservableArray | T[]): T[]; + /** + * Get information about the current computed property during the execution of a computed observable’s evaluator function. + */ computedContext: KnockoutComputedContext; ////////////////////////////////// @@ -656,7 +782,13 @@ interface KnockoutStatic { renderTemplateForEach(template: Function, arrayOrObservableArray: KnockoutObservable, options: Object, targetNode: Node, parentBindingContext: KnockoutBindingContext): any; renderTemplateForEach(template: any, arrayOrObservableArray: KnockoutObservable, options: Object, targetNode: Node, parentBindingContext: KnockoutBindingContext): any; - ignoreDependencies(callback: () => T): T; + /** + * Executes a callback function inside a computed observable, without creating a dependecy between it and the observables inside the function + * @param callback Function to be called. + * @param callbackTarget Defines the value of 'this' in the callback function + * @param callbackArgs Arguments for the callback Function + */ + ignoreDependencies(callback: () => T, callbackTarget?: any, callbackArgs?: any): T; expressionRewriting: { bindingRewriteValidators: any[]; @@ -731,7 +863,14 @@ interface KnockoutBindingProvider { } interface KnockoutComputedContext { + /** + * Returns the number of dependencies of the computed observable detected so far during the current evaluation. + */ getDependenciesCount(): number; + /** + * A function that returns true if called during the first ever evaluation of the current computed observable, or false otherwise. + * For pure computed observables, isInitial() is always undefined. + */ isInitial: () => boolean; isSleeping: boolean; } @@ -799,12 +938,33 @@ declare namespace KnockoutComponentTypes { } interface KnockoutComponents { - // overloads for register method: - register(componentName: string, config: KnockoutComponentTypes.Config | KnockoutComponentTypes.EmptyConfig): void; + /** + * Registers a component, in the default component loader, to be used by name in the component binding. + * @param componentName Component name. + * @param config Component configuration. + */ + register(componentName: string, config: KnockoutComponentTypes.Config | KnockoutComponentTypes.EmptyConfig): void; + /** + * Determine if a component with the specified name is already registered in the default component loader. + * @param componentName Component name. + */ isRegistered(componentName: string): boolean; + /** + * Removes the named component from the default component loader registry. Or if no such component was registered, does nothing. + * @param componentName Component name. + */ unregister(componentName: string): void; + /** + * Searchs each registered component loader by component name, and returns the viewmodel/template declaration via callback parameter + * @param componentName Component name. + * @param callback Function to be called with the viewmodel/template declaration parameter. + */ get(componentName: string, callback: (definition: KnockoutComponentTypes.Definition) => void): void; + /** + * Clears the cache knockout creates to speed up component loading, for a given component. + * @param componentName Component name. + */ clearCachedDefinition(componentName: string): void defaultLoader: KnockoutComponentTypes.Loader; loaders: KnockoutComponentTypes.Loader[];