search

golang / go

The Go programming language
https://go.dev
BSD 3-Clause "New" or "Revised" License
124.1k stars 17.68k forks source link

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

Open adg opened 11 years ago

adg commented 11 years ago 
It would be nice if godoc could automatically link text that refers to extant packages.
adg commented 11 years ago

Comment 1:

Labels changed: added godoc.

gopherbot commented 11 years ago

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 commented 11 years ago

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 commented 11 years ago

Comment 4:

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

Comment 5 by aaron.l.france:

Maybe a textual way to say "expand this symbol"?
Something like: `!`io.Reader`
4ad commented 11 years ago

Comment 6:

No magic syntax. Just plain text.
gopherbot commented 11 years ago

Comment 7 by sedevelopers01:

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

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 commented 11 years ago

Comment 9:

Issue #5852 has been merged into this issue.

adg commented 11 years ago

Comment 11:

Issue #6207 has been merged into this issue.

rsc commented 10 years ago

Comment 12:

Labels changed: added repo-tools.

rsc commented 10 years ago

Comment 13:

Adding Release=None to all Priority=Someday bugs.

Labels changed: added release-none.

kegsay commented 5 years ago

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 commented 5 years ago

Marking this 1.13 so it gets some visibility.