W3C WebDriver spec links not working for a lot of pages

[garg3133]

There are a lot of pages in the API docs which have an invalid link in the "W3C WebDriver spec" section. See this page for one such example.

• [x] We need to fix all such invalid links in the API docs. This can ideally be fixed by adding the WebDriver spec doc link as the prefix if the link does not start with http. This change only needs to be made at a single place in this repo where we convert the JSDoc tags to HTML.
• [ ] Additionally, all the links related to W3C should be placed in the @link tag in JSDoc throughout the Nightwatch APIs (present in nightwatchjs/nightwatch repo), and all other links should be put in the @see tag.

[ParmarKrishna]

I understood the issue here, and I am working on it.

[ParmarKrishna]

all the links related to W3C should be placed in the @link tag in JSDoc throughout the Nightwatch APIs (present in nightwatchjs/nightwatch repo), and all other links should be put in the @see tag.

Regarding this, there are two versions of @link tag found in the files. For example, lib/api/client-commands/document/source.js has entire link (such as, @link https://www.w3.org/TR/webdriver#getting-page-source) in the tag, where as other files such as, lib/api/client-commands/document/executeAsyncScript.js has only /#execute-async-script in the tag.

Hence, should link tag contain only #references-page or entire link as shown above? Additionally, the URL is also incorrect.

[garg3133]

The @link tag can contain links in /#execute-async-script format only, no need to specify complete URLs.

There are also some pages where the @link tag is incorrect (ex. the link present in element.clickAndHold page doesn't lead to anywhere), we'd need to fix those as well (or remove them if there's no such section and instead add a selenium doc reference).

Also, if there are some non-webdriver spec related links present in the @link tag, we would need to move them to @see tag. Similarly, if there are some webdriver spec related links present in @see tag, we'd move them to @link tag.

[ParmarKrishna]

okay. understood.

[Shubhdeep02]

hey @garg3133 is this issue also fixed??

[garg3133]

@Shubhdeep02 The second task of this issue is not completely fixed yet. A few links were fixed here though: https://github.com/nightwatchjs/nightwatch/pull/4166.

[Shubhdeep02]

@garg I have been trying to figure out the Nightwatch APIs JSDoc but it seems to me that all the links related to W3C are already placed in the @link tag or am i missing something?

[garg3133]

@Shubhdeep02 The issue here is that all the links related to W3C should be present under the @link tag and the @link tag should only contain the W3C links (usually starts with /# in JSDoc) and no other links. There are a few places where some other link is present in the @link tag, those should either be deleted (in case they are starting with /session) or moved to the @see tag.

Additionally, we need to ensure that all the W3C WebDriver spec links on the Nightwatch API docs website work and that they take you to the correct section on the target page (when going through the W3C links in the Nightwatch repository, just type the name of the file containing that link in the left navigation search bar of Nightwatch API docs and cross-check if the W3C link on the resultant page actually work).

The same thing needs to be done for the @see tag -- they should either contain the plain command names (like cookies.accept, session, etc.) or HTTP links other than the W3C spec links. Additionally, need to ensure that those links actually work on the actual website.