BCD: Interpretation assists

MDN
#1

I’ve been thinking lately about ways we could provide small amounts of added data that would make the information we already provide easier to interpret in ever more useful ways.

Feature/subfeature type guidance

First, I think we ought to add a type or kind field to features that would let us specify the kind of feature that’s being described. This field would take values such as these (in the API JSON; the appropriate values would need to be decided, if needed at all, for the others):

  • For top-level features:
    • interface
    • typedef
    • enum
    • class
    • constant
  • For sub-features:
    • method
    • property
    • constant
    • constructor

This would let us avoid having to do things like manually add description fields to provide proper styling for entries in compatibility tables (proper styling that may be MDN-specific).

Using substitutions to avoid MDN-specific styling

Currently, when we do things like write information in the note field, we tend to do things like embed HTML to do things like include links, style the name of interfaces and methods, and so forth. We could avoid this by adding the ability to use some simple substitutions. The client making use of the data would then apply the appropriate substitution, optionally adding appropriate styles.

This way, MDN could add <code>...</code> around things like we do, while other BCD clients could use their preferred styling.

More importantly, we could use this in concert with the first idea (adding types to BCD entries) to automatically add parentheses to function names and such at the same time, to get the presentation just the way we want it, while other clients, again, could choose to do so or not.

Even better, this makes it relatively trivial for clients to change up their style rules over time, because the substitutions would be getting done somewhere other than in the content itself, so they’d simple re-render content after updating their code and the output would all get updated accordingly.

1 Like
#2

Hey Sheppy, thanks for writing this proposal down. I know there’s been discussions about type fields from time to time, but I don’t think there are any open issues with a proposal.

The type field proposal seems likely to be met with little controversy, though perhaps there will be some nitpicking over type names. For my part, I’d like to see any PR that adds types not obligate contributors to recapitulate the data hierarchy (e.g., I’d expect index.js to automatically add a property type to top-level features in css.properties).

The substitutions proposal is somewhat unclear to me. Could you perhaps illustrate with a couple of examples on how you’d expect notes or description fields to change with substitutions? I hadn’t really considered this before; I always understood <code> tags in descriptions and notes as serving a semantic function as much as a stylistic one.

Thank you again for starting this discussion.

1 Like
#3

So, about the substitutions… here are some conceptual examples (the names and syntax are of course up for debate if we ever decided to investigate this further).

Example 1

Let’s say you have a note like this for the property SpaghettiDinner.sauceType:

"note": "The <code><a href=\"https://developer.mozilla.org/en-US/docs/Web/API/SpaghettiDinner\">SpaghettiDinner</a></code> interface is only available in Firefox 36 and later. <code>SpaghettiDinner</code> was enabled by default in Firefox 39.

Using substitutions, this could instead be written as:

"note": "The ${link:interface} interface is only available in Firefox 36 and later. ${interface} was enabled by default in Firefox 39.

This would allow MDN to create an internal link for the interface, instead of using a full URL, and we could apply the styling we wish to use. Perhaps we want to start using classes to identify the type of item the <code> element is being used on. We could update MDN’s interpretation of the substitutions and start outputing:

"note": "The <code class="code-interface-name"><a href=\"/en-US/docs/Web/API/SpaghettiDinner\">SpaghettiDinner</a></code> interface is only available in Firefox 36 and later. <code class="code-interface-name">SpaghettiDinner</code> was enabled by default in Firefox 39.

Example 2

Looking at the same imaginary interface again, we have data for a method, taste():

      "SpaghettiDinner": {
        "__compat": {
          "mdn_url": "${link:interface}",
...
          "support": {
            "firefox": {
              "version_added": "45"
            },
...
      "taste": {
        "__compat": {
          "mdn_url": "${link:interface/self}",
          "support": {
            "firefox": {
              "version_added": "47",
              "notes": "Although ${link:interface} was never prefixed, this property was prefixed as ${prefixed:self} until Firefox 49."
            },

Stuff like that.

#4

Thanks for clarifying, @sheppy! The substitutions proposal seems quite a bit more ambitious than adding ordinary string data. I’d expect that to require much more convincing (for example, current consumers of BCD would have to parse and handle substitutions, something they don’t have to do today—we’d need a strong case to ask consumers to take that on).

But since that seems to depend on types data, I’d start there, if I were you. The next logical step would be an issue or PR on BCD that shows how the schema would change, what the expected uses for that data would be, and so on. This issue and discussion that followed might help serve as a model for getting an idea like this through: https://github.com/mdn/browser-compat-data/issues/3366

1 Like