(maint) clarify language around composite namevars

Author: DavidS

language/resource-api/README.md

@@ -77,7 +77,6 @@ Each resource being managed must be identified by a unique title. Usually this i
 
 If multiple attributes are defined with the `namevar` behaviour, the type SHOULD specify `title_patterns` that will tell Resource API how to get at the attributes from the title. If `title_patterns` is not specified a default pattern is applied, and matches against the first declared `namevar`.
 
-
 > Note: The order of title_patterns is important. You should declare the most specific pattern first and end with the most generic.
 
 Each title pattern contains the:
@@ -143,6 +142,8 @@ software { php:
 }
 ```
 
+The provider's `get` method should return a single formatted string representing all namevar values in such a way that it matches one of the title patterns as value to the `:title` key for each resource. This allows the runtime environment to present resources in a way familiar to the user.
+
 ## Resource implementation ("provider")
 
 To affect changes, a resource requires an implementation that makes the universe's state available to Puppet, and causes the changes to bring reality to whatever state is requested in the catalog. The two fundamental operations to manage resources are reading and writing system state. These operations are implemented as `get` and `set`. The implementation itself is a basic Ruby class in the `Puppet::Provider` namespace, named after the type using CamelCase.
@@ -209,17 +210,17 @@ Once all of that is in place, instead of the `set` method, the provider needs to
 
 * `create(context, name, should)`: This is called when a new resource should be created.
   * `context`: provides utilities from the runtime environment, and is described in more detail in its own section below.
-  * `name`: the name or hash of the new resource.
+  * `name`: the name (if there is only one namevar) or hash of namevars (if there are multiple) of the new resource.
   * `should`: a hash of the attributes for the new instance.
 
 * `update(context, name, should)`: This is called when a resource should be updated.
   * `context`: provides utilities from the runtime environment, and is described in more detail in its own section below.
-  * `name`: the name or hash of the resource to change.
+  * `name`: the name (if there is only one namevar) or hash of namevars (if there are multiple) of the new resource.
   * `should`: a hash of the desired state of the attributes.
 
 * `delete(context, name)`: This is called when a resource should be deleted.
   * `context`: provides utilities from the runtime environment, and is described in more detail in its own section below.
-  * `name`: the name or hash of the resource that should be deleted.
+  * `name`: the name (if there is only one namevar) or hash of namevars (if there are multiple) of the new resource.
 
 The `SimpleProvider` takes care of basic logging, and error handling.