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
go/doc: improve headings, lists, and links #51082
Comments
Change https://go.dev/cl/384263 mentions this issue: |
Change https://go.dev/cl/384257 mentions this issue: |
Change https://go.dev/cl/384267 mentions this issue: |
Change https://go.dev/cl/384258 mentions this issue: |
Change https://go.dev/cl/384265 mentions this issue: |
Change https://go.dev/cl/384266 mentions this issue: |
Change https://go.dev/cl/384268 mentions this issue: |
Change https://go.dev/cl/384264 mentions this issue: |
Change https://go.dev/cl/384259 mentions this issue: |
Change https://go.dev/cl/384260 mentions this issue: |
Change https://go.dev/cl/384274 mentions this issue: |
The top comment has been filled in now. |
This solves 90% of my problems working with docstrings and makes the remaining 10% trivial. I am ecstatic! I'd be perfectly happy to have this accepted as-is but I do have a couple minor thoughts: I'd s/Text/Inline/g and then s/Plain/Text/g to align with html. That could just be familiarity but it seems clearer to me. Allow subheadings with |
For now I think we should keep things simple and not increase scope past the previous discussion. There would really be no problem with having ## render as a paragraph during a later transition. Single # is rendering as a paragraph during this one. |
In numbered point 5 in the goals and non-goals, the absence of in-line image support is noted for a couple of languages and support by one, but no mention of Python (a much more relevant language than for example Perl). Here it does exist in some projects https://numpy.org/doc/stable/reference/generated/numpy.fft.fft.html#numpy.fft.fft and in general, Python doc strings may be valid reStructuredText which allows embedding of images. |
Python supports images in their docs, noted. |
I am extremely excited about this! A couple of questions / suggestions.
Again, really looking forward to this in any case. |
Overall this looks good, but I want to restate my concern about the accessibility issues I raised with the approach to marking links. |
Thanks for the questions, @ainar-g.
|
@kortschak Noted re link syntax. I don't have anything more to add beyond #48305 (comment). |
It's worth noting that I did follow that up OOB with a detailed response, but did not receive a reply. |
Overall, this is exciting to see. A few quick questions about linking to headers and the relationship to the base URL.
In any event, I think the ability to link to headers would be extremely useful, especially for complex packages. |
This proposal has been added to the active column of the proposals project |
golang/go#51082 changed how gofmt handles some comments, so we need to slightly reformat them to avoid `gofmt -s -d .` errors.
Gofmt to update doc comments to the new formatting. (There are so many files in x/tools I am breaking up the gofmt'ing into multiple CLs.) For golang/go#51082. Change-Id: I0cc2e6cac2e4ed975770aea78cc2f39c13d6f874 Reviewed-on: https://go-review.googlesource.com/c/tools/+/399357 Run-TryBot: Russ Cox <rsc@golang.org> Auto-Submit: Russ Cox <rsc@golang.org> gopls-CI: kokoro <noreply+kokoro@google.com> TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Ian Lance Taylor <iant@google.com>
Gofmt to update doc comments to the new formatting. (There are so many files in x/tools I am breaking up the gofmt'ing into multiple CLs.) For golang/go#51082. Change-Id: Ife11502fe1e59a04d53dba9edccd3043e57f9ae8 Reviewed-on: https://go-review.googlesource.com/c/tools/+/399358 Run-TryBot: Russ Cox <rsc@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org> Auto-Submit: Russ Cox <rsc@golang.org> gopls-CI: kokoro <noreply+kokoro@google.com> Reviewed-by: Ian Lance Taylor <iant@google.com>
Gofmt to update doc comments to the new formatting. (There are so many files in x/tools I am breaking up the gofmt'ing into multiple CLs.) For golang/go#51082. Change-Id: I77809c80838cc8f4cdf43c3c42685e2fc695328a Reviewed-on: https://go-review.googlesource.com/c/tools/+/399359 Run-TryBot: Russ Cox <rsc@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org> Auto-Submit: Russ Cox <rsc@golang.org> gopls-CI: kokoro <noreply+kokoro@google.com> Reviewed-by: Ian Lance Taylor <iant@google.com>
Gofmt to update doc comments to the new formatting. (There are so many files in x/tools I am breaking up the gofmt'ing into multiple CLs.) For golang/go#51082. Change-Id: I229b90365998244cfa858ae678382f6089b1cdb9 Reviewed-on: https://go-review.googlesource.com/c/tools/+/399360 Run-TryBot: Russ Cox <rsc@golang.org> Auto-Submit: Russ Cox <rsc@golang.org> gopls-CI: kokoro <noreply+kokoro@google.com> TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Ian Lance Taylor <iant@google.com>
Gofmt to update doc comments to the new formatting. (There are so many files in x/tools I am breaking up the gofmt'ing into multiple CLs.) For golang/go#51082. Change-Id: I5e11f2946001b9b36b7bd3af4d42da9dcea7494f Reviewed-on: https://go-review.googlesource.com/c/tools/+/399361 Run-TryBot: Russ Cox <rsc@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org> Auto-Submit: Russ Cox <rsc@golang.org> gopls-CI: kokoro <noreply+kokoro@google.com> Reviewed-by: Ian Lance Taylor <iant@google.com>
Gofmt to update doc comments to the new formatting. (There are so many files in x/tools I am breaking up the gofmt'ing into multiple CLs.) For golang/go#51082. Change-Id: I58a534f3e518dad2d3a867f81b08a551a76bd423 Reviewed-on: https://go-review.googlesource.com/c/tools/+/399362 Run-TryBot: Russ Cox <rsc@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org> Auto-Submit: Russ Cox <rsc@golang.org> gopls-CI: kokoro <noreply+kokoro@google.com> Reviewed-by: Ian Lance Taylor <iant@google.com>
Gofmt to update doc comments to the new formatting. (There are so many files in x/tools I am breaking up the gofmt'ing into multiple CLs. This is the leftovers.) For golang/go#51082. Change-Id: Id9d440cde9de7093d2ffe06cbaa7098993823d6b Reviewed-on: https://go-review.googlesource.com/c/tools/+/399363 Run-TryBot: Russ Cox <rsc@golang.org> Auto-Submit: Russ Cox <rsc@golang.org> gopls-CI: kokoro <noreply+kokoro@google.com> TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Ian Lance Taylor <iant@google.com>
Gofmt to update doc comments to the new formatting. For golang/go#51082. Change-Id: Ic98f647623f234cf5d36309c6204683e151820d7 Reviewed-on: https://go-review.googlesource.com/c/example/+/399596 Run-TryBot: Russ Cox <rsc@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org> Auto-Submit: Russ Cox <rsc@golang.org> Reviewed-by: Ian Lance Taylor <iant@google.com>
Gofmt to update doc comments to the new formatting. For golang/go#51082. Change-Id: Ia404739fe81daca82a209ff82fc29ac3a064cea2 Reviewed-on: https://go-review.googlesource.com/c/benchmarks/+/399595 Run-TryBot: Russ Cox <rsc@golang.org> Auto-Submit: Russ Cox <rsc@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org> Reviewed-by: Ian Lance Taylor <iant@google.com>
Gofmt to update doc comments to the new formatting. For golang/go#51082. Change-Id: I9b4c287e2d25aa108adfa9fe2f972c8fd3d68fe1 Reviewed-on: https://go-review.googlesource.com/c/mobile/+/399597 Run-TryBot: Russ Cox <rsc@golang.org> Reviewed-by: Ian Lance Taylor <iant@google.com> TryBot-Result: Gopher Robot <gobot@golang.org> Auto-Submit: Russ Cox <rsc@golang.org>
Gofmt to update doc comments to the new formatting. For golang/go#51082. Change-Id: Iac828c845b6d7ae0eab93fcf007f3ef8e16c8ed7 Reviewed-on: https://go-review.googlesource.com/c/exp/+/399614 Run-TryBot: Russ Cox <rsc@golang.org> Reviewed-by: Ian Lance Taylor <iant@google.com> TryBot-Result: Gopher Robot <gobot@golang.org> Auto-Submit: Russ Cox <rsc@golang.org>
I think there is a bug with list formatting when comment start and end with Test codeSee https://go.dev/play/p/WfIdp2WQphD?v=gotip Expected result
Got result
|
@shuLhan Would you mind opening a new issue for that specific problem? Thanks. |
I believe that all changes described here have been submitted, so closing this issue. Please comment if you disagree. |
Gofmt to update doc comments to the new formatting. For golang/go#51082. Change-Id: I9a1c4b671c06820a1c383ee515f7884965fefa54 Reviewed-on: https://go-review.googlesource.com/c/sys/+/399602 Reviewed-by: Ian Lance Taylor <iant@google.com> Auto-Submit: Russ Cox <rsc@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org> Run-TryBot: Russ Cox <rsc@golang.org>
Still one pending CL: the doc comment for the comment package: https://go.dev/cl/397287. |
The changes for this proposal appear to have introduced a crash in |
This is only waiting documentation now, right? |
Change https://go.dev/cl/407137 mentions this issue: |
Excluding vendor and testdata. CL 384268 already reformatted most, but these slipped past. The struct in the doc comment in debug/dwarf/type.go was fixed up by hand to indent the first and last lines as well. For #51082. Change-Id: Iad020f83aafd671ff58238fe491907e85923d0c7 Reviewed-on: https://go-review.googlesource.com/c/go/+/407137 Run-TryBot: Russ Cox <rsc@golang.org> TryBot-Result: Gopher Robot <gobot@golang.org> Auto-Submit: Russ Cox <rsc@golang.org> Reviewed-by: Ian Lance Taylor <iant@google.com>
This proposal improves support for headings, lists, and links in Go doc comments,
while remaining backwards compatible with existing comments.
It includes a new package,
go/doc/comment
, exposing a parsed syntax tree fordoc comments, and it includes changes to
go/printer
and thereforegofmt
to format doc comments in a standard way.
For example, existing lists reformat from the display on the left to the one on the right:
URL links can be rewritten to change the display on the left to the one on the right:
And package doc comments (and others) can be rewritten to link to specific symbols:
The full design doc is at https://github.com/golang/proposal/blob/master/design/51082-godocfmt.md.
The text was updated successfully, but these errors were encountered: