There must be one and only one newline after each documentation eleme…

…nt. (#336)

Merged PR #336.

products/compute/terraform.yaml

@@ -506,42 +506,41 @@ overrides: !ruby/object:Provider::ResourceOverrides
         custom_expand: templates/terraform/custom_expand/route_gateway.erb
         # Description here is overridden because puppet won't compile if you ask
         # it to include docs greater than 80 characters.
-        description: |
+        description: |+
           URL to a gateway that should handle matching packets.
-
           Currently, you can only specify the internet gateway, using a full or
           partial valid URL:
-
-          * https://www.googleapis.com/compute/v1/projects/project/global/gateways/default-internet-gateway
-          * projects/project/global/gateways/default-internet-gateway
-          * global/gateways/default-internet-gateway
-          You can also provide the string 'default-internet-gateway'.
+          * `https://www.googleapis.com/compute/v1/projects/project/global/gateways/default-internet-gateway`
+          * `projects/project/global/gateways/default-internet-gateway`
+          * `global/gateways/default-internet-gateway`
+          * The string `default-internet-gateway`.
+          
       nextHopInstance: !ruby/object:Provider::Terraform::PropertyOverride
         diff_suppress_func: 'compareSelfLinkOrResourceName'
         custom_expand: templates/terraform/custom_expand/route_instance.erb
         # Description here is overridden because puppet won't compile if you ask
         # it to include docs greater than 80 characters.
-        description: |
+        description: |+
           URL to an instance that should handle matching packets.
           You can specify this as a full or partial URL. For example:
-
-          * https://www.googleapis.com/compute/v1/projects/project/zones/zone/instances/instance
-          * projects/project/zones/zone/instances/instance
-          * zones/zone/instances/instance
-          You can also provide just the instance name, with the zone in
-          `next_hop_instance_zone`.
+          * `https://www.googleapis.com/compute/v1/projects/project/zones/zone/instances/instance`
+          * `projects/project/zones/zone/instances/instance`
+          * `zones/zone/instances/instance`
+          * Just the instance name, with the zone in `next_hop_instance_zone`.
+          
       tags: !ruby/object:Provider::Terraform::PropertyOverride
         custom_expand: templates/terraform/custom_expand/set_to_list.erb
         is_set: true
     custom_code: !ruby/object:Provider::Terraform::CustomCode
       decoder: templates/terraform/decoders/route.erb
       extra_schema_entry: templates/terraform/extra_schema_entry/route.erb
     docs: !ruby/object:Provider::Terraform::Docs
-      optional_properties: |
+      optional_properties: |+
           * `next_hop_instance_zone` - (Optional when `next_hop_instance` is
             specified)  The zone of the instance specified in
             `next_hop_instance`.  Omit if `next_hop_instance` is specified as
             a URL.
+
   Snapshot: !ruby/object:Provider::Terraform::ResourceOverride
     exclude: true
   SslCertificate: !ruby/object:Provider::Terraform::ResourceOverride

templates/terraform/property_documentation.erb

@@ -1,10 +1,11 @@
+
 * `<%= Google::StringUtils.underscore(property.name) -%>` -
 <% if property.required -%>
   (Required)
 <% elsif !property.output -%>
   (Optional)
 <% end -%>
-<%= indent(property.description.strip, 2) -%>
+<%= indent(property.description.strip.gsub("\n\n", "\n"), 2) -%>
 <% if property.is_a?(Api::Type::NestedObject) || (property.is_a?(Api::Type::Array) && property.item_type.is_a?(Api::Type::NestedObject)) -%>
   Structure is documented below.
 <% end -%>

templates/terraform/resource.html.markdown.erb

@@ -12,6 +12,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 <% end -%>
+<%# NOTE NOTE NOTE
+    The newlines in this file are *load bearing*.  This file outputs
+    Markdown, which is extremely sensitive to newlines.  You have got
+    to have a newline after every attribute and property, because
+    otherwise MD will think the next element is part of the previous
+    property's bullet point.  You cannot have any double newlines in the
+    middle of a property or attribute, because MD will think that the
+    empty line ends the bullet point and the indentation will be off.
+    You must have a newline before and after all --- document indicators,
+    and you must have a newline before and after all - - - hlines.
+    You cannot have more than one blank line between properties.
+    The --- document indicator must be the first line of the file.
+    As long as you only use `build_property_documentation`, it all works
+    fine - but when you need to add custom docs (notes, etc), you need
+    to remember these things.
+
+    Know also that the `lines` function in heavy use in MagicModules will
+    strip exactly one trailing newline - unless that's what you've designed
+    your docstring for, it's easier to insert newlines where you need them
+    manually.  That's why, in this file, we use `lines` on anything which
+    is generated from a ruby function, but skip it on anything that is
+    directly inserted from YAML.
+-%>
 <%
   api_name_lower = product_ns.downcase
   resource_name = Google::StringUtils.underscore(object.name)
@@ -50,25 +73,23 @@ To get more information about <%= object.name -%>, see:
 
 <% unless object.examples.nil? -%>
 ## Example Usage
+<%= "\n" + object.examples -%>
 
-<%= object.examples  -%>
 <% end -%>
-
 ## Argument Reference
 
 The following arguments are supported:
 
 <% properties.select(&:required).each do |prop| -%>
 <%= lines(build_property_documentation(prop)) -%>
 <% end -%>
-
 <% properties.select(&:required).each do |prop| -%>
 <%= lines(build_nested_property_documentation(prop)) -%>
 <% end -%>
-
 <%- unless object.docs.required_properties.nil? -%>
-<%= lines(object.docs.required_properties) -%>
+<%= "\n" + object.docs.required_properties -%>
 <% end -%>
+
 - - -
 
 <% properties.reject(&:required).reject(&:output).each do |prop| -%>
@@ -82,10 +103,10 @@ The following arguments are supported:
 <% properties.reject(&:required).reject(&:output).each do |prop| -%>
 <%= lines(build_nested_property_documentation(prop)) -%>
 <% end -%>
-
 <%- unless object.docs.optional_properties.nil? -%>
-<%= lines(object.docs.optional_properties) -%>
+<%= "\n" + object.docs.optional_properties -%>
 <% end -%>
+
 ## Attributes Reference
 
 In addition to the arguments listed above, the following computed attributes are exported:
@@ -100,10 +121,10 @@ In addition to the arguments listed above, the following computed attributes are
 <% properties.select(&:output).each do |prop| -%>
 <%= lines(build_nested_property_documentation(prop)) -%>
 <% end -%>
-
 <%- unless object.docs.attributes.nil? -%>
-<%= lines(object.docs.attributes) -%>
+<%= "\n" + object.docs.attributes -%>
 <% end -%>
+
 <% unless object.async.nil? -%>
 ## Timeouts