CSSSyntax - should we make the parameter mandatory?

[wbamberg]

The current implementation of CSSSyntax takes a parameter naming the thing for which we want to display formal syntax (e.g. margin, <color>, image()). But the param is optional: if it is omitted (which it almost always is) the macro tries to figure out what the thing is based on the current page.

Over in mdn/yari#6618 (comment) , @teoli2003 proposed that we stop doing this, and instead make the parameter mandatory.

I think this is a good idea, mostly because it makes things more explicit and less magical: you get what you ask for instead of having the code work out what you asked for. It's also less fragile and means we could change page titles or slugs without worrying about things like this.

[teoli2003]

So I have no problem having 0 parameters if we can get the data with 100% accuracy, like, say, from a YAML attribute.

I don't like when there are guesses or when it adds a dependency (like from Tags because we want to get rid of these, or – that's the most important– assuming a specific format in the Title, or in the Slug, or elsewheere). The more dependencies we have, the more complicated the platform becomes, and the more difficult it is to make changes: changing titles would mean changing the macros that depend on a specific format at the same time.

So the question is: can we achieve this? If so, fine. If not, I would prefer to have an explicit parameter (like we end doing for APIRef as we can't rely on Tags: (and don't want).

[wbamberg]

Well yes, I thought about this a bit. I agree, if we had a front matter item that we can use directly, then this is fine too. And if there were a few different places in a page where we wanted to use it, then it might make sense to do it like this (and maybe with CSSInfo there is actually more than one).

But I feel like we have to be really careful with defining front matter keys. We don't want a proliferation of half-thought-out keys in front matter. In this case what we really care about is that the string identifier maps to an entry in webref. AFAICT this means, for example, that for CSS functions it's <functionName()>, for properties it's propertyName, for data types it's <dataTypeName>. What would we call a key like this, and where would we use it apart from CSSSyntax?

For instance, would we tie it explicitly to webref, (e.g. "webref-identifier"), since that's actually the thing we care about?

[teoli2003]

Yep, I don't think we should use a front-matter key for this alone.

Having both browser-compat-data and webref-identifier is interesting, though.