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