proposal: go/doc: Support for bulleted lists

[robfig]

Presently, the best practice when enumerating something in godoc is to use a
pre-formatted section.  For example:

"""
This library has the following caveats:
  * It requires the caller to invoke the method
    only on odd-numbered days
  * It may crash your computer.
"""

I think it would improve godoc (HTML) readability to recognize and format bulleted lists
as <ul>'s instead.  The recognition could be narrowly defined to avoid mistakenly
formatting blocks that were not intended to be lists.

I propose a list is recognized as:
- An indented (pre-formatted) block, 
- .. that consists of 2 or more list items
- .. and that consists only of list items

and a list item is defined as:
- Consecutive lines
- .. where the first line begins with "- " or "* "
- .. that terminate on blank lines.

This can be implemented with minimal disruption to the existing code.  Here is a CL:
https://golang.org/cl/91830044

Here are some before/after examples from popular package docs: 

http://godoc.org/code.google.com/p/gorilla/mux
http://192.241.149.161:8080/pkg/code.google.com/p/gorilla/mux

http://godoc.org/code.google.com/p/gorilla/sessions
http://192.241.149.161:8080/pkg/code.google.com/p/gorilla/sessions

http://godoc.org/code.google.com/p/gorilla/schema
http://192.241.149.161:8080/pkg/code.google.com/p/gorilla/schema

http://godoc.org/code.google.com/p/gogoprotobuf/gogoproto
http://192.241.149.161:8080/pkg/code.google.com/p/gogoprotobuf/gogoproto

http://godoc.org/github.com/davecgh/go-spew/spew
http://192.241.149.161:8080/pkg/github.com/davecgh/go-spew/spew

http://godoc.org/code.google.com/p/go.text/collate/colltab#pkg-constants
http://192.241.149.161:8080/pkg/code.google.com/p/go.text/collate/colltab#pkg-constants

[bradfitz]

Comment 1:

Previous proposals similar to this have been rejected on grounds that it's a slippery
slope from this to Markdown or worse.

[robfig]

Comment 2:

I agree wholeheartedly with comments as plain text, free of presentation markup. 
This CL reflects how developers are already writing documentation and is a strict
improvement in the presentation of it.  I don't believe it has any cost to in-code
comment readability.

[ianlancetaylor]

Comment 3:

The way to discuss a proposal like this is to raise it on the public lists.  Especially
if you have a patch.  See http://golang.org/doc/contribute.html .  Thanks.

Labels changed: added repo-main, release-none.

[frankandrobot]

Are you kidding me? You guys have an issue with markdown?

[bradfitz]

@frankandrobot, that is not a constructive comment. We happily use Markdown on Github and elsewhere. We just don't want it to be Go's documentation format.

[frankandrobot]

@bradfitz i'm surprised that you guys decided to go with plain text. In practice in a large, complex app, you'll end up approximating a markup language for readability anyway (ex: caps for sections), and well you might as well pick a markup language for comments.

Alternatively, since you guys hate markdown, is there the ability to pick whatever markup you want (like a plugin for markdown)?

[bronger]

While I sympathise with not supporting Markdown in godoc, I also think that bulleted lists are important enough to have them properly displayed in godoc. A PR is still welcome? Or has this been rejected somewhere else already?

[bradfitz]

I think @adg and @robpike want to see a design before code.

[robpike]

And @griesemer.

[theherk]

I understand and support the strive for simplicity. In this case, it seems, simplicity could be improved going either direction. Either have it be plain text or support a preexisting parser. To do it the way it is currently seems unnecessarily complex. As it stands, a simple parser is implemented (to heading sections and for preformatted text; documented here).

It seems that just supporting an already existing parser, or at least parser specification like Markdown, would be duck soup. Maybe it would hurt the elegance of the output, but a list is a key ingredient of documentation.

[griesemer]

Moving to 1.9Maybe to raise visibility. No guarantee we're getting to it for 1.9, though.

[awnumar]

@bradfitz

