Should we use "Returns" in the description of a property?

[wbamberg]

When we document a property of an interface, should we say, for example:

## Value

A string representing the blah-di-blah...

or:

## Value

Returns a string representing the blah-di-blah...

To me the second is awkward and mystifying. It's a property, not a method.

I raised this before and had feedback that it's used as an indicator that the property is read only. However to me that's quite an indirect way of indicating this, especially since we also say "read only" in the property's description.

I'm not advocating that we go and update all the property pages that use "returns", just to have a guideline for reviewers in the future. If "returns" is actually better for read-only properties, we should say that. Currently we say nothing:

Value

Include a description of the property's value, including data type and what it represents.

[OnkarRuikar]

From the discussion so far some of us want to indicate if the property has been implemented using JS getter or setter. But I think we shouldn't burden readers about the internal implementation and we should go with A string representing the blah-di-blah....

But if we want to address getter and setter then we could have something like:
read only: A string representing ...
write only: Returns a string representing...
read-write: Sets or returns a string representing...
This increases the burden on page author to double check what exactly is the property read only, write only, or read-write. And we also have the read-only badge to indicate that.

[teoli2003]

No strong feeling here but:

• "A string representing…" looks simple and clear enough to me
• We shouldn't use "Returns …" if it is not a read-only property.

read-only is also mentioned in the first sentence.

Finally, are there write-only properties?

[estelle]

This discussion was discussed synchronously during the #writing-docs meeting held on April 16, 2024. Here are the (slightly edited for clarity) minutes from that portion of the meeting:

Question: Should we use "Returns" in the description of a property?

• No. If it’s not a method, it doesn’t "return".
• MDN Writing Guidelines say nothing. We should add it to the template in the writing guidelines.
• You can write and read the property, so it doesn’t just return. The word returns sounds like it’s only a getter.

ACTION ITEM: @wbamberg will file a PR for the API property template in the writing guidelines

Note: not using "returns" as a "guideline" not a "rule". We don't need to do an update of all existing content.