Change to comply with documentation standards

[adursun]

Some verbs didn't follow documentation standards written here.

[javiereguiluz]

I'm not strongly against this change ... but I can't find where this is recommended in the link you shared. Besides, we use this style in hundreds of examples across the doc, so it'd be almost impossible to fix everything.

Now a personal opinion: I like the current style because it's easier to understand for me:

• return a string ... looks like: "you should return a string here"
• returns a string ... looks like: "the result of executing this code is that a string is returned"

[adursun]

As you said, both styles are used in the documentation. There are inconsistencies, especially here, but I am not sure it is worth changing all of them.

In my opinion, the correct style depends on the communication between the documentation and the reader. If the documentation tells the reader what to do, you return version should be used. If the documentation describes methods or statements to the reader, it returns version should be used.

[javiereguiluz]

OK, so we should fix this inconsistency. I propose to use everywhere returns a string... instead of return a string... What do other doc maintainers think? @wouterj @xabbuh Thanks!

Note: whatever the decision, we should make those changes in 2.7 branch (the oldest maintained branch) and then we'll merge fixes up to the other branches. Thanks!

[xabbuh]

I prefer the previous style. @javiereguiluz explained that quite well. This comment explains what the code below does, not what you as a developer should do.

[javiereguiluz]

Given the comments from the doc maintainers, we've decided to make code comments consistent. We've created #9194 to do that, so we're closing this one. @adursun even if your pull request wasn't merged, it helped us to find this inconsistency and fix it. Thank you!