Naming conventions for properties in returned objects

[queengooborg]

In #12840, @ddbeck and @foolip had been discussing a convention for the properties in the objects returned by certain methods. Quoting the conversation here:

Since we don't have a guideline, maybe this is an opportunity to start from scratch? How about returns_audioCapabilities_property with the idea being that we could have a convention for object properties (like this one), types (like returns_DOMMatrix_type), and values (like returns_undefined_value).

We should probably put the word return in the description too. Returns <code>audioCapabilities</code> property?

Originally posted by @ddbeck in #12840 (comment)

More ideas on these lines, to cut down on the wordiness:

• audioCapabilities in return value object
• audioCapabilities in returned object
• Returns object with audioCapabilities
• Returns object with audioCapabilities property

Originally posted by @ddbeck in #12840 (comment)

This made me think of the possibility of %parameter%_property_returned as the standard key, if that sounds nice?

[foolip]

Which description do you prefer? I think we can just take the entry name based on that.

"audioCapabilities in returned object" looks best to me, since multiple of those can co-exist without any sense that they are contradictory. Having both "Returns object with a" and "Returns object with b" sound more like they're exclusive.

[ddbeck]

"audioCapabilities in returned object" looks best to me

I think this is my preference too. I didn't consider the possible suggestion of exclusivity for the the "Returns object…" cases. I also prefer fewer words over more words, all other things being equal.