Doc comments are often written in the imperative mood

[lilyball]

Version
1.8.1, 1.10.1

Description
tokio's doc comments are written in a mixture of the indicative mood and imperative mood. They should all be in the indicative mood (e.g. "Returns foo"), to match the stdlib and the standard rustdoc conventions.

For example, tokio::runtime::Runtime uses the imperative mood for all of its method comments, e.g.:

pub fn handle(&self) -> &Handle
Return a handle to the runtime’s spawner.

The returned handle can be used to spawn tasks that run on this runtime, and can be cloned to allow moving the Handle to other threads.

tokio::runtime::Handle uses a mixture of imperative and indicative moods:

pub fn enter(&self) -> EnterGuard<'_>
Enter the runtime context. This allows you to construct types that must have an executor available on creation such as Sleep or TcpStream. It will also allow you to call methods such as tokio::spawn.

pub fn current() -> Self
Returns a Handle view over the currently running Runtime

Note how Handle::enter is imperative, but Handle::current is indicative (also note how Handle::current is missing the trailing period).

I mostly just look at Runtime and Handle, so I'm not sure how prevalent this issue is across the rest of the API.

[Darksonn]

PRs that make this type of change is fine with me. I'm sure it's very prevalent - we have not done anything to keep it consistent in this area.

[antglb]

I wouldn't mind working on this if no one else is.