No documentation for many auto generated types.

[bmenasha]

There is no documentation for the fields of the

google.cloud.monitoring_v3.types.MetricDescriptor
google.cloud.monitoring_v3.types.MessageOptions
(and many others)

in the generated docmentation here:

https://google-cloud-python.readthedocs.io/en/latest/monitoring/gapic/v3/types.html

Or consider

google.cloud.redis_v1beta1.types.Operation

in

https://google-cloud-python.readthedocs.io/en/latest/redis/gapic/v1beta1/types.html

These classes have fields that are generated from protobuf messages yet there is no documentation.

My attempts to use auto completion in common IDEs like pycharm, visual studio code, emacs's elpy all fail. Is there an IDE that does auto completion successfully on these types I can use?

Thanks

[tseaver]

@bmenasha Thanks for the report. PR googleapis/google-cloud-python#5364 made a change such that shared types (such as google.longrunning.operation_pb2.Operation no longer have their modules overwritten. I argued (in issue googleapis/google-cloud-python#4715) that overwriting them even for "local" types was wrong: your report that it breaks IDE code completion is a telling point there.

WRT the docstrings: I can see that, for instance, google.api.metric.MetricDescriptor has a least a one-line comment which should be carried over into the generated code, ISTM.

[bmenasha]

Well, I can't get auto completion working with any of pycharm, elpy, or vscode for the auto generated classes in google.api.metric_pb2 either.

While docstring would be nice. I'm primary complaining about the lack of any fields on these types in any python documentation I can find. The only way to determine what fields exists is to read protobuf definitions or examine the type at runtime with help(). This is all fine by me because I expect everything to be hard, but some developers might expect our client library documentation to document the interface.

thanks for the quick reply.

[tseaver]

@bmenasha I can see the "empty" types you reference here.

@theacodes Is this an issue we should be solving in the codegen side?

[tseaver]

/cc @lukesneeringer Can you suggest a way we could get docs generating properly for the "common" API proto messages?

[bmenasha]

Even for those types which aren't "common" our documentation is poor.

Consider the new cloud asset API. We expose: export_assets() which accepts a output_config. We document this here https://googleapis.github.io/google-cloud-python/latest/asset/gapic/v1beta1/types.html#google.cloud.asset_v1beta1.types.OutputConfig with:

class google.cloud.asset_v1beta1.types.OutputConfig
    Output configuration for export assets destination.
        destination
            Asset export destination.
        gcs_destination
            Destination on Cloud Storage. 

What's the type of gcs_destionation? a string? why both "destination" and gcs_destionatoin" who knows! I'm back to reading autogenerated python protobuf source for this.

Here is the protobuf definition for this type:

// Output configuration for export assets destination.
message OutputConfig {
  // Asset export destination.
  oneof destination {
    // Destination on Cloud Storage.
    GcsDestination gcs_destination = 1;
  }
}

What is this "oneof", Doesn't seem to make sense to use oneof for a single field. right? It produces confusing documentation and users.

thanks

[meredithslota]

I think maybe this issue should be moved to the python microgenerator repo, but I don't have permission to do that. @AlanGasperini thoughts?