Improve the comments on various types

[iwahbe]

I'm trying for a more unified and higher quality documentation story, with the eventual goal to merge 👇, mandating comments on all exported functions.

 .golangci.yaml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.golangci.yaml b/.golangci.yaml
index b55ac7c..f75ffbd 100644
--- a/.golangci.yaml
+++ b/.golangci.yaml
@@ -3,6 +3,7 @@ run:
 issues:
   # Enable checking the by default skipped "examples" dirs
   exclude-dirs-use-default: false
+  exclude-use-default: false
   exclude-dirs:
     - vendor$
     - third_party$
@@ -28,4 +29,5 @@ linters:
     - staticcheck
     - stylecheck
     - unused
+    - godot
   disable:

[iwahbe]

Nice! The enforced period at the end of every internal comment seems a bit overzealous but not a big deal.

I'm happy to leave that off for now. I have scoped the revive style lint to non-internal code. Preferably, we would scope all of these comment lints to user facing code.

The only thing I noticed is that you occasionally used Markdown backticks to surround code. Can/should we do standardize this and do it always or never?

We should standardize. It seems like the go language itself doesn't use backticks, so we should do the same.

// The real built-in function returns the real part of the complex number c.
// The return value will be floating point type corresponding to the type of c.
func real(c ComplexType) FloatType

[iwahbe]

It looks like backticks are not even rendered by godoc: