1314662 - Create new API cross-reference link macro to replace/supplement domxref

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: Macros/Templates, defect)

Description

[Eric Shepherd [:sheppy]]

The {{domxref}} macro is one of our most-used macros, yet it has serious deficiencies. It's not as smart as it could be.

I propose a replacement, {{APIXref}}, which I describe below. It would live alongside {{domxref}}, which can either remain as-is or be stubbed over to {{APIXref}} if that turns out to be viable.

I propose APIXref have the following syntax:

{{APIXRef("[InterfaceName][.methodOrPropertyName[()]]", alternateText, anchor)}}

Its mission is as always to insert a link to the API reference page corresponding to the specified interface and/or property or method.

However, we can do a lot to make the output smarter:

* If no interface name is provided, look at the slug of the current page; if it's a page within an interface, assume that interface when building the destination URL.

* If no period is included, look at the first letter; if it's upper-case, look to see if an interface exists by that name; if so, create a link to that interface page. Otherwise, look at the current page's slug to get the interface to assume the link is meant for. If the current page isn't in an interface, this is an error state.

* If the link is to a member of an interface (that is, a property or method), and no parentheses are attached to the name, look at the page's tags to see if it's labeled as a method. If it is, add the parentheses to the link text.

* If the link is to a member of an interface, look at the destination page and see if it's a constructor. If so, always format it as a method link, and always as simply <code>InterfaceName()</code>.

* If the methodOrPropertyName includes parentheses, it's a method link, so remove them before generating the destination URL.

* If the InterfaceName is included but the current page is that interface, leave out the "InterfaceName." part from the link text, since it's unnecessary.

* If the specified API page is the same one the user is currently on, don't create a link at all. Just add the text.

* For the generated link, set the title attribute to the SEO summary or summary of the target page, using similar logic to the existing domxref macro.

* If the alternateText parameter is included, use it (without <code> wrapper) as the link text.

* If the anchor parameter is included, make the link target the specified text as an anchor by adding "#" + removeSpacesEtc(anchor) to the end of the target URL. removeSpacesEtc() is an appropriate algorithm that cleans the anchor to be sure it's usable - by removing special characters, turning spaces into underscores, etc.

There are probably even more ways to make this smarter.

This allows us much more freedom in using the macro, and is much more forgiving about the output.

Comment 1

[BMO Automation]

MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.