x/tools/cmd/godoc: link "package foo" and "foo package" in text when "foo" exists

[adg]

It would be nice if godoc could automatically link text that refers to extant packages.

[adg]

Comment 1:

Labels changed: added godoc.

[gopherbot]

Comment 2 by pedromorgan:

Yes please This is silly that its not there..
I cannot even create a summary text and link directly to types and functions etc.
Also missing is basic fomratting eg * for bullets and == for headings ==

[griesemer]

Comment 3:

This request is somewhat underspecified to act upon. Questions to be answered:
1) What godoc text? Comments that shows up in documentation? Any godoc text (probably
not). Something else?
2) When does a package exist? When it's in the std lib? Somewhere else?
There already is a mechanism to highlight individual words in documentation comments,
for instance to connect the documentation to parameter names in the documented function
or method. That machinery is not used yet. It could be modified to do a bit more.

[adg]

Comment 4:

1) Anything that we search for and linkify "http://example.com".
2) When godoc lists it in /pkg/.

[gopherbot]

Comment 5 by aaron.l.france:

Maybe a textual way to say "expand this symbol"?
Something like: `!`io.Reader`

[4ad]

Comment 6:

No magic syntax. Just plain text.

[gopherbot]

Comment 7 by sedevelopers01:

Why not markdown? It's conrete, easy-to-read and well-known.
http://daringfireball.net/projects/markdown/syntax

[adg]

Comment 8:

It has been debated before. The conclusion is that we will not include any kind of
special syntax in godoc comments. The consensus is that they should read just like
regular comments, and require very little understanding of godoc's mechanisms to write
correctly.

[adg]

Comment 9:

Issue #5852 has been merged into this issue.

[adg]

Comment 11:

Issue #6207 has been merged into this issue.

[rsc]

Comment 12:

Labels changed: added repo-tools.

[rsc]

Comment 13:

Adding Release=None to all Priority=Someday bugs.

Labels changed: added release-none.

[kegsay]

I think this specific feature request is "in the spirit of" the simple GoDoc style requirements in the same way that http:// links are. They are regular comments that make sense on their own.

My use case is to be able to have well-documented package overviews which then link off to sub-packages for further reading. There is a concern that this could feature-creep (e.g. linking to a specific definition in a given package) but the simple case of linking to a package only seems pretty uncontroversial to me.

[griesemer]

Marking this 1.13 so it gets some visibility.

[seankhliao]

documentation links are available for modern doc systems https://go.dev/doc/comment#links