1324310 - AddonManager documentation broken due to missing AMInterface template

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: Add-ons, defect)

Description

[Kris Maglione [:kmag]]

I don't know when this template disappeared, but it looks like it may have disappeared a while ago, and only became a problem when I updated the page and invalidated its cached content.

Comment 1

[Kris Maglione [:kmag]]

The last archive.org snapshot is in 2013: http://web.archive.org/web/20130502193707/https://developer.mozilla.org/en-US/docs/Template:AMInterface

Comment 3

[Kris Maglione [:kmag]]

Will, maybe you can have a look at this?

Comment 4

[John Whitlock [:jwhitlock]]

The template was deleted on June 11, 2016 by fscholz, with a reason of 'unused'. That may imply that our search database didn't fully index the existing documents.  Since then, I've purged the deleted documents, so we probably don't have the ability to restore it.

I think the next step is replace the existing uses of AMTemplate (it appears to just be a link wrapped in a <code> element), or add it to the kumascript repo.

Comment 5

[Will Bamberg [:wbamberg]]

Thanks for figuring that out John. Since this is only used in a few pages, let's replace it with links.

Comment 6

[Leif-AMO]

If I understand the options proposed:

First would be to change all instances of "{{ AMInterface }}" on the site (/(lang)/docs/Add-ons/Add-on_Manager, possibly others?), to <code><a href ...>...</a></code> literals?  Not sure how to do that for arbitrary languages, or how to find all pages using AMInterface, but if someone knows how, I could modify the links.

