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

Open
opened this issue Aug 10, 2016 · 21 comments

Projects
None yet
9 participants

### aeneasr commented Aug 10, 2016 • edited

 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'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. 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.
Member

### mdempsky commented Aug 10, 2016

 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"?
Author

Member

### mdempsky commented Aug 10, 2016

 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?
Member

### bradfitz commented Aug 10, 2016

 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.

Author

### aeneasr commented Aug 10, 2016

 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: start program click the link that brings you to the package's documentation you're currently working on With godoc, I have to: start godoc figure out which link is the right one (hint: it's not documents) figure out that i have to append my package name after pkg finally have some docs i can look at
Member

### mdempsky commented Aug 10, 2016

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

### aeneasr commented Aug 10, 2016 • edited

 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 ;)
Author

### aeneasr commented Aug 10, 2016

 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 :)
Member

### rakyll commented Aug 10, 2016

 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?

Author

Author

### aeneasr commented Aug 10, 2016 • edited

 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 :)
Member

### bradfitz commented Aug 10, 2016

 Another option: you can also use any UTF-8 in godoc, so you can format it as: • Item 1 • Item 2 • Item 3 Where the bullet (•) is just an actual Unicode bullet (U+2022).
Member

### bradfitz commented Aug 10, 2016

 Or if you care about formatting, you indent it like code, and it ends up looking like: * Item 1 words words words words words words words words words words words words words words words words words words * Item 2 words words words words words words words words words words word words words words words words words words * Item 3 words words words words words words words words words words words words words words words words words words
Author

### aeneasr commented Aug 10, 2016 • edited

 So how would I format that using e.g. CSS? I think it's great that godoc supports UTF-8, but imho it's questionable if these type of workarounds are: a. user/developer friendly b. make writing go documentation something enjoyable c. interoperable d. only a pseudo-fix for obvious problems Plus, this is not only about lists, it's about more things that are missing imo. GitHub has made writing documentation great, why not take the good parts of this process every developer today is used to and introduce them to go?
Contributor

### ianlancetaylor commented Aug 10, 2016

 There are several different ideas here. I don't know which are more important. Something like "support markdown in godoc" should go through the proposal process. It will require somebody to implement it.
Author

### aeneasr commented Aug 10, 2016

 The vision should be to improve the process of writing documentation in Go. Weighting features and discussing what people need or don't need should be an essential part of it. A proposal is a good idea, unless this means that the issue will just be pushed back until forever. I would gladly contribute to this and I'm sure other gophers will too.
Contributor

### as commented Aug 11, 2016 • edited

 I like that Go documentation doesn't interpret markdown. It makes the documentation easier to read with go doc pkgname. I don't miss or /// either.
Author

### aeneasr commented Aug 11, 2016 • edited

 It makes the documentation easier to read with go doc pkgname. Then again, go doc pkgname could strip that (markdown/html/...) away, so it's easy to read in the console and readable/expressive on the web.
Contributor

### kostya-sh commented Aug 11, 2016

 Most of the time I read the documentation in a text editor along with the code. So many things like images, links, emphasis, etc cannot be displayed. These features might make HTML version of the documentation better looking but the text version might become harder to read. One case when readability of HTML documentation is inferior to the text version is list formatting (#7873). I would love to see it fixed.

Author

### aeneasr commented Sep 7, 2016

 Again, sorry if this comes across as spam, but I feel like this is an area of design that I can really contribute to. Don't worry, I'd rather have 100 mails of GitHub notifications regarding discussion / ideas / contributions to a topic than none. :)

Closed

Open

Open

Merged