Add documentation for the new event functions

Author: jskeet

README.md

@@ -59,43 +59,58 @@ dotnet new gcf-event
 ```
 
 That will create the same set of files as before, but the `Function`
-class now implements `ICloudEventFunction`. This is a function that
-responds to [CNCF Cloud Events](https://cloudevents.io/). The procedure
-for running a Cloud Event Function is exactly the same as for an
-HTTP Function.
-
-## Legacy Event Functions
-
-Google Cloud Functions support for events predates the CNCF Cloud
-Events initiative. "Legacy" event functions handle these events via
-the `ILegacyEventFunction<T>` type. The type parameter `T`
-represents the payload type of the event. Any class type that can be
-deserialized via `System.Text.Json` can be used, but the Functions
-Framework for .NET comes with the following payload types built-in,
-all within the `Google.Cloud.Functions.LegacyEvents` namespace:
-
-- `StorageObject` for Google Cloud Storage events
-- `FirestoreEvent` for Cloud Firestore events
-- `PubSubMessage` for Cloud Pub/Sub messages
-
-See the Google Cloud Functions ["Events and Triggers"
-documentation](https://cloud.google.com/functions/docs/concepts/events-triggers)
-for more information about the triggers available.
+class now implements `ICloudEventFunction<StorageObject>`. This is a
+function that responds to [CNCF Cloud
+Events](https://cloudevents.io/), expecting data corresponding to a
+Google Cloud Storage object. If you deploy the function with a
+trigger of `google.storage.object.finalize` and then upload a new
+object to Google Cloud Storage, the sample event will log the
+details of the new event, including some properties of the storage
+object.
+
+The procedure for running a Cloud Event Function is exactly the same
+as for an HTTP Function.
+
+The type argument to the generic `ICloudEventFunction<TData>` interface
+expresses the type of data your function expects within the
+CloudEvent. This is deserialized using System.Text.Json
+deserialization: you can specify any type, so long as
+it can be deserialized appropriately from the Cloud Event data
+attribute.
+
+> **Note:**  
+> Google Cloud Functions support for events predates the CNCF Cloud
+> Events initiative. The types in the `Google.Cloud.Functions.Framework.GcfEvents`
+> namespace provide payloads for these events. The Functions Framework
+> converts the Google Cloud Functions representation into a Cloud Event
+> representation transparently, so as a developer you only need to
+> handle Cloud Events.
+
+### Untyped Cloud Event Functions
+
+If you are experimenting with Cloud Events and don't yet have a
+payload data model you wish to commit to, or you want your function
+to be able to handle *any* CloudEvent, you can implement the
+non-generic `ICloudEventFunction` interface. Your function's method
+will then just be passed a `CloudEvent`, with no separate data object.
 
 After installing the template package described earlier, use the
-`gcf-legacy-event` template:
+`gcf-untyped-event` template:
 
 ```sh
-mkdir HelloLegacyEvents
-cd HelloLegacyEvents
-dotnet new gcf-legacy-event
+mkdir HelloUntypedEvents
+cd HelloUntypedEvents
+dotnet new gcf-untyped-event
 ```
 
-This will create a legacy event function consuming Google Cloud
-Storage events. If you deploy the function with a trigger of
-`google.storage.object.finalize` and then upload a new object to
-Google Cloud Storage, the sample event will log the details of the
-new event, including some properties of the storage object.
+This will create a function that simply logs the information about
+any Cloud Event it receives.
+
+> **Note:**  
+> The automatic conversion of Google Cloud Functions events to
+> Cloud Events only happens for typed Cloud Event functions. Untyped
+> Cloud Event functions only succeed when the underlying HTTP request
+> contains a Cloud Event.
 
 ## VB and F# support