Documenting Gapic/Proto (autogen files)

[callmehiphop]

Opening an issue to track discussion on how we should go about documenting GAX from within our library.

[callmehiphop]

My initial thoughts are that users who take advantage of GAX will be a bit more advanced. That being said, it might not be unreasonable to simply link them to the proto files being used? Then from within our library we can document the methods that expose said APIs v2, v1beta1, etc.

It also might benefit us to look into adding the feature discussed here - https://github.com/GoogleCloudPlatform/gcloud-common/issues/80

[stephenplusplus]

cc: @jmuk @jmdobry

Is it a requirement for us to display autogen docs, or is linking to proto files sufficient?

[jmdobry]

For now at least, I think linking to proto files is sufficient.

[jmuk]

Cc: @omaray

We want the documentation for GAX (i.e. LanguageServiceApi). The generated files are more language-idiomatic and serve methods with additional features such as parameter-flattening / page-streaming, that are not seen in the proto files. We will also add auto-generated usage samples to individual method.

[omaray]

Correct. We want the documentation of GAPIC/GAX to show. Not every API will have a handwritten layer (or at least at the beginning). So we want to show the docs of the auto-gen too.

[stephenplusplus]

Just tagging as these are related: https://github.com/GoogleCloudPlatform/gcloud-common/issues/207