diff --git a/src/Subject.ts b/src/Subject.ts index fa3c2ed712..3defb618f8 100644 --- a/src/Subject.ts +++ b/src/Subject.ts @@ -9,6 +9,9 @@ import {$$rxSubscriber} from './symbol/rxSubscriber'; import {throwError} from './util/throwError'; import {ObjectUnsubscribedError} from './util/ObjectUnsubscribedError'; +/** + * @class Subject + */ export class Subject extends Observable implements Observer, Subscription { static create: Function = (destination: Observer, source: Observable): Subject => { @@ -221,6 +224,11 @@ export class Subject extends Observable implements Observer, Subscripti } } +/** + * We need this JSDoc comment for affecting ESDoc. + * @ignore + * @extends {Ignored} + */ class SubjectObservable extends Observable { constructor(source: Subject) { super(); diff --git a/src/observable/ArrayLikeObservable.ts b/src/observable/ArrayLikeObservable.ts index 926b849654..bd0b8b7b3a 100644 --- a/src/observable/ArrayLikeObservable.ts +++ b/src/observable/ArrayLikeObservable.ts @@ -5,6 +5,11 @@ import {EmptyObservable} from './EmptyObservable'; import {Subscriber} from '../Subscriber'; import {Subscription} from '../Subscription'; +/** + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true + */ export class ArrayLikeObservable extends Observable { private mapFn: (x: T, y: number) => T; diff --git a/src/observable/ArrayObservable.ts b/src/observable/ArrayObservable.ts index 32248bf8da..43fcb7a595 100644 --- a/src/observable/ArrayObservable.ts +++ b/src/observable/ArrayObservable.ts @@ -7,19 +7,21 @@ import {isScheduler} from '../util/isScheduler'; import {Subscription} from '../Subscription'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class ArrayObservable extends Observable { /** * @param array * @param scheduler - * @return {ArrayObservable} + * @return {Observable} * @static true * @name fromArray * @owner Observable */ - static create(array: T[], scheduler?: Scheduler) { + static create(array: T[], scheduler?: Scheduler): Observable { return new ArrayObservable(array, scheduler); } diff --git a/src/observable/BoundCallbackObservable.ts b/src/observable/BoundCallbackObservable.ts index b5a3d5b4b6..60b70725f7 100644 --- a/src/observable/BoundCallbackObservable.ts +++ b/src/observable/BoundCallbackObservable.ts @@ -7,7 +7,9 @@ import {errorObject} from '../util/errorObject'; import {AsyncSubject} from '../subject/AsyncSubject'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class BoundCallbackObservable extends Observable { subject: AsyncSubject; diff --git a/src/observable/BoundNodeCallbackObservable.ts b/src/observable/BoundNodeCallbackObservable.ts index 55b46d4185..f0b8a434dc 100644 --- a/src/observable/BoundNodeCallbackObservable.ts +++ b/src/observable/BoundNodeCallbackObservable.ts @@ -7,7 +7,9 @@ import {errorObject} from '../util/errorObject'; import {AsyncSubject} from '../subject/AsyncSubject'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class BoundNodeCallbackObservable extends Observable { subject: AsyncSubject; diff --git a/src/observable/ConnectableObservable.ts b/src/observable/ConnectableObservable.ts index b353574fd6..1f1fce5921 100644 --- a/src/observable/ConnectableObservable.ts +++ b/src/observable/ConnectableObservable.ts @@ -3,6 +3,9 @@ import {Observable} from '../Observable'; import {Subscriber} from '../Subscriber'; import {Subscription} from '../Subscription'; +/** + * @class ConnectableObservable + */ export class ConnectableObservable extends Observable { protected subject: Subject; @@ -62,6 +65,11 @@ class ConnectableSubscription extends Subscription { } } +/** + * We need this JSDoc comment for affecting ESDoc. + * @ignore + * @extends {Ignored} + */ class RefCountObservable extends Observable { connection: Subscription; diff --git a/src/observable/DeferObservable.ts b/src/observable/DeferObservable.ts index cebc595499..3595db9fe5 100644 --- a/src/observable/DeferObservable.ts +++ b/src/observable/DeferObservable.ts @@ -4,7 +4,9 @@ import {tryCatch} from '../util/tryCatch'; import {errorObject} from '../util/errorObject'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class DeferObservable extends Observable { diff --git a/src/observable/EmptyObservable.ts b/src/observable/EmptyObservable.ts index 160f1f8424..3e161365c2 100644 --- a/src/observable/EmptyObservable.ts +++ b/src/observable/EmptyObservable.ts @@ -4,13 +4,15 @@ import {Observable} from '../Observable'; import {Subscription} from '../Subscription'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class EmptyObservable extends Observable { /** * @param scheduler - * @return {EmptyObservable} + * @return {Observable} * @static true * @name empty * @owner Observable diff --git a/src/observable/ErrorObservable.ts b/src/observable/ErrorObservable.ts index 43663fb99b..6ef141ee83 100644 --- a/src/observable/ErrorObservable.ts +++ b/src/observable/ErrorObservable.ts @@ -3,7 +3,9 @@ import {Observable} from '../Observable'; import {Subscription} from '../Subscription'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class ErrorObservable extends Observable { diff --git a/src/observable/ForkJoinObservable.ts b/src/observable/ForkJoinObservable.ts index ce8539a4e8..7c8e8a5b7d 100644 --- a/src/observable/ForkJoinObservable.ts +++ b/src/observable/ForkJoinObservable.ts @@ -6,7 +6,9 @@ import {isPromise} from '../util/isPromise'; import {isArray} from '../util/isArray'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class ForkJoinObservable extends Observable { constructor(private sources: Array | Promise>, diff --git a/src/observable/FromEventObservable.ts b/src/observable/FromEventObservable.ts index 50d8175c92..3df2a321f1 100644 --- a/src/observable/FromEventObservable.ts +++ b/src/observable/FromEventObservable.ts @@ -35,7 +35,9 @@ function isEventTarget(sourceObj: any): sourceObj is EventTarget { export type EventTargetLike = EventTarget | NodeStyleEventEmmitter | JQueryStyleEventEmitter | NodeList | HTMLCollection; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class FromEventObservable extends Observable { diff --git a/src/observable/FromEventPatternObservable.ts b/src/observable/FromEventPatternObservable.ts index 20f70d8bea..f96426bf70 100644 --- a/src/observable/FromEventPatternObservable.ts +++ b/src/observable/FromEventPatternObservable.ts @@ -5,7 +5,9 @@ import {errorObject} from '../util/errorObject'; import {Subscriber} from '../Subscriber'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class FromEventPatternObservable extends Observable { diff --git a/src/observable/FromObservable.ts b/src/observable/FromObservable.ts index 2d400b343e..4f0981aa36 100644 --- a/src/observable/FromObservable.ts +++ b/src/observable/FromObservable.ts @@ -17,7 +17,9 @@ import {ObserveOnSubscriber} from '../operator/observeOn'; const isArrayLike = ((x: any): x is ArrayLike => x && typeof x.length === 'number'); /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class FromObservable extends Observable { constructor(private ish: ObservableInput, private scheduler: Scheduler) { diff --git a/src/observable/IfObservable.ts b/src/observable/IfObservable.ts index c12ba85be1..1221499230 100644 --- a/src/observable/IfObservable.ts +++ b/src/observable/IfObservable.ts @@ -2,6 +2,11 @@ import {Observable} from '../Observable'; import {Subscriber} from '../Subscriber'; import {Subscription} from '../Subscription'; +/** + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true + */ export class IfObservable extends Observable { static create(condition: () => boolean, diff --git a/src/observable/IntervalObservable.ts b/src/observable/IntervalObservable.ts index cf3cdda5d6..1e3d4474c0 100644 --- a/src/observable/IntervalObservable.ts +++ b/src/observable/IntervalObservable.ts @@ -5,7 +5,9 @@ import {Observable} from '../Observable'; import {async} from '../scheduler/async'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class IntervalObservable extends Observable { /** diff --git a/src/observable/IteratorObservable.ts b/src/observable/IteratorObservable.ts index 5f9867160a..b95be77db4 100644 --- a/src/observable/IteratorObservable.ts +++ b/src/observable/IteratorObservable.ts @@ -9,6 +9,11 @@ import {errorObject} from '../util/errorObject'; import {Subscription} from '../Subscription'; import {Subscriber} from '../Subscriber'; +/** + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true + */ export class IteratorObservable extends Observable { private iterator: any; diff --git a/src/observable/NeverObservable.ts b/src/observable/NeverObservable.ts index 373f6749b8..b48b2f3a66 100644 --- a/src/observable/NeverObservable.ts +++ b/src/observable/NeverObservable.ts @@ -3,7 +3,9 @@ import {Subscriber} from '../Subscriber'; import {noop} from '../util/noop'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class NeverObservable extends Observable { /** diff --git a/src/observable/PromiseObservable.ts b/src/observable/PromiseObservable.ts index d7a6ed4c0a..0c849a5299 100644 --- a/src/observable/PromiseObservable.ts +++ b/src/observable/PromiseObservable.ts @@ -5,7 +5,9 @@ import {Subscriber} from '../Subscriber'; import {Subscription} from '../Subscription'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class PromiseObservable extends Observable { diff --git a/src/observable/RangeObservable.ts b/src/observable/RangeObservable.ts index 05919fa23e..9f441ba9dc 100644 --- a/src/observable/RangeObservable.ts +++ b/src/observable/RangeObservable.ts @@ -4,7 +4,9 @@ import {Subscription} from '../Subscription'; import {Subscriber} from '../Subscriber'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class RangeObservable extends Observable { diff --git a/src/observable/ScalarObservable.ts b/src/observable/ScalarObservable.ts index e7b5c6801f..e8bc554937 100644 --- a/src/observable/ScalarObservable.ts +++ b/src/observable/ScalarObservable.ts @@ -3,6 +3,11 @@ import {Observable} from '../Observable'; import {Subscriber} from '../Subscriber'; import {Subscription} from '../Subscription'; +/** + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true + */ export class ScalarObservable extends Observable { static create(value: T, scheduler?: Scheduler): ScalarObservable { return new ScalarObservable(value, scheduler); diff --git a/src/observable/SubscribeOnObservable.ts b/src/observable/SubscribeOnObservable.ts index 3919f1a646..d497859d98 100644 --- a/src/observable/SubscribeOnObservable.ts +++ b/src/observable/SubscribeOnObservable.ts @@ -5,6 +5,11 @@ import {Observable} from '../Observable'; import {asap} from '../scheduler/asap'; import {isNumeric} from '../util/isNumeric'; +/** + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true + */ export class SubscribeOnObservable extends Observable { static create(source: Observable, delay: number = 0, scheduler: Scheduler = asap): Observable { return new SubscribeOnObservable(source, delay, scheduler); diff --git a/src/observable/TimerObservable.ts b/src/observable/TimerObservable.ts index 3db92b49c5..ecf66b5dc6 100644 --- a/src/observable/TimerObservable.ts +++ b/src/observable/TimerObservable.ts @@ -8,7 +8,9 @@ import {Subscription} from '../Subscription'; import {Subscriber} from '../Subscriber'; /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class TimerObservable extends Observable { diff --git a/src/observable/UsingObservable.ts b/src/observable/UsingObservable.ts index a7b2ca941d..90089e0bf0 100644 --- a/src/observable/UsingObservable.ts +++ b/src/observable/UsingObservable.ts @@ -2,6 +2,11 @@ import {Observable} from '../Observable'; import {Subscriber} from '../Subscriber'; import {Subscription} from '../Subscription'; +/** + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true + */ export class UsingObservable extends Observable { static create(resourceFactory: () => Subscription, diff --git a/src/observable/dom/AjaxObservable.ts b/src/observable/dom/AjaxObservable.ts index a7f2995a38..5d0d74a6fe 100644 --- a/src/observable/dom/AjaxObservable.ts +++ b/src/observable/dom/AjaxObservable.ts @@ -71,28 +71,41 @@ export function ajaxGetJSON(url: string, resultSelector?: (data: T) => R, const finalResultSelector = resultSelector ? (res: AjaxResponse) => resultSelector(res.response) : (res: AjaxResponse) => res.response; return new AjaxObservable({ method: 'GET', url, responseType: 'json', resultSelector: finalResultSelector, headers }); }; + +/** + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true + */ +export class AjaxObservable extends Observable { /** - * Creates an observable for an Ajax request with either a request object with url, headers, etc or a string for a URL. + * Creates an observable for an Ajax request with either a request object with + * url, headers, etc or a string for a URL. * * @example - * source = Rx.Observable.ajax('/products'); - * source = Rx.Observable.ajax( url: 'products', method: 'GET' }); - * - * @param {Object} request Can be one of the following: + * source = Rx.Observable.ajax('/products'); + * source = Rx.Observable.ajax( url: 'products', method: 'GET' }); * - * A string of the URL to make the Ajax call. - * An object with the following properties + * @param {string|Object} request Can be one of the following: + * A string of the URL to make the Ajax call. + * An object with the following properties * - url: URL of the request * - body: The body of the request * - method: Method of the request, such as GET, POST, PUT, PATCH, DELETE * - async: Whether the request is async * - headers: Optional headers * - crossDomain: true if a cross domain request, else false - * - createXHR: a function to override if you need to use an alternate XMLHttpRequest implementation. - * - resultSelector: a function to use to alter the output value type of the Observable. Gets {AjaxResponse} as an argument + * - createXHR: a function to override if you need to use an alternate + * XMLHttpRequest implementation. + * - resultSelector: a function to use to alter the output value type of + * the Observable. Gets {@link AjaxResponse} as an argument. * @return {Observable} An observable sequence containing the XMLHttpRequest. + * @static true + * @name ajax + * @owner Observable */ -export class AjaxObservable extends Observable { + static _create_stub(): void { return null; } + static create: AjaxCreationMethod = (() => { const create: any = (urlOrRequest: string | AjaxRequest) => { return new AjaxObservable(urlOrRequest); diff --git a/src/observable/dom/WebSocketSubject.ts b/src/observable/dom/WebSocketSubject.ts index 0245804e77..d5f1cd9bd7 100644 --- a/src/observable/dom/WebSocketSubject.ts +++ b/src/observable/dom/WebSocketSubject.ts @@ -21,7 +21,9 @@ export interface WebSocketSubjectConfig { } /** - * + * We need this JSDoc comment for affecting ESDoc. + * @extends {Ignored} + * @hide true */ export class WebSocketSubject extends Subject { url: string; diff --git a/src/operator/delayWhen.ts b/src/operator/delayWhen.ts index 52d3de7844..3563ba911e 100644 --- a/src/operator/delayWhen.ts +++ b/src/operator/delayWhen.ts @@ -114,6 +114,11 @@ class DelayWhenSubscriber extends OuterSubscriber { } } +/** + * We need this JSDoc comment for affecting ESDoc. + * @ignore + * @extends {Ignored} + */ class SubscriptionDelayObservable extends Observable { constructor(protected source: Observable, private subscriptionDelay: Observable) { super(); diff --git a/src/operator/groupBy.ts b/src/operator/groupBy.ts index 7a13f0fbcb..ef21c0b80d 100644 --- a/src/operator/groupBy.ts +++ b/src/operator/groupBy.ts @@ -8,15 +8,22 @@ import {FastMap} from '../util/FastMap'; /** * Groups the items emitted by an Observable according to a specified criterion, - * and emits these grouped items as `GroupedObservables`, one `GroupedObservable` per group. + * and emits these grouped items as `GroupedObservables`, one + * {@link GroupedObservable} per group. * * * - * @param {Function} keySelector - a function that extracts the key for each item - * @param {Function} elementSelector - a function that extracts the return element for each item - * @return {Observable} an Observable that emits GroupedObservables, each of which corresponds - * to a unique key value and each of which emits those items from the source Observable that share - * that key value. + * @param {function(value: T): K} keySelector a function that extracts the key + * for each item. + * @param {function(value: T): R} [elementSelector] a function that extracts the + * return element for each item. + * @param {function(grouped: GroupedObservable): Observable} [durationSelector] + * a function that returns an Observable to determine how long each group should + * exist. + * @return {Observable>} an Observable that emits + * GroupedObservables, each of which corresponds to a unique key value and each + * of which emits those items from the source Observable that share that key + * value. * @method groupBy * @owner Observable */ @@ -211,6 +218,14 @@ class GroupDurationSubscriber extends Subscriber { } } +/** + * An Observable representing values belonging to the same group represented by + * a common key. The values emitted by a GroupedObservable come from the source + * Observable. The common key is available as the field `key` on a + * GroupedObservable instance. + * + * @class GroupedObservable + */ export class GroupedObservable extends Observable { constructor(public key: K, private groupSubject: Subject, diff --git a/src/subject/AsyncSubject.ts b/src/subject/AsyncSubject.ts index 3a8bb4f487..b5ec3f3feb 100644 --- a/src/subject/AsyncSubject.ts +++ b/src/subject/AsyncSubject.ts @@ -2,6 +2,9 @@ import {Subject} from '../Subject'; import {Subscriber} from '../Subscriber'; import {Subscription} from '../Subscription'; +/** + * @class AsyncSubject + */ export class AsyncSubject extends Subject { value: T = null; hasNext: boolean = false; diff --git a/src/subject/BehaviorSubject.ts b/src/subject/BehaviorSubject.ts index f39367e5c1..c3595880d4 100644 --- a/src/subject/BehaviorSubject.ts +++ b/src/subject/BehaviorSubject.ts @@ -4,6 +4,9 @@ import {Subscription} from '../Subscription'; import {throwError} from '../util/throwError'; import {ObjectUnsubscribedError} from '../util/ObjectUnsubscribedError'; +/** + * @class BehaviorSubject + */ export class BehaviorSubject extends Subject { constructor(private _value: T) { diff --git a/src/subject/ReplaySubject.ts b/src/subject/ReplaySubject.ts index f50cda0ff6..74c2b6d070 100644 --- a/src/subject/ReplaySubject.ts +++ b/src/subject/ReplaySubject.ts @@ -5,6 +5,9 @@ import {Subscriber} from '../Subscriber'; import {Subscription} from '../Subscription'; import {ObserveOnSubscriber} from '../operator/observeOn'; +/** + * @class ReplaySubject + */ export class ReplaySubject extends Subject { private events: ReplayEvent[] = []; private scheduler: Scheduler; diff --git a/src/testing/ColdObservable.ts b/src/testing/ColdObservable.ts index 7920a31930..19e707332d 100644 --- a/src/testing/ColdObservable.ts +++ b/src/testing/ColdObservable.ts @@ -7,6 +7,11 @@ import {SubscriptionLoggable} from './SubscriptionLoggable'; import {applyMixins} from '../util/applyMixins'; import {Subscriber} from '../Subscriber'; +/** + * We need this JSDoc comment for affecting ESDoc. + * @ignore + * @extends {Ignored} + */ export class ColdObservable extends Observable implements SubscriptionLoggable { public subscriptions: SubscriptionLog[] = []; scheduler: Scheduler; diff --git a/src/testing/HotObservable.ts b/src/testing/HotObservable.ts index bef1d717f9..14e973b630 100644 --- a/src/testing/HotObservable.ts +++ b/src/testing/HotObservable.ts @@ -7,6 +7,11 @@ import {SubscriptionLog} from './SubscriptionLog'; import {SubscriptionLoggable} from './SubscriptionLoggable'; import {applyMixins} from '../util/applyMixins'; +/** + * We need this JSDoc comment for affecting ESDoc. + * @ignore + * @extends {Ignored} + */ export class HotObservable extends Subject implements SubscriptionLoggable { public subscriptions: SubscriptionLog[] = []; scheduler: Scheduler; diff --git a/tools/custom-esdoc-plugin.js b/tools/custom-esdoc-plugin.js index 3111eb863a..b818d3b82b 100644 --- a/tools/custom-esdoc-plugin.js +++ b/tools/custom-esdoc-plugin.js @@ -1,42 +1,48 @@ -// Fixes ESDoc structure by moving all "add-able" operator functions -// (either prototype operator or static operator) under the Observable class. -// Looks for the "@owner" tag, then moves the thing to that owner. "@owner" is -// usually "Observable", but may be something else. -exports.onHandleTag = function onHandleTag(ev) { - function getTagValue(tag, tagName) { - var unknownTags = tag.unknown; - if (!unknownTags) { - return null; - } - var unknownTagsLength = unknownTags.length; - for (var i = 0; i < unknownTagsLength; i++) { - if (unknownTags[i].tagName === tagName) { - return unknownTags[i].tagValue; - } - } +function getTagValue(tag, tagName) { + var unknownTags = tag.unknown; + if (!unknownTags) { return null; } - - function getLongname(name) { - var index = ev.data.tag.findIndex(function (t) { - return t.name === name; - }); - if (index === -1) { - throw new Error('Could not find longname for unknown tag named "' + name + - '"'); - } else { - return ev.data.tag[index].longname; + var unknownTagsLength = unknownTags.length; + for (var i = 0; i < unknownTagsLength; i++) { + if (unknownTags[i].tagName === tagName) { + return unknownTags[i].tagValue; } } + return null; +} + +function getLongname(ev, name) { + var index = ev.data.tag.findIndex(function (t) { + return t.name === name; + }); + if (index === -1) { + throw new Error('Could not find longname for unknown tag named "' + name + + '"'); + } else { + return ev.data.tag[index].longname; + } +} +/** + * Fixes ESDoc structure by moving all "add-able" operator functions + * (either prototype operator or static operator) under the Observable class. + * Looks for the "@owner" tag, then moves the thing to that owner. "@owner" is + * usually "Observable", but may be something else. + */ +exports.onHandleTag = function onHandleTag(ev) { var tagsLen = ev.data.tag.length; for (var i = 0; i < tagsLen; i++) { var tag = ev.data.tag[i]; var owner = getTagValue(tag, '@owner'); var name = getTagValue(tag, '@name'); var isStatic = getTagValue(tag, '@static'); - if (owner) { - var ownerLongname = getLongname(owner); + var isHidden = getTagValue(tag, '@hide'); + if (isHidden) { + ev.data.tag[i] = {name: '', longname: ''}; + ev.data.tag[i]['export'] = false; + } else if (owner) { + var ownerLongname = getLongname(ev, owner); tag.kind = 'method'; tag.static = false; tag.memberof = ownerLongname;