(PDOC-30) Fix Markdown parsing lists parsing

The transformer comment matching regex matched all whitespace after a comment.
Lines which were effectively "blank" and just had a comment would be erased.
Markdown lists need to end with a blank line. This messed up markdown
formatting.

The culprit is the regex /^\s*#\s/ which matches all of the comment ' #\n',
however we want to leave the newline alone for markdown to parse.
We replace the regex with /^\s*#[ \t]/ which will only match tabs or spaces
after the hash and leave our beloved newline alone.

lib/puppet_x/puppetlabs/strings/pops/yard_statement.rb

@@ -58,7 +58,14 @@ def extract_comments
         # FIXME: The gsub trims comments, but is extremely optimistic: It
         # assumes only one space separates the comment body from the
         # comment character.
-        comments.unshift line.gsub(/^\s*#\s/, '')
+        # NOTE: We cannot just trim any amount of whitespace as indentation
+        # is sometimes significant in markdown. We would need a real parser.
+
+        # Comments which begin with some whitespace, a hash and then some
+        # tabs and spaces should be scrubbed. Comments which just have a
+        # solitary hash then a newline should keep that newline since newlines
+        # are significant in markdown.
+        comments.unshift line.gsub(/^\s*#[\t ]/, '').gsub(/^\s*#\n/, "\n")
       else
         # No comment found on this line. We must be done piecing together a
         # comment block.

spec/unit/puppet_x/puppetlabs/strings/yard/defined_type_handler_spec.rb

@@ -32,7 +32,7 @@ def the_definedtype()
 
     parse(puppet_code, :puppet)
 
-    comment = "Definition: foo::bar\nThis class does some stuff"
+    comment = "Definition: foo::bar\n\nThis class does some stuff"
     expect(the_definedtype).to document_a(:type => :definedtype, :docstring => comment)
   end
 

spec/unit/puppet_x/puppetlabs/strings/yard/host_class_handler_spec.rb

@@ -31,7 +31,7 @@ class foo::bar { }
 
     parse(puppet_code, :puppet)
 
-    comment = "Class: foo::bar\nThis class does some stuff"
+    comment = "Class: foo::bar\n\nThis class does some stuff"
     expect(the_hostclass).to document_a(:type => :hostclass, :docstring => comment)
   end