Add "Refs" (find usages) links to definitions

[sqs]

This PR adds unobtrusive "Uses" links for each type, func, and method that show all references to the item (on Sourcegraph). Like the permalink, the Refs link is only displayed on hover.

Viewing usages of a definition is a good way to determine how (best) to use something, especially when the documentation is poor or nonexistent.

Possible improvements/changes:

• Fetch the reference count from the Sourcegraph API (either on the backend or on the client) and make the link read "Refs (123)" or "123 refs" instead of just "Refs"
• Find a way to add refs links for vars and consts (which don't have headers)

Disclaimer: I'm one of the creators of Sourcegraph. I think lots of people would find it useful to view usages (and several people asked me to submit this), but I know it'd be a slippery slope to start adding external links to gddo. I'd obviously totally understand if this PR is rejected.

(As an aside, gowalker.org already offers links to examples on Sourcegraph; see bytes.Buffer on gowalker.org, for example. They are quite popular, judging from our site analytics.)

---

Demo

• Go to http://godoc.sgdev.org/github.com/gorilla/mux#Route.Match

• Hover over the Match header and click Uses
• You're taken to the Sourcegraph listing of references to the Match method

[dmitshur]

In general, I agree that being able to easily find usages of an identifier is useful. Especially when docs are unclear or lacking, or usage requires some helpers whose availability is not immediately obvious.

Some thoughts:

• "Refs" is a very generic word that, at least to me, suggests nothing about what it actually is. I think "Usages" or "Examples" or "Usage Examples" would be a better term to use here.

• If this functionality were available for all identifiers for all packages, then I would argue it should have a more prominent position, similar to the way doc examples are displayed at the bottom:

  

  However, I understand that that's not the case. Some identifiers may actually not be used anywhere in the wild, or perhaps they are used but those packages were not yet processed by Sourcegraph. Finally, some usage examples may not be of high quality (is it a precondition for the code to compile for it to show up as a ref?).

  If the "Fetch the reference count from the Sourcegraph API" improvement is done, perhaps that might be enough to promote this feature to have higher visibility like examples above (when their count is > 0).

• I tried to use this functionality just now because I needed it. I wanted to find usages of golang.org/x/mobile/gl.BufferData and it would've been very useful if I could do it via this feature.

  Without it, I had to rely on finding entire packages that imported golang.org/x/mobile/gl. Luckily, there were only four, one of them was golang.org/x/mobile/example/basic, and that package had a usage example of gl.BufferData:

  var triangleData = f32.Bytes(binary.LittleEndian,
      0.0, 0.4, 0.0, // top left
      0.0, 0.0, 0.0, // bottom left
      0.4, 0.0, 0.0, // bottom right
  )
  
  gl.BufferData(gl.ARRAY_BUFFER, gl.STATIC_DRAW, triangleData)

  It was very valuable to discover that f32.Bytes(binary.LittleEndian, ...) helper this way. This story is to motivate the usefulness of an easier way to find usage examples.

[vniche]

+1

[adg]

I think "Uses" might be a better word. I'm quite happy with the presentation though. WDYT @sqs ?

[Thomasdezeeuw]

Should Godoc start linking to sourcegraph.com? I use godoc offline a lot (in which sourcegraph won't work) and I don't think it should be added to Godoc, but that's just my opinion.

[sqs]

@adg "Uses" sounds better to me, too. Thanks!

@Thomasdezeeuw: Good point. Just to be make sure, you mean gddo not godoc, right? I can update this PR so that it either:

• only adds the "Uses" link for packages that have an underlying external, non-offline repository (github.com/..., gopkg.in/..., etc.); OR
• exposes a command-line flag to enable/disable the "Uses" link

Unless there is a clear preference either way (or other ideas), I will explore the first option and implement that if it is workable. If not, I'll implement the second option.

[Thomasdezeeuw]

@sqs yes, I do mean gddo. I think @adg should decide what the best course of action is.

[adg]

This seems okay to me. Sorry for taking so long to get to this.

We're using Gerrit now. Care to send a Gerrit review? This change needs to be rebased regardless. If not, then I can re-send this change through Gerrit myself.

[adg]

Timed out.

[sqs]

Actually, we are working on adding this now for all of the repositories we can crawl and making it much faster. Will post an update this week. Sorry for the delay.

On Apr 10, 2016, at 20:32, Andrew Gerrand notifications@github.com wrote:

Closed #259.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub

[adg]

@sqs will you send a Gerrit change? If so, this can remain closed.

[sqs]

Will do. 👍

On Apr 10, 2016, at 22:04, Andrew Gerrand notifications@github.com wrote:

@sqs will you send a Gerrit change? If so, this can remain closed.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub

[adg]

Much appreciated. Make sure you send it to adg@golang.org.