x/tools/cmd/godoc: request for richer formatting

[aeneasr]

Documenting Go code is not fun. At all. That this benefits bad behaviour (:= no/little docs) is obvious.

1. 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's localhost:6060/pkg/github.com/foo/bar. I tried variations like localhost:6060/github.com/foo/bar or localhost:6060/src/github.com/foo/bar which obviously didn't work.

2. 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.
   

3. 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.

4. I can't link text.

5. I can't load images.

6. 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.

7. There is no instruction for inheritance, for example when implementing interfaces.

8. No inline code.

9. 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.

[mdempsky]

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's localhost:6060/pkg/github.com/foo/bar.

Where do you generally go to find documentation for the standard library? E.g., if you wanted to look at documentation for "fmt"?

[aeneasr]

https://godoc.org/-/go and google

[mdempsky]

I see. Have you ever clicked the "Packages" link at the top of golang.org? If so, did you think to click it at the top of localhost:6060?

[bradfitz]

Dup of #7873, #13748, etc

Related: #4953

There are docs on Go's formatting rules at https://golang.org/pkg/go/doc/#ToHTML It's not much, but it's something. We've decided against HTML and Markdown in the past and I don't think anything has changed.

[aeneasr]

Yes I know it exists but for some reason I didn't notice the pkg part. This might look obvious to you, but to someone who doesn't know how things works it's not.

I can't think of any other documentation generator that is harder to use than:

1. start program
2. click the link that brings you to the package's documentation you're currently working on

With godoc, I have to:

1. start godoc
2. figure out which link is the right one (hint: it's not documents)
3. figure out that i have to append my package name after pkg
4. finally have some docs i can look at

[mdempsky]

Yes I know it exists but for some reason I didn't notice the pkg part.

I see. Thanks.

This might look obvious to you, but to someone who doesn't know how things works it's not.

I didn't mean to imply it should be. I was asking genuine questions to understand your thought process and why the packages list was not more discoverable.

[aeneasr]

Thanks for the link @bradfitz , I sumbled on it some time ago when randomly googling for the godoc syntax. It would be great to have that linked somewhere.

In all honesty, I think that the decision should be rethought, and it looks like I'm not the only one. The go toolchain is superb, why ship a, imho inferior, documentation tool? It doesn't have to be HTML or Markdown either, as long as it is possible to write better docs. If the decision changes, I would love to help with this.

I regularly catch myself avoiding godoc/golang.org and jump in the code instead, because I find it hard to read and find things. This has been the cause of me overlooking important details like closing response bodies ;)

[aeneasr]

I didn't mean to imply it should be. I was asking genuine questions to understand your thought process and why the packages list was not more discoverable.

Ok, I misinterpreted that, sorry :)

[rakyll]

It's not clear (to me) how to link from package a to package b

Always linking to the godoc.org partially solves the problem if it is not private. I don't seriously care clicking on the links during the development. But this is a pain for private repos without a private deployment of godoc.org.

Not having lists around is a real pain.

- prefixed lists are pretty common in the godoc from the stdlib and official package. I think they look pretty ok. Why doesn't it work?

- first item
- second item

No inline code.

You can escape code if you indent in godoc. Like DoSometing at https://godoc.org/golang.org/x/net/context. Are you mentioning another type of inlining?

[aeneasr]

Always linking to the godoc.org partially solves the problem if it is not private. I don't seriously care clicking on the links during the development. But this is a pain for private repos without a private deployment of godoc.org.

I do, because I want to know if my links work ;)

prefixed lists are pretty common in the godoc from the stdlib and official package. I think they look pretty ok. Why doesn't it work?

I don't know (well I do, because lists in godoc aren't lists, they are paragraphs which need a blank line):

// 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.

You can escape code if you indent in godoc. Like DoSometing at https://godoc.org/golang.org/x/net/context. Are you mentioning another type of inlining?

Yes, I'm talking about this type of inlining.

[aeneasr]

This is what a list (actually paragraphs) look like in godoc. Needless to say that this doesn't look pretty with larger text as identation is missing.

// 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.

---

On a side node: Thanks for being so super responsive all :)