(maint) fix desc/docs confusion

The text and examples have been inconsistent with how `desc` vs `docs`
has been handled. This change fixes the text and examples to all show
and require `desc`, but accept `docs` in places where we showed it
previously.

Author: DavidS

language/resource-api/README.md

@@ -56,7 +56,7 @@ Puppet::ResourceApi.register_type(
 The `Puppet::ResourceApi.register_type(options)` function takes the following keyword arguments:
 
 * `name`: the name of the resource type.
-* `desc`: a doc string that describes the overall working of the resource type, provides examples, and explains prerequisites and known issues.
+* `desc`: a doc string that describes the overall working of the resource type, provides examples, and explains prerequisites and known issues. Can also be written as `docs` for backwards compatibility. This compatibility option will go away in the next major revision.
 * `attributes`: a hash mapping attribute names to their details. Each attribute is described by a hash containing the Puppet 4 data `type`, a `desc` string, a `default` value, and the `behaviour` of the attribute: `namevar`, `read_only`, `init_only`, or a `parameter`.
   * `type`: the Puppet 4 data type allowed in this attribute.
   * `desc`: a string describing this attribute. This is used in creating the automated API docs with [puppet-strings](https://github.com/puppetlabs/puppet-strings).
@@ -90,7 +90,7 @@ Example:
 # lib/puppet/type/software.rb
 Puppet::ResourceApi.register_type(
   name: 'software',
-  docs: <<-DOC,
+  desc: <<-DOC,
     This type provides Puppet with the capabilities to manage ...
   DOC
   title_patterns: [