(PDOC-206) support for Puppet Tasks

Currently, puppet-strings does not know how to generate documentation
for Puppet Tasks. This does all the work to add support for Tasks
including a new JSON parser, a task handler, task statement, and task code
object. Basically, Strings reads the JSON using the native ruby json
parser and sends values through in a way it understands. It is only
passing json key/value pairs through, nothing is happening with tags at
this time. You can now document Tasks and generate HTML, Markdown, or
JSON output.

lib/puppet-strings/markdown/templates/puppet_task.erb

@@ -10,18 +10,8 @@
 <%= "The #{name} task." %>
 
 <% end -%>
-<% if supports_noop || input_method -%>
-#### Input
+**Supports noop?** <%= supports_noop %>
 
-<% if input_method -%>
-Input method: <%= input_method %>
-
-<% end -%>
-<% if supports_noop -%>
-Supports noop? <%= supports_noop %>
-
-<% end -%>
-<% end -%>
 <% if params -%>
 #### Parameters
 

lib/puppet-strings/yard/code_objects/task.rb

@@ -59,11 +59,11 @@ def to_hash
       file: statement.file,
       line: statement.line,
       docstring: {
-        text: statement.json['description'],
+        text: statement.docstring,
         tags: parameters
       },
       source: statement.source,
-      supports_noop: statement.json['supports_noop'],
+      supports_noop: statement.json['supports_noop'] || false,
       input_method: statement.json['input_method']
     }
   end

lib/puppet-strings/yard/parsers/json/task_statement.rb

@@ -1,18 +1,15 @@
 module PuppetStrings::Yard::Parsers::JSON
   # Represents the Puppet Task statement.
   class TaskStatement
-    attr_reader :line, :comments, :comments_range, :json, :file, :source
+    attr_reader :line, :comments, :comments_range, :json, :file, :source, :docstring
 
     def initialize(json, source, file)
       @file = file
       @source = source
       @json = json
       @line = 0
       @comments_range = nil
-    end
-
-    def docstring
-      YARD::Docstring.new(json['description'] || "")
+      @docstring = YARD::Docstring.new(@json['description'])
     end
 
     def parameters
@@ -28,7 +25,7 @@ def show
     end
 
     def comments
-      ""
+      docstring.all
     end
 
     def name

lib/puppet-strings/yard/templates/default/puppet_task/html/input.erb

@@ -1,11 +1,5 @@
 <% if json['input_method'] || json['supports_noop'] %>
 <div class="tags">
-  <p class="tag_title"> Input </p>
-  <ul>
-    <% if json['input_method'] %>
-        <li> Input method: <%= json['input_method'] %> </li>
-    <% end %>
-        <li> Supports noop? <%= json['supports_noop'] ? "true" : "false" %></li>
-  </ul>
+    <p><strong>Supports noop?</strong> <%= json['supports_noop'] ? "true" : "false" %></p>
 </div>
 <% end %>

spec/fixtures/unit/json/output.json

@@ -642,7 +642,7 @@
         ]
       },
       "source": "{\n  \"description\": \"Allows you to backup your database to local file.\",\n  \"input_method\": \"stdin\",\n  \"parameters\": {\n    \"database\": {\n      \"description\": \"Database to connect to\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"user\": {\n      \"description\": \"The user\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"password\": {\n      \"description\": \"The password\",\n      \"type\": \"Optional[String[1]]\"\n    },\n     \"sql\": {\n      \"description\": \"Path to file you want backup to\",\n      \"type\": \"String[1]\"\n    }\n  }\n}\n",
-      "supports_noop": null,
+      "supports_noop": false,
       "input_method": "stdin"
     }
   ]

spec/fixtures/unit/markdown/output.md

