DatastoreDb.Insert() sometimes returns null.

[SurferJeffAtGoogle]

The documentation describes the behavior correctly:
https://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Datastore.V1/api/Google.Cloud.Datastore.V1.DatastoreDb.html#Google_Cloud_Datastore_V1_DatastoreDb_Insert_Google_Cloud_Datastore_V1_Entity_Google_Api_Gax_Grpc_CallSettings_

But I found this behavior confusing.
https://github.com/GoogleCloudPlatform/dotnet-docs-samples/blob/master/datastore/api/TaskListTest/DatastoreTest.cs#L223

Why not always return the key?

[jskeet]

The test is certainly confusing and needs changing.

The behaviour matches the underlying API, however - I would be somewhat reluctant to completely mask that, both for consistency with other platforms and because it may well be useful behaviour. (Aside from anything else, it would be odd for a user to read the API documentation and then get very different behaviour from the library.)

@pcostell Do you have examples of where it's particularly useful to distinguish between allocated keys and client-provided keys? If we could add something into our library docs, that would be great.

[jskeet]

Ah, I hadn't noticed that the test is in your samples rather than in my repo :) I would take issue of your claim of "should" in the test, as the code is behaving exactly as documented.

[jskeet]

Ping for further input from @SurferJeffAtGoogle or @pcostell.

(Marked as release blocking because changing it later would be a breaking change.)

[pcostell]

I believe this is just for reduced network traffic. There is no need for us to tell you about the keys you already know about.

From the user point of view, there isn't really any difference between the two. Where it can be important is if you do some sort of:

a = EntityWithIncompleteKey()
commit(a)
a.foo = "bar"
commit(a)

You'll end up accidentally creating two entities, rather than 1. Most of our libraries have modified commit so that when you call commit(a) it will mutate a to store the key. That way, later modifications to a will ensure it is the same entity.

[jskeet]

Just reopening for now - the "most of our libraries" comment from Patrick sounds like it may be something we want to do... although of course it makes for interesting things around asynchrony.

Jeffrey: I'm assuming your closing aspect was around the returning of the keys? Do you think you'd expect and/or like the entities to be mutated after commit? (It feels slightly surprising to me, but I can see it being handy.) If we're happy on the return front but want to explore the mutation side, I'll create a separate issue for that.

[jskeet]

Reclosing this, so a new issue can focus on whether to update key properties.