Description
Documenting Go code is not fun. At all. That this benefits bad behaviour (:= no/little docs) is obvious.
-
It's not clear in which path your documentation will be available when running
godoc -http=:6060. I had to ask in slack to find out it'slocalhost:6060/pkg/github.com/foo/bar. I tried variations likelocalhost:6060/github.com/foo/barorlocalhost:6060/src/github.com/foo/barwhich obviously didn't work. -
Not having lists around is a real pain. How am I supposed to do something like this:
// Package warden decides if access requests should be allowed or denied. In a scientific taxonomy, the warden // is classified as a Policy Decision Point. The warden's primary goal is to implement `github.com/ory-am/hydra/firewall.Firewall`. // // This package is structured as follows: // * handler.go: A HTTP handler capable of validating access tokens. // * warden_http.go: A Go API using HTTP to validate access tokens. // * warden_local.go: A Go API using storage managers to validate access tokens. // * warden_test.go: Functional tests all of the above. -
It's not clear (to me) how to link from package a to package b and get that working in both godoc.org and with
godoc. -
I can't link text.
-
I can't load images.
-
There is no emphasis, I overread important things all the time because I'm too lazy concentrating on 10 lines of plain text when a simple Note: Don't do this if XYZ would most certainly solve that.
-
There is no instruction for inheritance, for example when implementing interfaces.
-
No inline
code. -
Probably more stuff (feel free to extend) but it's late and I'm tired and frustrated.
My suggestion is to have markdown or simple HTML, it would solve almost all of the problems above and a godoc command that actually does what it says: serving the docs of the cwd (and optionally other GOPATH packages too).
The issue number (it's a sign) gives me hope that documenting go code will get better soon.