search

googleapis / google-cloud-java

Google Cloud Client Library for Java
https://cloud.google.com/java/docs/reference
Apache License 2.0
1.89k stars 1.06k forks source link

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

Closed lesv closed 6 years ago

lesv commented 7 years ago

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

Why? These are clients for those services...

lesv commented 7 years ago

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

garrettjonesgoogle commented 7 years ago

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

jabubake commented 7 years ago

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

Let's talk about this - this afternoon.

garrettjonesgoogle commented 7 years ago

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

garrettjonesgoogle commented 7 years ago

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

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

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.