@@ -15,6 +15,8 @@
 * [`func3x`](#func3x): Documentation for an example 3.x function.
 * [`func4x`](#func4x): An example 4.x function.
 * [`func4x_1`](#func4x_1): An example 4.x function with only one signature.
+## Tasks
+* [`(stdin)`](#(stdin)): Allows you to backup your database to local file.
 ## Classes
 
 ### klass
@@ -381,3 +383,37 @@ Data type: `Integer`
 
 The first parameter.
 
+## Tasks
+
+### (stdin)
+
+Allows you to backup your database to local file.
+
+**Supports noop?** false
+
+#### Parameters
+
+##### `database`
+
+Data type: `Optional[String[1]]`
+
+Database to connect to
+
+##### `user`
+
+Data type: `Optional[String[1]]`
+
+The user
+
+##### `password`
+
+Data type: `Optional[String[1]]`
+
+The password
+
+##### `sql`
+
+Data type: `String[1]`
+
+Path to file you want backup to
+

spec/unit/puppet-strings/yard/code_objects/task_spec.rb

@@ -46,27 +46,42 @@
 
   describe '#to_hash' do
     let(:expected) do
-      { :name => "test",
-        "description" => "Allows you to backup your database to local file.",
-        "input_method" => "stdin",
-        "parameters" =>
-        {"database" => {
-            "description" => "Database to connect to",
-            "type" => "Optional[String[1]]"
-          },
-          "user"=> {
-            "description"=>"The user",
-            "type"=>"Optional[String[1]]"
-          },
-          "password"=> {
-            "description"=>"The password",
-            "type"=>"Optional[String[1]]"
-          },
-          "sql"=> {
-            "description"=>"Path to file you want backup to",
-            "type"=>"String[1]"
-          }
-        }
+      {
+        :name => "test",
+        :supports_noop => false,
+        :docstring => {
+          :text=>"Allows you to backup your database to local file.",
+          :tags=> [
+            {
+              :name=>"database",
+              :tag_name=>"param",
+              :text=>"Database to connect to",
+              :types=> ["Optional[String[1]]"]
+            },
+            {
+              :name=>"user",
+              :tag_name=>"param",
+              :text=>"The user",
+              :types=> ["Optional[String[1]]"]
+            },
+            {
+              :name=>"password",
+              :tag_name=>"param",
+              :text=>"The password",
+              :types=> ["Optional[String[1]]"]
+            },
+            {
+              :name=>"sql",
+              :tag_name=>"param",
+              :text=>"Path to file you want backup to",
+              :types=>["String[1]"]
+            }
+          ]
+        },
+        :file => "test.json",
+        :input_method => "stdin",
+        :line => 0,
+        :source => "{\n  \"description\": \"Allows you to backup your database to local file.\",\n  \"input_method\": \"stdin\",\n  \"parameters\": {\n    \"database\": {\n      \"description\": \"Database to connect to\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"user\": {\n      \"description\": \"The user\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"password\": {\n      \"description\": \"The password\",\n      \"type\": \"Optional[String[1]]\"\n    },\n     \"sql\": {\n      \"description\": \"Path to file you want backup to\",\n      \"type\": \"String[1]\"\n    }\n  }\n}\n"
       }
     end
 

spec/unit/puppet-strings/yard/parsers/json/parser_spec.rb

@@ -64,7 +64,7 @@ class foo {
       subject.parse
       expect(subject.enumerator.size).to eq(1)
       statement = subject.enumerator.first
-      expect(statement).to be_instance_of(Hash)
+      expect(statement).to be_instance_of(PuppetStrings::Yard::Parsers::JSON::TaskStatement)
     end
   end
 end

spec/unit/puppet-strings/yard/parsers/json/task_statement_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+describe PuppetStrings::Yard::Parsers::JSON::TaskStatement do
+  let(:source) { <<-SOURCE
+{
+  "description": "Allows you to backup your database to local file.",
+  "input_method": "stdin",
+  "parameters": {
+    "database": {
+      "description": "Database to connect to",
+      "type": "Optional[String[1]]"
+    },
+    "user": {
+      "description": "The user",
+      "type": "Optional[String[1]]"
+    },
+    "password": {
+      "description": "The password",
+      "type": "Optional[String[1]]"
+    },
+     "sql": {
+      "description": "Path to file you want backup to",
+      "type": "String[1]"
+    }
+  }
+}
+SOURCE
+  }
+  let(:json) { JSON.parse(source) }
+  subject { PuppetStrings::Yard::Parsers::JSON::TaskStatement.new(json, source, "test.json") }
+  describe '#comments' do
+    it 'returns docstring' do
+      expect(subject.comments).to eq "Allows you to backup your database to local file."
+    end
+  end
+  describe '#parameters' do
+    context 'with params' do
+      it 'returns params' do
+        expect(subject.parameters.size > 0).to be true
+      end
+    end
+    context 'no params' do
+      let(:source) { <<-SOURCE
+{
+  "description": "Allows you to backup your database to local file.",
+  "input_method": "stdin"
+}
+SOURCE
+      }
+      it 'returns an empty hash' do
+        expect(subject.parameters).to eq({})
+      end
+    end
+  end
+
+end