docs: fix broken links in documentation

[tmair]

Description:
This PR fixes broken links within the documentation that are reported by the build of the documentation.

Two examples of the broken links can be found on the Global Config documentation page.

Related issue (if exists):
None

[niklas-wortmann]

thanks a lot for fixing this

[cartant]

Do links declared like this render correctly in the app? My understanding is that custom link text has to be placed after a |, like this:

{@link Notification#createNext | createNext}

https://tsdoc.org/pages/tags/link/

[benlesh]

@niklas-wortmann @tmair thoughts?

[tmair]

Do links declared like this render correctly in the app?
Yes they do. And the reason why is that documentation generation does not depend on tsdoc but on the dgeni and degeni-packages packages. For @link extraction the following two files are important:

• https://github.com/ReactiveX/rxjs/blob/86cce743334cf1b05f2a9f2ad182452aa3785a6e/docs_app/tools/transforms/links-package/inline-tag-defs/link.js
• https://github.com/ReactiveX/rxjs/blob/86cce743334cf1b05f2a9f2ad182452aa3785a6e/docs_app/tools/transforms/links-package/services/getLinkInfo.js

There is a RegExp in the link.js file

rxjs/docs_app/tools/transforms/links-package/inline-tag-defs/link.js

Line 1 in 86cce74

var INLINE_LINK = /(\S+)(?:\s+([\s\S]+))?/;

for parsing @link content which is basically of the form ${url} ${link name}. So that is the reason why this works for the documentation home page.

There is however another issue that is related to how @links are parsed and shown in IDEs. As there is no standard for JS/TS documentation each IDE or Editor seems to ship its own slightly different version for @link processing and parsing. These are the ones I know of but this list is not exhaustive:

• VSCode: There has been a recent addition to better support @link processing and display in TypeScript which then also benefits VSCode. It should be included in TS 4.3 Editor support for link tag microsoft/TypeScript#41877
• TSDoc: TSDoc is an effort to add a standard for TS documentation. The @link proposal is still in discussion (There are a number of tricky issues regarding this simple tag RFC: Syntax for "declaration references" (hyperlinks) microsoft/tsdoc#9). Currently it seems that TSDoc is used by APIExtractor to generate documentation (similar to dgeni)

So long story short: I would like to look into the recent addition of @link parsing to TS and its compatibility or incompatibility with TSDoc a little closer. So for now I am fine if this PR still stays open a little longer. I don't exactly know when I will have time to dig a little deeper into all of this as I am not too familiar with dgeni or the TSDoc project.

[jakovljevic-mladen]

Actually, Angular has so many examples of these links; one of them:

https://github.com/angular/angular/blob/cd252b99fe04bcde2a31e2314f9eb920b2d38e49/packages/forms/src/directives/reactive_directives/form_group_name.ts#L47

This is how it looks like in the docs:
https://angular.io/api/forms/FormGroupName#access-individual-controls-in-the-group

[cartant]

@tmair Thanks for the super-thorough comment. 👍