Add easy link from docs to the code

[jgeewax]

For the methods we have in our docs, is it possible to add a link to the code so that we don't have to click around trying to navigate from the docs for (say) datastore.save -> code for the method?

[lukesneeringer]

This would be a really nice feature. It does not look like something JSDoc supports out of the box. We could use @see but the GitHub links would have constantly changing line numbers, which would make maintenance tough.

I think we could write a plugin that could do this, however. The JSDoc AST already has enough information.

[stephenplusplus]

I think we have what you're looking for, but let me know if I misunderstand:

https://googlecloudplatform.github.io/google-cloud-node/#/docs/google-cloud/v0.55.0/datastore?method=save

[lukesneeringer]

So we do. I did not see that.

Would it be possible to change our template to have that be next to the header, rather than at the very bottom of a very long and drawn out explanation with multiple examples?

I am thinking along the lines of having it right-aligned right next to the name of the method.

[stephenplusplus]

Historic reason: #790 (comment)

We basically have a generic "put relevant links here" bucket-- at a minimum, they're supposed to contain:

• Source code link (always present)
• Upstream API reference breakdown of the object/method that's relevant (mostly present, when applicable)

Anything else, like links to guides from the official docs "Getting Started with _____", will go here as well.

[callmehiphop]

@stephenplusplus I think @lukesneeringer's suggestion is good, we can still put other links (upstream docs, etc.) at the bottom but maybe some smaller text next to the method name that says view source or similar.

[stephenplusplus]

I'm fine with it that way, or the way it is!

[stephenplusplus]

This issue was moved to GoogleCloudPlatform/gcloud-common#229

[stephenplusplus]

The positioning issue can be resolved in the common repo-- that's where the change would be made, and it would affect all of our libraries.