Second would be to implement AMInterface template in Kumascript (https://github.com/mozilla/kumascript)?  I'm not at all familiar with that codebase, but it seems like a simple copy/paste from the web archive, into https://github.com/mozilla/kumascript/blob/master/macros/AMInterface.ejs would be a start, and inject any references to AMInterface elsewhere, rebuild, retest, etc?

Comment 7

[Will Bamberg [:wbamberg]]

(In reply to Leif-AMO from comment #6)
> If I understand the options proposed:

I think you do.

> First would be to change all instances of "{{ AMInterface }}" on the site
> (/(lang)/docs/Add-ons/Add-on_Manager, possibly others?), to <code><a href
> ...>...</a></code> literals?  Not sure how to do that for arbitrary
> languages, or how to find all pages using AMInterface, but if someone knows
> how, I could modify the links.

Yes, exactly. Here: https://developer.mozilla.org/en-US/docs/User:wbamberg/all-addons-pages I've got a tree of all pages under /Add-ons. It's very likely that all pages using AMInterface are under Add-on Manager or Add-on Repository, and you can see that there are only a few pages there.

I just fixed a couple of pages using this approach.

To find translations, you can hover over "Languages" just left of "Edit" and it'll tell you which other languages the page has been translated into.

> Second would be to implement AMInterface template in Kumascript
> (https://github.com/mozilla/kumascript)?  I'm not at all familiar with that
> codebase, but it seems like a simple copy/paste from the web archive, into
> https://github.com/mozilla/kumascript/blob/master/macros/AMInterface.ejs
> would be a start, and inject any references to AMInterface elsewhere,
> rebuild, retest, etc?

Also yes (I'm not sure what "inject any references to AMInterface elsewhere" means though).

I suppose this option would be more robust, in case there are other pages we don't know about that use AMInterface.

On the whole I'd probably prefer these kinds of very special-purpose macros to go away, but I'd be OK with either approach. If you'd like to fix this using either approach, that would be great!

Comment 8

[Leif-AMO]

What I meant, was not only to implement the script itself (*.ejs file), but an awareness that sometimes it needs to be referenced in test scripts, build scripts, etc, the specifics of which I am not familiar with kumascript.  A cursory review, I don't see any such references.  The scripts holding the templates seem self-contained.

I admit this is a fairly narrow usage for this script.  But it does seem preferable to change one small macro than hunt for pages and translations and instances per page.  The benefit, if at some point the link style was to be changed, perhaps to remove the <code> tag, then it's easier to change one macro than a few dozen locations scattered across several files.

I was wondering about a 3rd option, if there are other pages that use a similar template, if perhaps a more generic solution could be devised to handle more cases.  In other words, give the script a justification by finding a way to make the idea more useful.  Otherwise get rid of it, if it causes as much maintenance work as it saves.

But I do like that it potentially saves more work in the future, for instance if the page is translated to more languages.

Comment 9

[Will Bamberg [:wbamberg]]

(In reply to Leif-AMO from comment #8)
> A cursory review, I don't see any such references.

I don't think that there are any such references. The current docs for contributing to KumaScript macros are here: https://github.com/mozilla/kumascript.

> I admit this is a fairly narrow usage for this script.  But it does seem
> preferable to change one small macro than hunt for pages and translations
> and instances per page.  The benefit, if at some point the link style was to
> be changed, perhaps to remove the <code> tag, then it's easier to change one
> macro than a few dozen locations scattered across several files.

In theory, but in practice that's unlikely to happen.

> I was wondering about a 3rd option, if there are other pages that use a
> similar template, if perhaps a more generic solution could be devised to
> handle more cases.

There are indeed many similar macros, and we would love to consolidate them. But it's a big project to do so, and not a project that we're currently contemplating for 2017.

I understand that macros are useful sometimes. I'm not convinced this is one of those times. This is a small, Firefox-internal API, that should already be deprecated for add-ons. It more properly belongs under the other JSM pages (https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules) than under Add-ons, and the other JSM docs don't use macros in this way.

As I said: if you'd like to fix this, I'd be very happy for you to use either approach. If I'm doing it, I'd remove the macro calls and replace them with links.

Comment 10

[Leif-AMO]

(In reply to Will Bamberg [:wbamberg] from comment #9)
> I don't think that there are any such references. The current docs for
> contributing to KumaScript macros are here:
> https://github.com/mozilla/kumascript.

Found previously, and the kuma project.  Understood.

> There are indeed many similar macros, and we would love to consolidate them.
> But it's a big project to do so, and not a project that we're currently
> contemplating for 2017.

Will keep an eye out for it if I'm around and still interested when it happens.  Or just play with a local copy of MDN, if motivated to familiarize myself further.

> I understand that macros are useful sometimes. I'm not convinced this is one
> of those times.

Points taken and reasonable.
 
> As I said: if you'd like to fix this, I'd be very happy for you to use
> either approach. If I'm doing it, I'd remove the macro calls and replace
> them with links.

I'll work on the link replacement momentarily.  My focus was elsewhere yesterday, today it is here.

Comment 11

[Kris Maglione [:kmag]]

It would be nice if we could replace this with a more general macro for platform APIs, so we could do something like ToolkitInterface("AddonManager.getAddonById()") and have it link to the right place, and with the right style.

Comment 12

[Leif-AMO]

(In reply to Kris Maglione [:kmag] from comment #11)
> ToolkitInterface("AddonManager.getAddonById()") and have it link to the
> right place, and with the right style.

Would that need to handle arbitrary dots?  i.e.

KumaScript template call:

{{ ToolkitInterface( "BaseAPI.branch1.branch2.getLeaf()" ) }}

Creates resultant HTML:

[If all methods have their own page]

<code><a href="/LANG/BaseAPI/branch1/branch2/getLeaf" title="BaseAPI.branch1.branch2.getLeaf()">BaseAPI.branch1.branch2.getLeaf()</a></code>

[Or, if all methods on one page]

<code><a href="/LANG/Base/branch1/branch2#getLeaf" title="Base.branch1.branch2.getLeaf()">Base.branch1.branch2.getLeaf()</a></code>

Actual (until recently) live example:

<code><a href="/en-US/Add-ons/Add-on_Manager/AddonManager#getInstallForURL()">getInstallForURL()</a></code>

And what about style?

Or, any other arbitrary document structure?

Noticed some of the older non-English translations had a `<a class="new" ...`  reference, which made the link a dark red.  Most pages don't seem have this on any links, but the examples used a red color fr object names, and this turned the link red inside code examples (<pre class="brush: js">).  Although the <code></code> tags seem superfluous, they actually seem to be necessary to force the <a> link to be recognized inside <pre class="brush: js"> tags.

Comment 13

[Kris Maglione [:kmag]]

(In reply to Leif-AMO from comment #12)
> (In reply to Kris Maglione [:kmag] from comment #11)
> > ToolkitInterface("AddonManager.getAddonById()") and have it link to the
> > right place, and with the right style.
>
> Would that need to handle arbitrary dots?  i.e.
>
> KumaScript template call:
>
> {{ ToolkitInterface( "BaseAPI.branch1.branch2.getLeaf()" ) }}

Probably not. The existing macros along these lines only support 0 or 1 dots.
When there's a dot included, it's always preceded by an interface name or a
global object, so "AddonManager.addInstallListener()", or "AddonInstall", or
"AddonInstall.onEnabled()". Anything with more parts would need to have the
parts defined as another interface.

Comment 14

[Leif-AMO]

Update: Still picking away at these as I have time throughout the day.  I know the pages are low priority, but it's a good place to get some practice and learn my way around without blowing up heavily used stuff.

Regarding a generic "ToolkitInterface" macro, I was thinking of this problem and I've thus far come across 3 macros (including the phantom AMInterface) which do a similar thing.  There may be more.  The only essential difference seems to be the name of the macro, the base URI of documentation, and possibly trivial stylings.

Interface => /<lang>/docs/Mozilla/Tech/XPCOM/Reference/Interface/
jsxref => /<lang>/docs/Web/JavaScript/Reference/Global_Objects/
AMInterface => /<lang>/docs/Addons/Add-on_Manager/

So a generic macro would need to map calls to respective paths, by keeping some sort of reference table (hash or array lookups etc), e.g.:

"nsILoadGroup" and "nsIFile" to /<lang>/docs/Mozilla/Tech/XPCOM/Reference/Interface/
"Error" to /<lang>/docs/Web/JavaScript/Reference/Global_Objects/
"Addon" to /<lang>/docs/Addons/Add-on_Manager/

Multiple unique terms can resolve to the same path, that is good.  But terms like "Error" are generic may not be unique to one location, so I'm not sure how that would be handled.

Perhaps a 3rd parameter is necessary to specify path, either by path fragment, or a simple short but unique identifier.

ToolkitReference( path_fragment_or_unique_id, object, property_or_method )

ToolkitReference( "jsx", "Error" ) // 3rd optional parameter null
ToolkitReference( "xpcom", "nsIFile" )
ToolkitReference( "aom", "Addon", "findUpdates" )

Essentially, instead of coding path info in the name of a unique macro, move it to the first parameter.  Once inside the macro, once the API is identified, then the path, custom stylings, consideration of optional 3rd parameter, etc, could be applied.

I realize the implementation may not be scheduled for 2017, but thought I'd offer a potential remedy for future reference, and see what feedback that generates.  Thanks.

Comment 15

[Will Bamberg [:wbamberg]]

(In reply to Leif-AMO from comment #14)
> Update: Still picking away at these as I have time throughout the day.  I
> know the pages are low priority, but it's a good place to get some practice
> and learn my way around without blowing up heavily used stuff.

It's awesome work, thanks for doing this.

> Regarding a generic "ToolkitInterface" macro

/*
The backstory (in case you're wondering "why is it like this?"): until a couple of months ago, all KumaScript macros were stored somewhere in Kuma's database and were edited as Wiki pages, that just lived in a completely flat hierarchy, like this: https://developer.mozilla.org/en-US/docs/Template:WebExtBrowserCompat, https://developer.mozilla.org/en-US/docs/Template:jsxref, etc . Editing them meant editing the macro's page, and saving it published it live into production. We didn't have any defined review process or any tests, and since it was hard to reason about the macros we had, there was a lot of code duplication.

In November we moved them into the GitHub repo, and this opens up possibilities about managing them better, including dealing with the code duplication issue. We're excited about getting into this work. But it's still a big task with a lot of legacy use.
*/

One thing to say about the proposal is that there are a lot of technology areas on MDN. They broadly fall into one of two categories:

* docs for Mozilla internal technologies: things that are useful if you are a Mozilla developer (or an old-school add-on developer, since old-school add-ons get access to a similar set of nonstandard JS APIs). That includes AddonManager and other JSMs (https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules), as well as XPCOM (https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM).

* "open web" docs: standards-based browser-agnostic reference, like JavaScript or CSS or WebExtensions.

The MDN team is much more focused on the open web docs than on the Mozilla internal docs.

So one question is, is the proposal intended to cover xref macros used in the open web docs (I think it should!). If so, then "ToolkitReference" is probably not a good name. Kris's comment 11 is I think only about Mozilla's internal APIs. But in the context of the open web docs, then "Toolkit" doesn't really mean anything.

I guess the general approach here could be:
1) write a new xref macro that can replace all the existing ones
2) update the old xref macros to call the new one
3) update the actual pages to call the new macro
4) delete the old xref macros

(3) in particular seems like a huge task, but one nice thing is that you'd get a lot of benefits by just doing (1) and (2), and you could do (3) gradually. 

I think the best place to discuss this proposal, though, is not this bug, but as a separate issue in the kumascript repo: https://github.com/mozilla/kumascript/issues. Would you mind filing an issue there, with your proposal?

Comment 16

[Leif-AMO]

(In reply to Will Bamberg [:wbamberg] from comment #15)
> I think the best place to discuss this proposal, though, is not this bug,
> but as a separate issue in the kumascript repo:
> https://github.com/mozilla/kumascript/issues. Would you mind filing an issue
> there, with your proposal?

I'll copy your previous message as a starting point for issue discussion, thanks for directing me there.  May go silent here for a few days.  Assume I am still picking at these, doing a conversion to manual links, and generally cleaning up docs, on occasion filing bugs for other misbehaving macros, etc.

Comment 17

[Leif-AMO]

Created GitHub issue in mozilla repo's KumaScript project.

https://github.com/mozilla/kumascript/issues/84

Comment 18

[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/.