feat(generator/dart): emit enums

[devoncarew]

Update the dart generator to emit enums:

• update the templates to emit enums
• update the templates to traverse into nested messages and enums
• general work towards bootstrap a dart backend for sidekick #1034

This uses Dart classes to represent enums instead of actual language enums. I assume this will work better with unknown values coming over the wire. And I'm assuming enum values over the wire will be represented by their int values (and not something like their SCREAMING_CAPS string name).

I'm using '$' to concatenate nested messages and enums. '_' and '' are also reasonable; nothing's particularly idiomatic. Perhaps shorter names could be used if we determine there are no namespace conflicts in a library?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.89%. Comparing base (9feaaa2) to head (a52a077).
Report is 18 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1082   +/-   ##
=======================================
  Coverage   95.89%   95.89%           
=======================================
  Files          34       34           
  Lines        1365     1365           
=======================================
  Hits         1309     1309           
  Misses         56       56           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[coryan]

This uses Dart classes to represent enums instead of actual language enums. I assume this will work better with unknown values coming over the wire. And I'm assuming enum values over the wire will be represented by their int values (and not something like their SCREAMING_CAPS string name).

That depends on the transport. Over HTTP+JSON (which is what we are targeting for Rust) the enums are indeed strings. Over gRPC + Protobuf the enums are ints. For most services we want to target HTTP+JSON. See go/cloud-sdk-new-languages and go/coryan:the-next-8. Even for services where we use gRPC and Protobuf: this usage should remain hidden from application developers.

I'm using '$' to concatenate nested messages and enums. '_' and '' are also reasonable; nothing's particularly idiomatic.

Your call then, I have no idea what would be considered "better" in Dart-world.

Perhaps shorter names could be used if we determine there are no namespace conflicts in a library?

I would discourage that: consider what happens when a library adds a type that creates a conflict. We wish to make such changes non-breaking. If we get clever with the names the change would be breaking I think.

[coryan]

I think we need to change these to use strings. Otherwise, the code is looking good. Nice tests too.

[coryan]

FYI: eventually we will need to define these cross-reference comments, the output will need to be something like:

Suggested change

	/// The state of a
	/// [SecretVersion][google.cloud.secretmanager.v1.SecretVersion], indicating if
	/// it can be accessed.
	/// The state of a
	/// [SecretVersion][google.cloud.secretmanager.v1.SecretVersion], indicating if
	/// it can be accessed.
	///
	/// [google.cloud.secretmanager.v1.SecretVersion]: /* the Dart way to link to the `SecretVersion` class */

There is a lot of prior art in the Rust codec, and probably some opportunities for refactoring.

[devoncarew]

+1, I'd like to clean up the comments here (for dart, called doc comments).

Assuming the reference can be resolved in the namespace, this would be emitted as:

/// The state of a [SecretVersion], indicating if it can be accessed.

If we can't resolve the reference we'd do something like emit 'SecretVersion' in a code-fence - not tell the dart doc tool to try and resolve the ref.

[coryan]

TIL: Dart supports nested constants.

[devoncarew]

I think we need to change these to use strings.

Gotcha - I updated to use the string value (stateUnspecified = SecretVersion$State('STATE_UNSPECIFIED')).

I would discourage that: consider what happens when a library adds a type that creates a conflict. We wish to make such changes non-breaking. If we get clever with the names the change would be breaking I think.

Makes sense - preferring to generate stable output, and reducing unnecessary breaking API changes.