mozilla / sphinx-js

Autodoc-style extraction into Sphinx for your JS project
https://pypi.python.org/pypi/sphinx-js/
MIT License
282 stars 81 forks source link

Support for JSDocs '@see {@link}' tag #173

Open xsjad0 opened 3 years ago

xsjad0 commented 3 years ago

With the @see tag it is only possible to reference internal documented objects like functions, classes, etc. Sphinx raises a warning if the referenced target could not be found and it just displays the non-clickable link.

/**
 * @see https://github.com/mozilla/sphinx-js
 */
bad_link_function() {}

image

image

To reference external resources we use the @see {@link} tag a lot from within our JavaScript code. So this pull request adds the functionality to support JSDocs @see {@link} syntax. Here's an example:

/**
 * @see {@link https://github.com/mozilla/sphinx-js}
 *
 * @returns {void}
 */
see_link_function() {}

image

The pull request covers the synonyms @linkcode and @linkplain though switching to a monospace font is not supported. JSDoc also provides different formats for the @link tag (see https://jsdoc.app/tags-inline-link.html). For now, I just covered the format @see {@link URL}.

Notable changes are