Merge pull request puppetlabs#160 from eputnam/master

(PDOC-222) Release 1.2.0 prep and sundries

Author: DavidS

CHANGELOG.md

@@ -1,3 +1,21 @@
+# Change log
+
+All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org).
+
+## [1.2.0](https://github.com/puppetlabs/puppet-strings/tree/1.2.0) (2018-02-26)
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/1.1.1...1.2.0)
+
+### Added
+
+- \(PDOC-184\) generate markdown [\#156](https://github.com/puppetlabs/puppet-strings/pull/156) ([eputnam](https://github.com/eputnam))
+- \(PDK-437\) Add support for Resource API types [\#153](https://github.com/puppetlabs/puppet-strings/pull/153) ([DavidS](https://github.com/DavidS))
+
+### Fixed
+
+- Fix return type matching for Puppet functions [\#159](https://github.com/puppetlabs/puppet-strings/pull/159) ([pegasd](https://github.com/pegasd))
+- Add rgen as a runtime dependency [\#149](https://github.com/puppetlabs/puppet-strings/pull/149) ([rnelson0](https://github.com/rnelson0))
+
 ## 2017-10-20 - Release 1.1.1
 
 ### BugFixes
@@ -166,3 +184,6 @@ All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with t
 - Puppet namespaces are no longer mangled for nested classes and defined types **(PDOC-25)**
 - Strings is now compatible with the renaming of the Puppetx/puppetx namespace to PuppetX/puppet_x **(PDOC-26)**
 - Strings will no longer crash when documenting 3x functions with less than two arguments passed into newfunction **(PDOC-27)**
+
+
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*

README.md

@@ -463,6 +463,7 @@ function example(string $name) {
 
 ### Available Strings tags
 
+* `@api`: Describes the resource as private or public, most commonly used with classes or defined types.
 * `@example`: Shows an example snippet of code for an object. The first line is an optional title. See above for more about how to [include examples in documentation](#including-examples-in-documentation).
 * `@param`: Documents a parameter with a given name, type and optional description.
 * `@!puppet.type.param`: Documents dynamic type parameters. See [Documenting resource types and providers](#documenting-resource-types-and-providers) above.

lib/puppet-strings/tasks/generate.rb

@@ -3,7 +3,7 @@
 # Implements the strings:generate task.
 namespace :strings do
   desc 'Generate Puppet documentation with YARD.'
-  task :generate, :patterns, :debug, :backtrace, :markup, :json, :yard_args do |t, args|
+  task :generate, [:patterns, :debug, :backtrace, :markup, :json, :markdown, :yard_args] do |t, args|
     patterns = args[:patterns]
     patterns = patterns.split if patterns
     patterns ||= PuppetStrings::DEFAULT_SEARCH_PATTERNS
@@ -14,11 +14,30 @@
       markup: args[:markup] || 'markdown',
     }
 
-	# rubocop:disable Style/PreferredHashMethods
-	# `args` is a Rake::TaskArguments and has no key? method
-    options[:json] = args[:json] if args.has_key? :json
+    raise("Error: Both JSON and Markdown output have been selected. Please select one.") if args[:json] == 'true' && args[:markdown] == 'true'
+
+    # rubocop:disable Style/PreferredHashMethods
+    # Because of Ruby, true and false from the args are both strings and both true. Here,
+    # when the arg is set to false (or empty), set it to real false, else real true. Then,
+    # if the arg is set simply to 'true', assume default behavior is expected and set the path
+    # to nil to elicit that, else set to the path given.
+    # @param [Hash] args from the Rake task cli
+    # @param [Hash] options to send to the generate function
+    # @param [Symbol] possible format option
+    # @return nil
+    def parse_format_option(args, options, format)
+      if args.has_key? format
+        options[format] = args[format] == 'false' || args[format].empty? ? false : true
+        if options[format]
+          options[:path] = args[format] == 'true' ? nil : args[format]
+        end
+      end
+    end
+
+    [:json,:markdown].each { |format| parse_format_option(args, options, format) }
+
+    warn('yard_args behavior is a little dodgy, use at your own risk') if args[:yard_args]
     options[:yard_args] = args[:yard_args].split if args.has_key? :yard_args
-	# rubocop:enable Style/PreferredHashMethods
 
     PuppetStrings.generate(patterns, options)
   end

puppet-strings.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name = 'puppet-strings'
   s.author = 'Puppet Inc.'
-  s.version = '1.1.1'
+  s.version = '1.2.0'
   s.license = 'Apache-2.0'
   s.summary = 'Puppet documentation via YARD'
   s.email = 'info@puppet.com'