{{ message }}

proposal: go/doc: Support for bulleted lists #7873

Open
opened this issue Apr 26, 2014 · 48 comments
Open

proposal: go/doc: Support for bulleted lists#7873

opened this issue Apr 26, 2014 · 48 comments
Labels
Projects
Milestone

robfig commented Apr 26, 2014

 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
'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 The text was updated successfully, but these errors were encountered:

 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 commented Apr 26, 2014

 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 commented May 9, 2014

 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.
removed the label Dec 18, 2014
added this to the Unplanned milestone Apr 10, 2015
removed labels Apr 10, 2015
mentioned this issue Jan 28, 2016
mentioned this issue Aug 10, 2016

frankandrobot commented Sep 27, 2016

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

 @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 commented Sep 28, 2016

 @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 commented Sep 28, 2016

 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?

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

robpike commented Sep 28, 2016

 And @griesemer.
mentioned this issue Nov 9, 2016

theherk commented Mar 1, 2017

 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.
modified the milestones: Go1.9Maybe, Unplanned Mar 1, 2017

griesemer commented Mar 1, 2017

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

awnumar commented Mar 19, 2017 • edited

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

 @libeclipse, thanks.
added the label Jun 28, 2017
modified the milestones: Go1.10, Go1.9Maybe Jun 28, 2017

KernelDeimos commented Jun 29, 2017

 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.
mentioned this issue Jun 30, 2017

gopherbot commented May 20, 2018

 Change https://golang.org/cl/113915 mentions this issue: crypto/x509: reformat template members in docs
pushed a commit that referenced this issue May 22, 2018
 crypto/x509: reformat template members in docs 
 5c8f65b 
It's easier to skim a list of items visually when the
items are each on a separate line. Separate lines also
help reduce diff size when items are added/removed.

The list is indented so that it's displayed preformatted
in HTML output as godoc doesn't support formatting lists
natively yet (see #7873).

Change-Id: Ibf9e92437e4b464ba58ea3ccef579e8df4745d75
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
modified the milestones: Go1.11, Unplanned May 23, 2018
added a commit to navytux/go123 that referenced this issue Jul 10, 2018
 *: Obey current Go suggested rule to format lists in comments 
 f7e2c63 
Until golang/go#7873 is fixed/implemented,
let's follow the currently advised scheme to indent lists and this way
put them as pre-formatted text.

We already do so mostly everywhere, but 2 of the places were not
following it and thus all items there were rendered as one line.
mentioned this issue Aug 2, 2018
added the label Aug 2, 2018

cespare commented Aug 2, 2018

 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 commented Aug 2, 2018

 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.
mentioned this issue Sep 24, 2018

mwmahlberg commented Dec 17, 2018 • edited

 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.
changed the title go/doc: Support for bulleted lists proposal: go/doc: Support for bulleted lists Dec 17, 2018

cespare commented Dec 17, 2018

 @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 commented Dec 17, 2018

 @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 commented Dec 18, 2018

 @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 commented Dec 19, 2018

 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.
added the label Dec 19, 2018
mentioned this issue Feb 22, 2019

gopherbot commented Mar 13, 2019

 Change https://golang.org/cl/167403 mentions this issue: builtin: make len's godoc less ambiguous
pushed a commit that referenced this issue Mar 13, 2019
 builtin: make len's godoc less ambiguous 
 1a24bf1 
The len godoc uses a blockquote to list the rules for its semantics.

The item that describes channels is a bit long, so it's split in two
lines. However, the first line ends with a semicolon, and the second
line can be read as a sentence of its own, so it's easy to misinterpret
that the two lines are separate.

Making that easy mistake would lead to an incorrect understanding of
len:

if v is nil, len(v) is zero.

This could lead us to think that len(nil) is valid and should return
zero. When in fact, that statement only applies to nil channels.

To make this less ambiguous, add a bit of indentation to the follow-up
line, to align with the channel body. If lists are added to godoc in the
future via #7873, perhaps this text can be simplified.

Fixes #30349.

Change-Id: I84226edc812d429493137bcc65c332e92d4e6c87
Run-TryBot: Daniel Martí <mvdan@mvdan.cc>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
removed the label Aug 16, 2019
This was referenced Nov 28, 2019
added this to Hold in Proposals Dec 4, 2019

rwxrob commented Apr 17, 2020

 I find it extremely disturbing that this discussion has not once referenced the amazing efforts of the Pandoc Markdown project (which is the standard documentation method use by the R language as well as many text books). It is objectively the most widely adopted knowledge source standard.

fosskers commented Aug 21, 2020

 Can this move forward at all? It seems like many people are looking for it, and miss this docstring feature that is present in many other languages.

dmitshur commented Aug 21, 2020 • edited

 /cc @julieqiu This is a longstanding proposal (with lots of discussion above) to modify how Go packages can be documented. Perhaps it should be considered as part of other future work that's being done to improve documentation rendering on pkg.go.dev.
added the label Aug 21, 2020

tooolbox commented Aug 29, 2020

 Just stumbled across this. 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. 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. Sounds great! Would be neat to address this in pkg.go.dev.
mentioned this issue Sep 23, 2020