New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
aeneasr opened this Issue Aug 10, 2016 · 21 comments

Comments

Projects
None yet
9 participants
@aeneasr

aeneasr commented Aug 10, 2016

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

This comment has been minimized.

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

@aeneasr

This comment has been minimized.

aeneasr commented Aug 10, 2016

@mdempsky

This comment has been minimized.

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?

@bradfitz

This comment has been minimized.

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.

@bradfitz bradfitz changed the title from godoc should support basic things like lists, links, emphasis, bold, inline code, ... to x/cmd/godoc: request for richer formatting Aug 10, 2016

@bradfitz bradfitz changed the title from x/cmd/godoc: request for richer formatting to x/tools/cmd/godoc: request for richer formatting Aug 10, 2016

@bradfitz bradfitz added the Thinking label Aug 10, 2016

@aeneasr

This comment has been minimized.

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:

  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

This comment has been minimized.

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.

@aeneasr

This comment has been minimized.

aeneasr commented Aug 10, 2016

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

This comment has been minimized.

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

@rakyll

This comment has been minimized.

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?

@rakyll rakyll added this to the Unreleased milestone Aug 10, 2016

@aeneasr

This comment has been minimized.

aeneasr commented Aug 10, 2016

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.

lists

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 comment has been minimized.

aeneasr commented Aug 10, 2016

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.

lists-godoc


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

@bradfitz

This comment has been minimized.

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

@bradfitz

This comment has been minimized.

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 
@aeneasr

This comment has been minimized.

aeneasr commented Aug 10, 2016

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

This comment has been minimized.

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.

@aeneasr

This comment has been minimized.

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.

@as

This comment has been minimized.

Contributor

as commented Aug 11, 2016

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

This comment has been minimized.

aeneasr commented Aug 11, 2016

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

This comment has been minimized.

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.

@Kroc

This comment has been minimized.

Kroc commented Sep 6, 2016

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:

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

This comment has been minimized.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment