Fix errors and warnings when building docs + fix links (#5943)

* docs(navigation): remove non-existing url

* docs(Subscription): fix links

* docs(publishReply): fix link to asObservable

* docs(windowTime): fix jsdoc return statement

* chore(services): add `disambiguateByNonMember` disambiguator

* docs: fix `@see` links

* chore(links-package): change disambiguators ordering

Fix Timestamp @see link to point to timestamp operator instead of Timestamp#timestamp member.

* chore: add links to @see sections

docs_app/content/navigation.json

@@ -79,11 +79,6 @@
         }
       ]
     },
-    {
-      "url": "resources",
-      "title": "External Resources",
-      "tooltip": "External Resources"
-    },
     {
       "url": "code-of-conduct",
       "title": "Code of Conduct",

docs_app/tools/transforms/links-package/index.js

@@ -10,14 +10,16 @@ module.exports =
       .factory(require('./services/getLinkInfo'))
       .factory(require('./services/disambiguators/disambiguateByDeprecated'))
       .factory(require('./services/disambiguators/disambiguateByModule'))
+      .factory(require('./services/disambiguators/disambiguateByNonMember'))
 
-      .config(function(inlineTagProcessor, linkInlineTagDef) {
+      .config(function (inlineTagProcessor, linkInlineTagDef) {
         inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef);
       })
 
-      .config(function(getDocFromAlias, disambiguateByDeprecated, disambiguateByModule) {
+      .config(function (getDocFromAlias, disambiguateByDeprecated, disambiguateByNonMember, disambiguateByModule) {
         getDocFromAlias.disambiguators = [
           disambiguateByDeprecated,
+          disambiguateByNonMember,
           disambiguateByModule
         ];
       });

docs_app/tools/transforms/links-package/services/disambiguators/disambiguateByNonMember.js

@@ -0,0 +1,14 @@
+/**
+ * This link disambiguator will remove all the members from the list of ambiguous links
+ * if there is at least one link to a doc that is not a member.
+ *
+ * The heuristic is that exports are more important than members when linking, and that
+ * in general members will be linked to via a more explicit code links such as
+ * `MyClass.member` rather than simply `member`.
+ */
+module.exports = function disambiguateByNonMember() {
+  return (alias, originatingDoc, docs) => {
+    const filteredDocs = docs.filter(doc => doc.docType !== 'member');
+    return filteredDocs.length > 0 ? filteredDocs : docs;
+  };
+};

docs_app/tools/transforms/links-package/services/disambiguators/disambiguateByNonMember.spec.js

@@ -0,0 +1,23 @@
+const disambiguateByNonMember = require('./disambiguateByNonMember')();
+const doc1 = { id: 'doc1', docType: 'function', containerDoc: {} };
+const doc2 = { id: 'doc2', docType: 'member', containerDoc: {} };
+const doc3 = { id: 'doc3', docType: 'member', containerDoc: {} };
+const doc4 = { id: 'doc4', docType: 'class', containerDoc: {} };
+const doc5 = { id: 'doc5', docType: 'member', containerDoc: {} };
+
+describe('disambiguateByNonMember', () => {
+  it('should filter out docs that are not members', () => {
+    const docs = [doc1, doc2, doc3, doc4, doc5];
+    expect(disambiguateByNonMember('alias', {}, docs)).toEqual([doc1, doc4]);
+  });
+
+  it('should return all docs if there are no members', () => {
+    const docs = [doc1, doc4];
+    expect(disambiguateByNonMember('alias', {}, docs)).toEqual([doc1, doc4]);
+  });
+
+  it('should return all docs if there are only members', () => {
+    const docs = [doc2, doc3, doc5];
+    expect(disambiguateByNonMember('alias', {}, docs)).toEqual([doc2, doc3, doc5]);
+  });
+});

src/internal/ReplaySubject.ts

@@ -30,9 +30,9 @@ import { dateTimestampProvider } from './scheduler/dateTimestampProvider';
  * 1. `BehaviorSubject` comes "primed" with a single value upon construction.
  * 2. `ReplaySubject` will replay values, even after observing an error, where `BehaviorSubject` will not.
  *
- * {@see Subject}
- * {@see BehaviorSubject}
- * {@see shareReplay}
+ * @see {@link Subject}
+ * @see {@link BehaviorSubject}
+ * @see {@link shareReplay}
  */
 export class ReplaySubject<T> extends Subject<T> {
   private buffer: (T | number)[] = [];

src/internal/Subscription.ts

@@ -32,13 +32,13 @@ export class Subscription implements SubscriptionLike {
 
   /**
    * The list of registered teardowns to execute upon unsubscription. Adding and removing from this
-   * list occurs in the {@link add} and {@link remove} methods.
+   * list occurs in the {@link #add} and {@link #remove} methods.
    */
   private _teardowns: Exclude<TeardownLogic, void>[] | null = null;
 
   /**
    * @param initialTeardown A function executed first as part of the teardown
-   * process that is kicked off when {@link unsubscribe} is called.
+   * process that is kicked off when {@link #unsubscribe} is called.
    */
   constructor(private initialTeardown?: () => void) {}
 
@@ -98,7 +98,7 @@ export class Subscription implements SubscriptionLike {
 
   /**
    * Adds a teardown to this subscription, so that teardown will be unsubscribed/called
-   * when this subscription is unsubscribed. If this subscription is already {@link closed},
+   * when this subscription is unsubscribed. If this subscription is already {@link #closed},
    * because it has already been unsubscribed, then whatever teardown is passed to it
    * will automatically be executed (unless the teardown itself is also a closed subscription).
    *
@@ -110,7 +110,7 @@ export class Subscription implements SubscriptionLike {
    *
    * `Subscription` instances that are added to this instance will automatically remove themselves
    * if they are unsubscribed. Functions and {@link Unsubscribable} objects that you wish to remove
-   * will need to be removed manually with {@link remove}
+   * will need to be removed manually with {@link #remove}
    *
    * @param teardown The teardown logic to add to this subscription.
    */
@@ -159,7 +159,7 @@ export class Subscription implements SubscriptionLike {
   }
 
   /**
-   * Called on a child when it is removed via {@link remove}.
+   * Called on a child when it is removed via {@link #remove}.
    * @param parent The parent to remove
    */
   private _removeParent(parent: Subscription) {
@@ -172,7 +172,7 @@ export class Subscription implements SubscriptionLike {
   }
 
   /**
-   * Removes a teardown from this subscription that was previously added with the {@link add} method.
+   * Removes a teardown from this subscription that was previously added with the {@link #add} method.
    *
    * Note that `Subscription` instances, when unsubscribed, will automatically remove themselves
    * from every other `Subscription` they have been added to. This means that using the `remove` method

src/internal/ajax/errors.ts

@@ -51,7 +51,7 @@ export interface AjaxErrorCtor {
  * the constructor.
  *
  * @class AjaxError
- * @see ajax
+ * @see {@link ajax}
  */
 export const AjaxError: AjaxErrorCtor = createErrorClass(
   (_super) =>
@@ -92,7 +92,7 @@ export interface AjaxTimeoutErrorCtor {
  * this type.
  *
  * @class AjaxTimeoutError
- * @see ajax
+ * @see {@link ajax}
  */
 export const AjaxTimeoutError: AjaxTimeoutErrorCtor = (() => {
   function AjaxTimeoutErrorImpl(this: any, xhr: XMLHttpRequest, request: AjaxRequest) {

src/internal/operators/endWith.ts

@@ -69,9 +69,9 @@ export function endWith<T, A extends any[] = T[]>(...args: A): OperatorFunction<
  *
  * @param values - Items you want the modified Observable to emit last.
  *
- * @see startWith
- * @see concat
- * @see takeUntil
+ * @see {@link startWith}
+ * @see {@link concat}
+ * @see {@link takeUntil}
  */
 export function endWith<T>(...values: Array<T | SchedulerLike>): MonoTypeOperatorFunction<T> {
   return (source: Observable<T>) => concat(source, of(...values)) as Observable<T>;

src/internal/operators/publishReplay.ts

@@ -26,9 +26,9 @@ export function publishReplay<T>(
 
 /**
  * Creates an observable, that when subscribed to, will create a {@link ReplaySubject},
- * and pass an observable from it (using {@link asObservable}) to the `selector`
- * function, which then returns an observable that is subscribed to before "connecting"
- * the source to the internal `ReplaySubject`.
+ * and pass an observable from it (using [asObservable](api/index/class/Subject#asObservable)) to
+ * the `selector` function, which then returns an observable that is subscribed to before
+ * "connecting" the source to the internal `ReplaySubject`.
  *
  * Since this is deprecated, for additional details see the documentation for {@link connect}.
  *

src/internal/operators/startWith.ts

@@ -70,14 +70,14 @@ export function startWith<T, A extends any[] = T[]>(...values: A): OperatorFunct
  *
  * @param values Items you want the modified Observable to emit first.
  *
- * @see endWith
- * @see finalize
- * @see concat
+ * @see {@link endWith}
+ * @see {@link finalize}
+ * @see {@link concat}
  */
 export function startWith<T, D>(...values: D[]): OperatorFunction<T, T | D> {
   const scheduler = popScheduler(values);
   return operate((source, subscriber) => {
-    // Here we can't pass `undefined` as a scheduler, becuase if we did, the
+    // Here we can't pass `undefined` as a scheduler, because if we did, the
     // code inside of `concat` would be confused by the `undefined`, and treat it
     // like an invalid observable. So we have to split it two different ways.
     (scheduler ? concat(values, source, scheduler) : concat(values, source)).subscribe(subscriber);

src/internal/operators/windowTime.ts

@@ -97,7 +97,7 @@ export function windowTime<T>(
  * values each window can emit before completion.
  * @param scheduler The scheduler on which to schedule the
  * intervals that determine window boundaries.
- * @returnAn observable of windows, which in turn are Observables.
+ * @return An observable of windows, which in turn are Observables.
  */
 export function windowTime<T>(windowTimeSpan: number, ...otherArgs: any[]): OperatorFunction<T, Observable<T>> {
   const scheduler = popScheduler(otherArgs) ?? asyncScheduler;

src/internal/operators/zipAll.ts

@@ -7,8 +7,8 @@ import { joinAllInternals } from './joinAllInternals';
  * it will subscribe to all inner sources, combining their values by index and emitting
  * them.
  *
- * {@see zipWith}
- * {@see zip}
+ * @see {@link zipWith}
+ * @see {@link zip}
  */
 export function zipAll<T>(): OperatorFunction<ObservableInput<T>, T[]>;
 export function zipAll<T>(): OperatorFunction<any, T[]>;

src/internal/types.ts

@@ -37,7 +37,7 @@ export interface MonoTypeOperatorFunction<T> extends OperatorFunction<T, T> {}
  *
  * Emitted by the `timestamp` operator
  *
- * {@see timestamp}
+ * @see {@link timestamp}
  */
 export interface Timestamp<T> {
   value: T;
@@ -53,7 +53,7 @@ export interface Timestamp<T> {
  *
  * Emitted by the `timeInterval` operator.
  *
- * {@see timeInterval}
+ * @see {@link timeInterval}
  */
 export interface TimeInterval<T> {
   value: T;