Fix function comments based on best practices from Effective Go

[Daanikus]

Every exported function in a program should have a doc comment. The first sentence should be a summary that starts with the name being declared.
From effective go.

I generated this with CodeLingo and I'm keen to get some feedback, but this is automated so feel free to close it and just say "opt out" to opt out of future CodeLingo outreach PRs.

[Daanikus]

Trying out some comment automation. I welcome any feedback as to how this could be improved. Thanks.

[vdobler]

This change has a some major drawbacks
First the Commit message: This CL is not a fix as the old code is not "broken". It should be named something like "adopt naming conventions" or "improve docs" or that like but not "fix".

Second: Go's documentation is made for humans. The convention mentioned in Effective Go are sensible but the proposed fix like "Rect: Draw rectangle of width w and ..." is worse than not starting the doc comment with the method name as is no longer is a sentence suitable for human consumption. A tiny change would make this nonsense a fine english sentence: "Rect draws rectangles of width w and ..."

I would merge a change to the doc comments if these are proper, sensible english sentences made for humans. But not some automatic-lets-please-brainless-tools change.

[Daanikus]

Hi @vdobler, I agree with this and we are working on improving the logic and not being so naive with our changes. Thanks for the feedback!