Add docstring with example of signing a URL

[jgeewax]

The change in #77 added the ability to sign a URL, but I don't see a docstring and example of how we'd use this. See https://github.com/GoogleCloudPlatform/gcloud-node/blob/master/lib/storage/file.js#L1010 for a comparable example.

[aozarov]

You mean more than the method's javadoc: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-storage/src/main/java/com/google/gcloud/storage/StorageService.java#L604
and this example: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/StorageExample.java#L487 ?

[aozarov]

Also, consider the specific option's javadoc associated with each SignUrlOption.

[jgeewax]

Shouldn't we have examples in the docstring ? Like we do for other libraries?

If we're going to auto-generate documentation pages like we do for gcloud- I'd expect we need the examples in there, right?

[aozarov]

Examples in method's Javadoc is not a common thing to do in Java (see this) . It is more typical to have some usage examples in the package-info and when applicable in a class javadoc (e.g.).

We don't have to follow this convention but I am not sure if that is a right decision. I did plan to add more examples in the package-info and class level javadoc once we finalize on the API but not more than that.

If you still think we should add examples per method in the main service API then we should rename this issue or create a new one more generic such as "add usage examples per method for every main service API"

[jgeewax]

I'm looking at things like Guice's MapBinder which generates pretty Javadocs using Doclava I think. It's including examples right up front of how you use the class...

This fits in closely with what we're doing in other languages. I don't see how we're going to be able to take the examples package of Java code and turn that into useful documentation for people in a web browser.

[aozarov]

No, this is still a class level javadoc (which I mentioned I plan to add). Clearly a class level javadoc normally does not cover all public methods it provides (including in your more trivial example). It is more about how to start using the class + basic usage.

Considering your particular method reference example I agree that it is much more needed when a language is non typed and the only param info is "options". In the Java case, all parameters for a function are typed and each one is documented (and any specific type such as SignUrlOption is documented as well). I think that in this case the equivalent example:

// create a signed url for 2 weeks
service.signUrl(Blob.of("b", "n"), System.currentTimeMillis() / 1000 +  (60 * 60 * 24 * 14))

is nice but not necessity.

As said, if you feel strongly about it feel free to create a more generic issue and we can get some more feedback about it.

[aozarov]

I am closing this issue (as it is not specific to the associated pull request or method).
Please create a separate one for adding method level examples for service interfaces if you are
still convinced that it should be done.

[jgeewax]

Based on our conversation the other day, the thought was "we should only add snippets if they're useful". So... the request is two-fold:

1. Decide whether it's useful to add a short snippet example of how you'd use this particular function
2. If it's useful, decide what that snippet should look like

Re-opening to discuss those things...

[aozarov]

I am going over issue and doing some cleanup.

Though I still don't feel that a snippet to Storage.signUrl method is necessary I rather
add it and close this issue.

@jgeewax what do you think about following (the addition is starting from "From example")?

/**
 Generates a signed URL for a blob.

 If you have a blob that you want to allow access to for a fixed amount of time, you can use this
 method to generate a URL that is only valid within a certain time period.
 This is particularly useful if you don't want publicly accessible blobs, but don't want to require users
 to explicitly log in.
 For example, to create a signed URL that is valid for 2 weeks you can do:
{@code
  service.signUrl(BlobInfo.of("bucket", "name"), TimeUnit.DAYS.toSeconds(14));
}
*/

[jgeewax]

I am hugely in favor of adding that snippet. That makes the method much much clearer to me. 👍

@mziccard, thoughts?

[mziccard]

It might not be common in the java world to have snippets in the docs but I still think they can be very useful for new users. To do simple stuff, relying solely on the javadocs and type information can be overly frustrating and time-consuming.

So 👍 :)