JavaDocs should explain the products rather than just say they are clients for...

[lesv]

http://googlecloudplatform.github.io/google-cloud-java/0.20.0/apidocs/

Take the one line Marketing summary and put it as a description.

Currently:

Class	Description
com.google.cloud	Core classes for the google-cloud library.
com.google.cloud.bigquery	A client to Google Cloud BigQuery.
com.google.cloud.bigquery.spi.v2
com.google.cloud.compute	A client to Google Cloud Compute.
com.google.cloud.compute.spi.v1
com.google.cloud.datastore	A client to the Google Cloud Datastore.
com.google.cloud.datastore.spi.v1
com.google.cloud.dns	A client to the Google Cloud DNS.
com.google.cloud.dns.spi.v1

Suggested:

Class	Description
com.google.cloud	Core classes for the google-cloud library.
com.google.cloud.bigquery	Bigquery – A fast, economical and fully-managed enterprise data warehouse for large-scale data analytics
com.google.cloud.bigquery.spi.v2
com.google.cloud.compute	Compute – Scalable, High-Performance Virtual Machines
com.google.cloud.compute.spi.v1
com.google.cloud.datastore	Datastore – Cloud Datastore is a highly-scalable NoSQL database for your web and mobile applications
com.google.cloud.datastore.spi.v1
com.google.cloud.dns	Cloud DNS - Reliable, resilient, low-latency DNS serving from Google’s worldwide network
com.google.cloud.dns.spi.v1

[garrettjonesgoogle]

Why? These are clients for those services...

[lesv]

It helps people discover that we have those services. (They might not have found it otherwise)

[garrettjonesgoogle]

I don't think it's the responsibility of the client libraries to tell people what GCP services are available...

[jabubake]

Agree with Les on making these more informative. To the user who arrives at the page, it is our opportunity to inform users of the existing services without bouncing off to search for what that is.

[lesv]

Let's talk about this - this afternoon.

[garrettjonesgoogle]

Resolved offline: the longer descriptions are fine, but retain the "A client for" at the beginning.

[garrettjonesgoogle]

@lesv : what about auto-generated clients? We don't have these descriptions in config anywhere, so we'd have to add it upstream and regenerate.

[lesv]

Yes - I think that's what we should do. Ideally we can ask that the eng's do that in their Proto's. (or some config file)

[yihanzhen]

Move this issue to feature backlog: https://github.com/GoogleCloudPlatform/google-cloud-java/wiki/Feature-backlog and close it here. The issue can continue to be used for comment and discussion.