Audit stdlib documentation

[vkleen]

For now, a quick pass over the stdlib documentation for consistency and typos.

[yannham]

So I had to stop at some point with suggestions, there were just too many lines 😓 but I think we should be consistent over:

• verbal forms. If we start some documentation with Returns, then all verbs describing the action of a function should use the s form.
• indentation. I believe there are cases where the code is indented with respect to the block fences, but not everywhere. Also, I don't think it's standard practice, it feels like it should start the the same level as the block, as I don't see much usefulness in having the whole code block indented by one level from the leftmost boundary.

[vkleen]

So I had to stop at some point with suggestions, there were just too many lines

No worries 😆 I'll find all the lines.

* verbal forms. If we start some documentation with `Returns`, then all verbs describing the action of a function should use the `s` form.

👍

* indentation. I believe there are cases where the code is indented with respect to the block fences, but not everywhere. Also, I don't think it's standard practice, it feels like it should start the the same level as the block, as I don't see much usefulness in having the whole code block indented by one level from the leftmost boundary.

It always felt to me like a fenced in block acts like a new scope, and as such deserves to be indentend. But that may indeed just be me.

I'll make another pass over all of it, remove indents from code block and pay attention to the verbal forms.

[yannham]

Sorry if my suggestions sounded a bit too affirmative 😅 I'm not necessarily pushing for the trailing s, and maybe there's a case to be made for indenting code inside a fenced block? Let met quickly check if I can find style advises online. But the hard constraint is that we're consistent.

[yannham]

So with respect to indenting code, it seems like GitHub's documentation and W3C's documentation show examples where the code isn't indented indeed (starts at the same indentation as the fence).

[vkleen]

No worries 😺 As you can tell from me preferring the trailing "s" on one day and preferring the other form on the next, I don't have a stable preference on the matter. But with you we have a slight bias towards trailing "s", so I'm taking that.

[yannham]

Oh my, I've merged #1198, which might make this rebase quite difficult. Might be simpler in the end to revert, merge this one, and reformat afterward? Or do you think it'll be manageable?