Improve metadata specification introducded in PR #1583

In #1583 you (@felipesanches ) introduced new metadata arguments to fontbakery.callable.FontBakeryCheck. We need better specifications of the expected data types and use cases. Inline comments are in general fine, BUT the other arguments are already described in the docstring of the Class.

Please move the specs and flesh out:

• Move the description comments into the docstring of FontBakeryCheck.
• rationale what is the difference to documentation how should each be used (this would be sth. I’d just put into documentation)
• affects please add an example, maybe define commonly needed words, so that we don’t end up with Windows, windows and win meaning the same thing or describe how to derive a key here.
• affects specify the format of the affected versions range or mark it explicitly as a TODO.
• affects Make it a tuple of tuples, we don’t want to change it, a tuple makes this semantically more clear.
• affects In the first test that uses the spec: ('Windows', 'unspecified') The second value should be None if unknown (see above: specify affected versions range.)
• example_failures how is this formatted and expected to be used, I can’t deduce from the current description. Why can’t this be in rationale or documentation? Maybe mark it explicitly as a TODO.
• In the first test that uses the spec, remove the line , example_failures = None. It’s optional and shouldn’t be used explicitly if it has no value.

[felipesanches]

it seems we’re suggesting the same thing 😄

[graphicore]

LOL