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

[bradfitz]

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

[bradfitz]

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 

[aeneasr]

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?

[ianlancetaylor]

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.

[aeneasr]

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.

[as]

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

[aeneasr]

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.

[kostya-sh]

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.

[Kroc]

Please accept my apologies for the mail spam created by replying to this thread; I have some interest / experience in this area having developed and used a formatting markup of my own devising for 8 years now.

Before I even talk about possible syntax to use; a policy you could adopt is to introduce formatting syntax only one, complete instance at a time (each Go release for example) -- allowing time for discussion and seeing what happens to it out in the wild.

---

My own markup system was developed specifically to look best as raw text as I would primarily be editing it in a text editor. I won't recommend my own syntax as-is, but I can provide some lessons learnt.

The use of <angle brackets (/url)> for URLs flows more naturally than [those of Markdown](/url)
and actually has more precedence in programmers' comments, e.g. <google.com>, than
Markdown's arbitrary syntax.

Though I would improve my original syntax to <use a colon or bar for URL separation : /url>.
Relative URLs I abbreviated like <this>, where "this" implies a URL of "./this", and could be
used for interlinking; though [square brackets] are a more common syntax for that. 

A markup syntax should communicate the programmer's voice rather than force them to micro-manage semantics; such as being forced to apply markup for all Proper Names they desire to be interlinked. Where possible of course, go doc could automatically hyperlink words it can recognise as Proper Names, but given go's naming conventions this is never 100% possible and is probably a chimera that should not be chased.

If I had to provide a solution with the noted concern of burdening documentation writers the world over, then these are the two solutions I propose:

1. An acute at the end of a word signals the word as a Proper Name to be linked.
   e.g. returns a lexer^ struct
2. Prefixing Proper Names with a dot; this implies that we are abbreviating the fully-qualified dotted notation of something. e.g. returns a .lexer struct implies that .lexer is this package's lexer. This is my preferred syntax as it's light on the eyes, easy to type and doesn't introduce punctuation that has alternate meaning in Go code proper

---

Most all markup syntaxes don't include Definition Lists, and this is very sad! :(
Definition lists are awesome. The syntax I arrived at is visually pleasing and very easy to type

:: Aardvark
    A large, nocturnal, burrowing mammal, Orycteropus afer, of central and southern
    Africa, feeding on ants and termites and having a long, extensile tongue,
    strong claws, and long ears.

:: Abacus
    A device for making arithmetic calculations, consisting of a frame set
    with rods on which balls or beads are moved.

I provide this as an alternative to consider too:
(line ending in colon with indented area immediately following, no blank line between)

Aardvark:
    A large, nocturnal, burrowing mammal, Orycteropus afer, of central and southern
    Africa, feeding on ants and termites and having a long, extensile tongue,
    strong claws, and long ears.

Abacus:
    A device for making arithmetic calculations, consisting of a frame set
    with rods on which balls or beads are moved.

---

I have spent a long time sweating details over plain-text presentation of markup syntax as I was not content to accept existing systems that lean to heavy on being languages of their own; I can understand very much why Google wanted to keep documentation comments as natural as possible.

My ideas on this issue are forever evolving. If you're interested in seeing more of my markup syntax, please browse over the following two guides:

• http://forum.camendesign.com/markup.php
• http://camendesign.com/remarkable

Again, sorry if this comes across as spam, but I feel like this is an area of design that I can really contribute to.

Kind regards,
Kroc Camen.

[aeneasr]

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

[karelbilek]

Aside note: I have notice Google itself uses Markdown in their godoc. :D

https://pkg.go.dev/google.golang.org/genproto/googleapis/api/annotations?tab=doc#HttpRule

[slinkydeveloper]

Hi, can we do something for this? Any pointers on where to start?

[karelbilek]

Hi, can we do something for this? Any pointers on where to start?

I am not that qualified to work on this, but maybe start on looking into godoc source code and where to put Markdown parser and HTML renderer?

As for Markdown parsing and rendering, I can recommend using https://github.com/yuin/goldmark which is now used by Hugo and is CommonMark compliant. (Markdown is really tricky to parse!)

[karelbilek]

Maybe it, however, needs to go through go proposals first, and I have no idea how does that work.

[pioz]

IMHO, an important thing is to highlight in some way (code, bold, italic,...) the names of the function parameters. For example:

NewBank creates a new bank that supports the currencies in the slice currencies and uses fetch to fetch the exchange rates table.

func NewBank(currencies []Currency, fetch FetchExchangeRatesTableFunc)

This helps a lot to read the docs and to understand what a param does.

[decadenza]

Are there any plans to have a markdown-like syntax in the future?

[seankhliao]

closing for new syntax in go.dev/doc/comment