Previous proposals similar to this have been rejected on grounds that it's a slippery slope from this to Markdown or worse.

This is an example of the slippery-slope fallacy and is not a valid argument.

[bradfitz]

@libeclipse, thanks.

[KernelDeimos]

In case anybody is interested, I made a modified version of Godoc that adds ordered and unordered lists with a fast and simple custom parser I wrote called slippery-slope-markdown.

Here's a link to my modified version: godoc-custom-fork

Admittedly, the way I threw it in there is kinda hacky, but it could be a starting point.

The parser follows this convention:

• A line starting with - and a space is a list item
• Any non-blank line following a list item belongs to that list item
• A blank line terminates the list

A similar convention is applied to ordered lists. As an aside, it also allows bold text.

[dsnet]

I hacked up an implementation of this (~25 lines of change on top of CL/72890) and I feel more strongly now that lists be preceded by indents since there are some cases where users have preceding "1. " or "* " where their intention is not to have a list, but rather a heading (which is a separate concept from what this issue is about).

Secondly, lists are typically rendered with an intent themselves, thus, it is natural to expect that how they appear in the comment also be indented.

[theherk]

If their intent is to have a heading, they should have the span be a single line, begin with a capital letter, and contain no punctuation. Indentation has a meaning already, <pre>; no reason to confuse that. How lists are commonly rendered seems irrelevant. How are they most intuitively read and written in plain text?

[gopherbot]

Change https://golang.org/cl/113915 mentions this issue: crypto/x509: reformat template members in docs

[cespare]

I previously discussed turning this into a proposal but never did. Adding the label now, so that this gets discussed.

Current proposal is to go with @dsnet's suggestions in #7873 (comment) and #7873 (comment). Essentially, we'll take the current "standard" workaround for bulleted lists (indent so as to create a code block) and recognize it, turning it into a nice bullet list in HTML. We could optionally do something special for text (go doc) output but it's okay to leave that alone for now.

[bcmills]

we'll take the current "standard" workaround for bulleted lists (indent so as to create a code block) and recognize it

In addition to the asterisks in @dsnet's sketch, we should probably also accept at least Unicode bullets (because they express clear semantic intent) and hyphen-minus characters (because that's what we use throughout the Go codebase) as the leading symbol to recognize a list.

[mwmahlberg]

We think those comments can be ordinary text, and so far we're willing to stick to that.

Isn't that the whole point of markdown? That it can be read both as ordinary text but can also be rendered to a more eye-friendly form? I can see some problems here, for example on how to deal with markdown links (both of the hyper and image flavor), but those could be easily circumvented, couldn't it?

I personally would love to have markdown in my comments, since that would basically prevent me from redoing myself having both godoc comments and a more detailed explanation elsewhere. So basically, all documentation could be dealt with and would be present in one place.

[cespare]

@mwmahlberg in the past year this thread has been converging on a small, concrete proposal for adding lists. That's also the title of the issue. It previously devolved into a markdown discussion, but I'd like for it to stay focused on just lists at this point in hopes that it will finally be reviewed and approved.

At this point, let's put new requests for markdown into a new issue or else add details to #16666. Thanks.

[cespare]

@golang/proposal-review is there something more to be done to move this along? (I understand that I can't expect much at this point during the last few weeks of the year, but I added the proposal label in August.)

[mwmahlberg]

@cespare I understand that and did not mean to escalate the topic at hand. But my point of view is that the question at hand is basically a landmark decision: Open up for more formatted godocs or not? Because when it is started, more feature requests will come in: named links, tables, etc. Therefor, the reluctance is understandable. What I was trying to bring across that markdown|rst|foobar markup could be seen as a language feature with quite some value (DRY) for developers.

[rsc]

Generally, we'd like to allow writing lists in docs. Deciding the exact syntax is still unresolved. It's not a high priority right now.

[gopherbot]

Change https://golang.org/cl/167403 mentions this issue: builtin: make len's godoc less ambiguous