Documenting interfaces with inheritance

MDN
#1

I bring this up now and then, but I feel that we need to figure out a proper solution for this. We are continuing to rack up more and more documentation where there are interfaces that are based on other interfaces, and we are either cross-linking, leading to some confusion when the parent interface is, say, read-only while the derived interface is not (like DOMPointReadOnly being the base class for DOMPoint). If you reuse DOMPointReadOnly content for DOMPoint, the text about being read-only is misleading (along with, of course, any uses of the base interface’s name).

I thought about creating a macro that would insert the name of the interface you’re reading about, but the macro is already run when the content is inserted into the page, so embedded content would not pick up the inherited class’s name still. Then I had a bit of an idea.

What about something like this: we create a new {{InheritPage}} macro that would embed the content from the specified page, but would do it indirectly. Any tokens shown below are just placeholders.

  1. Collect the output from the existing {{page}} macro into a variable.
  2. Find <code> blocks that have the class base-interface and replace the interface name within (the text before the first period) with the name of the interface portion of the current page’s slug. If the immediate parent or immediate child of the <code> block is an <a> element, correct its href, replacing the base interface name with the current interface’s name.
  3. Find any blocks with the class base-interface-only and remove them entirely.
  4. Return the resulting transformed output.

This would let us craft API documentation using special classes to allow derived classes to transclude the content and have the text match the derived class’s names, as well as leave out any text that’s specific to the base class.

The macro could also offer the ability to automatically link to the corresponding base class and/or member of the base class.

This could all be done with no new code on the platform side, other than the addition of support for a couple of new classes.

This seems like it could be an interesting experiment to me.

Sheppy

#2

You are right that we need to think up a better way to do all this. We’ve talked a couple of times in the past about running a project to figure this out, but not actually got round to it.

I see what you are saying here, but I get the feeling that this is over-complicating things somewhat. Or maybe you are just suggesting a cleverer solution to what I was thinking about in a more manual sense. Let’s talk this through and test it out.

So, the main trouble with our API docs is that they are confusing in terms of what objects people will actually search for. For example, strictly speaking setInterval() is hanging off WindowOrWorkerGlobalScope, so that’s how we documented it.

But that’s an implementation detail. No web developer will actually touch WindowOrWorkerGlobalScope — many won’t even know it exists — so it will confuse web developers searching for say Window.setInterval(), which is one of the places they’ll actually find it.

This begs the question — why not just document setInterval() in the place where developers will actually find it, and not have it hanging off these confusing implementation mixins. This may result in us having to repeat pages, but it would be better for readers. We could include details of where the method is actually specified in a special box somewhere, for those that are interested…

1 Like
#3

Oh, forgot to say, if you are interested in trying to solve this problem and come up with a better solution, I am happy for you to spend some time on this. You have the experimentation day on the Friday after each sprint has ended, and then we could discuss having a time-boxed sprint task to look into this too.

#4

My concern about having duplicate content because of mixins being used in multiple places is, as always, that this inevitably risks one page becoming out-of-date because it gets forgotten about while doing other updates. We’ve got tons of places where that sort of thing has happened before.

I think before going that way, it’s worth trying to find a solution that lets us present the content in multiple places without having to write it twice.

Sheppy