Should we use return or returns in Doxygen documentation?

[Panquesito7]

Originally asked by @realstealthninja in #2441 (comment).

[realstealthninja]

To me I'd say returns as it's the way we read i.e this function returns this variable which does that

[ewd00010]

I think returns for single possible variables since it works like rsn said, 'its the way we read'.
However, for multiple potential variables I prefer return because it works similar to a switch case IE

return x if that or return y if that or return z if that

#2464 has examples of both in the way I am thinking

[realstealthninja]

#2464 has a case with 3 @ return tags i wonder if multiple returns as rendered if so it would make things a whole lot cleaner

@returns y if case w
@returns x if case q
@returns z if case r

[ewd00010]

Thinking about it more, both versions make complete sense, it depends more on the context of how your think when you read the comment.
For example:

"if this function is run, you return y if case w, x if case q or z if case r"

Its equally correct to say:

"if this function is run, it returns y if case w, x if case q or z if case r"

The main difference between the two, in this case, is who/what is returning the value? is it a programmers intention or machine intention? I think the answer is dependant on the person and how they communicate what a section of code is meant to do.
Therefore, my answer is still both, left up to the programmer on what feels natural.
Although, what if someone did, for the same function:

@returns y if case w
@return x if case q
@returns z if case r

That seems a bit unclean. maybe enforce keeping return or returns the same for each individual function.

[realstealthninja]

Thinking about this i think we should just enforce it on a case to case basis. I.e what ever the developer has used more must be the only one used in the file