go/doc: add ToMarkdown

[JAicewizard]

Recently gopls added markdown output for markdown comments, the implementation is basically a copy of go/doc/comment.go replacing some things with markdown instead of html.
If go/doc was more flexible this would have been less of a copy paste. These should be a interface which can be used to create custom formatters. In this way packages that need backwards compatibility with older go stdlibs can create a formatter and use this with older versions of go. The type implementing this can be copy pasted into go/doc/comment.go(or vice versa).

I am willing to implement this together with porting the gopls markdown implementation to go/doc

[julieqiu]

/cc @dmitshur

[JAicewizard]

Hi, although its been a while I have functional code and an interface that should work in all situations. I have implemented this interface with all the old formats and markdown.
Can somebody check if I should open a CL for it? (not s in check my code, just in general)

[stamblerre]

@JAicewizard: We are currently in the freeze part of the Go release cycle (see https://github.com/golang/go/wiki/Go-Release-Cycle), so no new features will be accepted. I would suggest sending a CL when the tree is opened after Go 1.14 is released.

[JAicewizard]

Thanks for the info, I didn't want to start with sending in a CL without any discussion on what the interface should look like, but I will set a reminder to send one in February.

[stamblerre]

Sounds good. I think if you have a CL ready, you should be fine to send it in February and discussion can occur during the review process. Otherwise, you can mark this issue as a proposal to spark the conversation (just add the prefix "proposal: " to the issue title).

[gopherbot]

Change https://golang.org/cl/223577 mentions this issue: go/doc: make formatting comments more flexible using an interface

[dmitshur]

Thanks for sending that change, @JAicewizard. It will be helpful to have that prototype when discussing and considering this change.

The go/doc package is low level and in the standard library. Once new API is added to it, it is not possible to change due to the Go 1 compatibility promise. As a result, any potential API additions need to be discussed and agreed on first. (See issue #23864 for an example of a previous proposal to add new functionality to the go/doc package.)

We may decide that adding this new functionality would be better to do in another package (not in the standard library). It depends on whether we can expect the proposed API to solve the problem well today and in the future, without needing further API changes. Until then, it may be less costly to just maintain copies of the code in the necessary packages.

/cc @griesemer @agnivade per owners.

[dmitshur]

Also see CL 72890 for related work. It is an attempt to split documentation rendering into smaller and more flexible building blocks. An updated copy of that package is being used to render documentation on pkg.go.dev, which is going to be open sourced (see #36747).