pax_global_header00006660000000000000000000000064133144622020014507gustar00rootroot0000000000000052 comment=9c4c7227d34a3a1edd913cdb471e1478a9b23acb puppet-strings-2.1.0/000077500000000000000000000000001331446220200145135ustar00rootroot00000000000000puppet-strings-2.1.0/.gitignore000066400000000000000000000005451331446220200165070ustar00rootroot00000000000000## MAC OS .DS_Store ## TEXTMATE *.tmproj tmtags ## EMACS *~ \#* .\#* ## VIM *.swp /tags ## BUNDLER .bundle Gemfile.lock ## YARD .yardoc .yardwarns ## MODULE BUILDS **/pkg ## RubyMine /.idea/ ## rvm/rbenv /.ruby-version ## YARD output /doc/ ## Acceptance test artifacts /log/ /*.gem /spec/acceptance/nodesets/ ## local coverage results /coverage/ puppet-strings-2.1.0/.rubocop.yml000066400000000000000000000205531331446220200167720ustar00rootroot00000000000000AllCops: Exclude: # Ignore HTML related things - '**/*.erb' - 'lib/puppet-strings/yard/templates/**/*' # DISABLED - not useful Bundler/OrderedGems: Enabled: false # DISABLED - Doesn't understand conditionals that result in different versions of a gem. Bundler/DuplicatedGem: Enabled: false Lint/ConditionPosition: Enabled: true Lint/ElseLayout: Enabled: true Lint/UnreachableCode: Enabled: true Lint/UselessComparison: Enabled: true # MAYBE useful - no return inside ensure block. Lint/EnsureReturn: Enabled: false # MAYBE useful - errors when rescue {} happens. Lint/HandleExceptions: Enabled: false # MAYBE useful - catches while 1 Lint/LiteralInCondition: Enabled: false # MAYBE useful - but too many instances Lint/ShadowingOuterLocalVariable: Enabled: false # Can catch complicated strings. Lint/LiteralInInterpolation: Enabled: true # DISABLED really useless. Detects return as last statement. Style/RedundantReturn: Enabled: false # DISABLED since the instances do not seem to indicate any specific errors. Lint/AmbiguousOperator: Enabled: false Lint/AssignmentInCondition: Enabled: true # DISABLED - not useful Style/SpaceBeforeComment: Enabled: false # DISABLED - not useful Style/HashSyntax: Enabled: false # USES: as shortcut for non nil&valid checking a = x() and a.empty? # DISABLED - not useful Style/AndOr: Enabled: false # DISABLED - not useful Style/RedundantSelf: Enabled: false # DISABLED - not useful Metrics/MethodLength: Enabled: false Metrics/ModuleLength: Enabled: false # DISABLED - not useful Style/WhileUntilModifier: Enabled: false # DISABLED Security/Eval: Enabled: false # DISABLED - the offender is just haskell envy Lint/AmbiguousRegexpLiteral: Enabled: false # DISABLED Lint/BlockAlignment: Enabled: false # DISABLED Lint/DefEndAlignment: Enabled: false # DISABLED Lint/EndAlignment: Enabled: false # DISABLED Lint/DeprecatedClassMethods: Enabled: false # DISABLED Lint/Loop: Enabled: false # DISABLED Lint/ParenthesesAsGroupedExpression: Enabled: false Lint/RescueException: Enabled: false Lint/StringConversionInInterpolation: Enabled: false Lint/UnusedBlockArgument: Enabled: false Lint/UnusedMethodArgument: Enabled: false Lint/UselessAccessModifier: Enabled: true Lint/UselessAssignment: Enabled: true Lint/Void: Enabled: true Style/AccessModifierIndentation: Enabled: false Style/AccessorMethodName: Enabled: false Style/Alias: Enabled: false Style/AlignArray: Enabled: false Style/AlignHash: Enabled: false Style/AlignParameters: Enabled: false Metrics/BlockNesting: Enabled: false Style/AsciiComments: Enabled: false Style/Attr: Enabled: false Style/BracesAroundHashParameters: Enabled: false Style/CaseEquality: Enabled: false Style/CaseIndentation: Enabled: false Style/CharacterLiteral: Enabled: false Style/ClassAndModuleCamelCase: Enabled: false Style/ClassAndModuleChildren: Enabled: false Style/ClassCheck: Enabled: false Metrics/ClassLength: Enabled: false Style/ClassMethods: Enabled: false Style/ClassVars: Enabled: false Style/WhenThen: Enabled: false # DISABLED - not useful Style/WordArray: Enabled: false Style/UnneededPercentQ: Enabled: false Style/Tab: Enabled: false Style/SpaceBeforeSemicolon: Enabled: false Style/TrailingBlankLines: Enabled: false Style/SpaceInsideBlockBraces: Enabled: false Style/SpaceInsideBrackets: Enabled: false Style/SpaceInsideHashLiteralBraces: Enabled: false Style/SpaceInsideParens: Enabled: false Style/LeadingCommentSpace: Enabled: false Style/SpaceBeforeFirstArg: Enabled: false Style/SpaceAfterColon: Enabled: false Style/SpaceAfterComma: Enabled: false Style/SpaceAroundKeyword: Enabled: false Style/SpaceAfterMethodName: Enabled: false Style/SpaceAfterNot: Enabled: false Style/SpaceAfterSemicolon: Enabled: false Style/SpaceAroundEqualsInParameterDefault: Enabled: false Style/SpaceAroundOperators: Enabled: false Style/SpaceBeforeBlockBraces: Enabled: false Style/SpaceBeforeComma: Enabled: false Style/CollectionMethods: Enabled: false Style/CommentIndentation: Enabled: false Style/ColonMethodCall: Enabled: false Style/CommentAnnotation: Enabled: false Metrics/CyclomaticComplexity: Enabled: false Style/ConstantName: Enabled: false Style/Documentation: Enabled: false Style/DefWithParentheses: Enabled: false Style/DotPosition: Enabled: false # DISABLED - used for converting to bool Style/DoubleNegation: Enabled: false Style/EachWithObject: Enabled: false Style/EmptyLineBetweenDefs: Enabled: false Style/IndentArray: Enabled: false Style/IndentHash: Enabled: false Style/IndentationConsistency: Enabled: true Style/IndentationWidth: Enabled: true Style/EmptyLines: Enabled: false Style/EmptyLinesAroundAccessModifier: Enabled: false Style/EmptyLiteral: Enabled: false Metrics/LineLength: Enabled: false Style/MethodCallWithoutArgsParentheses: Enabled: false Style/MethodDefParentheses: Enabled: false Style/LineEndConcatenation: Enabled: false Style/TrailingWhitespace: Enabled: false Style/StringLiterals: Enabled: false Style/TrailingCommaInLiteral: Enabled: false Style/TrailingCommaInArguments: Enabled: false Style/GlobalVars: Enabled: false Style/GuardClause: Enabled: false Style/IfUnlessModifier: Enabled: false Style/MultilineIfThen: Enabled: false Style/NegatedIf: Enabled: false Style/NegatedWhile: Enabled: false Style/Next: Enabled: false Style/SingleLineBlockParams: Enabled: false Style/SingleLineMethods: Enabled: false Style/SpecialGlobalVars: Enabled: false Style/TrivialAccessors: Enabled: false Style/UnlessElse: Enabled: false Style/VariableInterpolation: Enabled: false Style/VariableName: Enabled: false Style/WhileUntilDo: Enabled: false Style/EvenOdd: Enabled: false Style/FileName: Enabled: false Style/For: Enabled: false Style/Lambda: Enabled: false Style/MethodName: Enabled: false Style/MultilineTernaryOperator: Enabled: false Style/NestedTernaryOperator: Enabled: false Style/NilComparison: Enabled: false Style/FormatString: Enabled: false Style/MultilineBlockChain: Enabled: false Style/Semicolon: Enabled: false Style/SignalException: Enabled: false Style/NonNilCheck: Enabled: false Style/Not: Enabled: false Style/NumericLiterals: Enabled: false Style/OneLineConditional: Enabled: false Style/OpMethod: Enabled: false Style/ParenthesesAroundCondition: Enabled: false Style/PercentLiteralDelimiters: Enabled: false Style/PerlBackrefs: Enabled: false Style/PredicateName: Enabled: false Style/RedundantException: Enabled: false Style/SelfAssignment: Enabled: false Style/Proc: Enabled: false Style/RaiseArgs: Enabled: false Style/RedundantBegin: Enabled: false Style/RescueModifier: Enabled: false Style/RegexpLiteral: Enabled: false Lint/UnderscorePrefixedVariableName: Enabled: false Metrics/ParameterLists: Enabled: false Lint/RequireParentheses: Enabled: false Style/ModuleFunction: Enabled: false Lint/Debugger: Enabled: false Style/IfWithSemicolon: Enabled: false Style/Encoding: Enabled: false Style/MultilineOperationIndentation: Enabled: false Style/BlockDelimiters: Enabled: false Style/ExtraSpacing: Enabled: false Style/MultilineHashBraceLayout: Enabled: false Style/MultilineMethodCallBraceLayout: Enabled: false Style/MultilineBlockLayout: Enabled: false Lint/UselessAssignment: Enabled: false Lint/DuplicateMethods: Enabled: false Style/EmptyLinesAroundMethodBody: Enabled: false Style/EmptyLinesAroundModuleBody: Enabled: false Style/EmptyLinesAroundBlockBody: Enabled: false Style/EmptyLinesAroundClassBody: Enabled: false Style/UnneededInterpolation: Enabled: false Style/SymbolProc: Enabled: false Style/ConditionalAssignment: Enabled: false Style/ZeroLengthPredicate: Enabled: false Style/TrailingUnderscoreVariable: Enabled: false Style/StringLiteralsInInterpolation: Enabled: false Style/RedundantParentheses: Enabled: false Style/MutableConstant: Enabled: false Performance/RedundantMatch: Enabled: false Performance/FlatMap: Enabled: false Performance/StringReplacement: Enabled: false Metrics/AbcSize: Enabled: false Metrics/PerceivedComplexity: Enabled: false Metrics/BlockLength: Enabled: false Style/VariableNumber: Enabled: false puppet-strings-2.1.0/.travis.yml000066400000000000000000000011101331446220200166150ustar00rootroot00000000000000--- language: ruby sudo: false bundler_args: --without development acceptance notifications: email: false before_install: - gem update bundler matrix: fast_finish: true include: - rvm: 2.1.9 env: PUPPET_GEM_VERSION="~> 4" CHECK=spec - rvm: 2.4.1 env: PUPPET_GEM_VERSION="~> 4" CHECK=spec - rvm: 2.4.1 env: PUPPET_GEM_VERSION="~> 5" CHECK=spec - rvm: 2.1.9 env: PUPPET_GEM_VERSION="~> 4" CHECK=rubocop - rvm: 2.1.0 env: PUPPET_GEM_VERSION="~> 4" CHECK=spec script: 'SPEC_OPTS="--format documentation" COVERAGE="yes" bundle exec rake $CHECK' puppet-strings-2.1.0/.yardopts000066400000000000000000000000721331446220200163600ustar00rootroot00000000000000--exclude lib/puppet-strings/yard/templates/ --no-private puppet-strings-2.1.0/CHANGELOG.md000066400000000000000000000332611331446220200163310ustar00rootroot00000000000000# Changelog All significant changes to this repo will be summarized in this file. ## [v2.1.0](https://github.com/puppetlabs/puppet-strings/tree/v2.1.0) (2018-06-25) [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/2.0.0...v2.1.0) **Implemented enhancements:** - \(PDOC-212, PDOC-213\) add support for @note and @todo [\#182](https://github.com/puppetlabs/puppet-strings/pull/182) ([eputnam](https://github.com/eputnam)) - \(PDOC-255\) markdown table of contents update [\#181](https://github.com/puppetlabs/puppet-strings/pull/181) ([eputnam](https://github.com/eputnam)) **Merged pull requests:** - \(PDOC-259\) relax ruby requirement to 2.1.0 from 2.1.9 [\#184](https://github.com/puppetlabs/puppet-strings/pull/184) ([DavidS](https://github.com/DavidS)) # Previous Changes ## [2.0.0](https://github.com/puppetlabs/puppet-strings/tree/2.0.0) (2018-05-11) [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/1.2.1...2.0.0) ### Changed - bump required ruby and puppet versions [\#178](https://github.com/puppetlabs/puppet-strings/pull/178) ([eputnam](https://github.com/eputnam)) ### Added - \(PDOC-238\) add generated message to markdown [\#175](https://github.com/puppetlabs/puppet-strings/pull/175) ([eputnam](https://github.com/eputnam)) - \(PDOC-228\) puppet plan support [\#168](https://github.com/puppetlabs/puppet-strings/pull/168) ([eputnam](https://github.com/eputnam)) - \(PDOC-206\) support for tasks [\#161](https://github.com/puppetlabs/puppet-strings/pull/161) ([eputnam](https://github.com/eputnam)) ### Fixed - \(PDOC-36\) fix hack for README urls [\#176](https://github.com/puppetlabs/puppet-strings/pull/176) ([eputnam](https://github.com/eputnam)) - \(PDOC-240\) add handling for :array node type in rsapi\_handler [\#174](https://github.com/puppetlabs/puppet-strings/pull/174) ([eputnam](https://github.com/eputnam)) - \(PDOC-159\) server urls fix [\#173](https://github.com/puppetlabs/puppet-strings/pull/173) ([eputnam](https://github.com/eputnam)) - \(maint\) display Plans in markdown table of contents [\#171](https://github.com/puppetlabs/puppet-strings/pull/171) ([eputnam](https://github.com/eputnam)) - \(PDOC-233\) markdown whitespace fixes [\#170](https://github.com/puppetlabs/puppet-strings/pull/170) ([JohnLyman](https://github.com/JohnLyman)) - \(PDOC-229\) fix error with return\_type and @return [\#169](https://github.com/puppetlabs/puppet-strings/pull/169) ([eputnam](https://github.com/eputnam)) - \(PDOC-36\) hack to fix README links in generated HTML [\#167](https://github.com/puppetlabs/puppet-strings/pull/167) ([eputnam](https://github.com/eputnam)) - \(PDOC-192\) remove warning for title/name [\#166](https://github.com/puppetlabs/puppet-strings/pull/166) ([eputnam](https://github.com/eputnam)) - \(maint\) add condition for misleading warning [\#155](https://github.com/puppetlabs/puppet-strings/pull/155) ([eputnam](https://github.com/eputnam)) ## [1.2.1](https://github.com/puppetlabs/puppet-strings/tree/1.2.1) (2018-03-01) [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/1.2.0...1.2.1) ### Fixed - (PDOC-224) Handle --emit-json(-stdout) again [\#162](https://github.com/puppetlabs/puppet-strings/pull/162) ([ekohl](https://github.com/ekohl)) ## [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 - Remove timestamps from footer of generated HTML pages ([GeoffWilliams](https://github.com/GeoffWilliams)) - Fix argument handling for `rake strings::generate` ([hashar](https://github.com/hashar)) ### Other - Fixed Markdown formatting issues in CHANGELOG ([maju6406](https://github.com/maju6406)) - Fixed typo in README ([hfm](https://github.com/hfm)) - Fixed Markdown formatting issues in README ([gguillotte](https://github.com/gguillotte)) - Update Travis CI configurations for Ruby and Puppet versions ([ghoneycutt](https://github.com/ghoneycutt)) ## 2017-03-20 - Release 1.1.0 ### Summary This release adds a new `summary` tag which can be used to add a short description to classes, functions, types, and providers. In addition, `@param` tags can now include type information in Puppet 4 code without warnings being issued. All related tickets can be found under the [PDOC](https://tickets.puppetlabs.com/browse/PDOC) JIRA project with the fix version of [1.1.0](https://tickets.puppetlabs.com/issues/?filter=25603). ### Features - The `summary` tag can be added to any code that puppet-strings supports. The recommended length limit for a summary is 140 characters. Warnings will be issued for strings longer than this limit. - Puppet 4 parameter types can now be explicitly documented. Previously, this was not allowed because Puppet 4 parameter types can be automatically determined without extra documentation. However, users may desire to do so anyway for consistency. Strings will emit a warning if the documented type does not match the actual type. In such an event, the incorrect documented type will be ignored in favor of the real one. ## 2016-11-28 - Release 1.0.0 ### Summary This release fixes up minor bugs from the 0.99.0 release and modifies the JSON schema for Puppet functions. All related tickets can be found under the [PDOC](https://tickets.puppetlabs.com/browse/PDOC) JIRA project with the fix version of [1.0.0](https://tickets.puppetlabs.com/issues/?filter=23607). ### Features - The JSON schema for Puppet functions has been altered to include a new 'signatures' top-level key **(PDOC-125)** - Includes information about all function signatures (overloads). Existing overload key format has been preserved. - Reworked README for enhanced clarity **(PDOC-133)** ### BugFixes - Fixed an issue where the search box in the code navigator overlapped list items below it **(PDOC-93)** - Strings can now handle multiple `defaultfor` calls in Puppet providers **(PDOC-95)** - Fixed an issue preventing the generated \_index.html file from being uploaded to GitHub pages via the gh_pages task **(PDOC-120)** - Fixed several issues with String's handling of Puppet 3.x and 4.x function return types **(PDOC-135)**, **(PDOC-136)** - Fixed an issue where String's didn't properly parse overloads if no summary description was provided **(PDOC-129)** - Strings now correctly handles Puppet 3.x functions when the `newfunction` call is on a newline **(PDOC-122)** - Fixed an issue where certain Ruby string constructs were incompletely stripped from some docstrings **(PDOC-126)** - Hanging indents from type feature descriptions are now properly stripped **(PDOC-127)** ## 2016-10-10 - Release 0.99.0 ### Summary This release includes a complete rewrite of strings, fixing many bugs from previous versions and generally improving the user experience. This release is intended to be the last stop before the strings major version 1.0 is released, and nearly all of the functionality of the major release is included. All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.99.0](https://tickets.puppetlabs.com/issues/?filter=22705). ### Features - Complete overhaul, including code cleanup, bug fixes and new functionality **(PDOC-63)** - Documentation has been split into sections based on type: puppet 3x API functions, puppet 4x API functions, ruby classes, puppet language functions, types, and providers - New JSON schema organized to reflect the separation of types - Support for custom functions written in the puppet language - Support for puppet function overloads via the create_function 4.x API - YARD bumped to latest version, 0.9.5 - Markdown is now the default format for parsing docstring text **(PDOC-86)** - Note: this means Markdown text in YARD comments and tags, not a change in the output of strings - New commandline options: --emit-json and --emit-json-stdout to generate JSON documentation **(PDOC-84)** - Runtime dependency on Puppet has been removed, allowing strings to function in Puppet Enterprise 3.8 **(PDOC-80)** - Note that the gem still requires puppet. We recommend that the strings gem be installed with puppet, as suggested in the [README](https://github.com/puppetlabs/puppet-strings/blob/master/README.md#installing-puppet-strings) - New gemspec requirement on Ruby version 1.9.3, the oldest supported Ruby version ### BugFixes - Prevents a blizzard of errors when documenting Puppet Core source and some puppet modules **(PDOC-63)** - As this is a complete rewrite, many known and unknown bugs from the original code were fixed along the way - Allow strings to be installed in PE 3.8 without overwriting existing puppet and facter installations with newer gems ## 2016-03-30 - Release 0.4.0 ### Summary This release adds JSON output support for strings, fixes a major bug that prevented strings from working with the 4.4.0 release of puppet, and is the last version of strings that will be released as a module. All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.4.0](https://tickets.puppetlabs.com/issues/?filter=18810). ### Features - Support for JSON output **(PDOC-23)** - Strings now has the ability to produce a JSON representation of a given puppet module - The details of the JSON schema can be found [here](https://github.com/puppetlabs/puppet-strings/blob/master/json_dom.md) - For details on how to generate JSON, see the [README](https://github.com/puppetlabs/puppet-strings/blob/master/README.md#running-puppet-strings) - Migrate to ruby gems as a distribution method **(PDOC-28)** - This is the last release of strings that will be available as a puppet module - The 0.4.0 release will be released concurrently as a ruby gem - After this release, all updates will only be available via the gem ### Bugfixes - Fix issue that prevented strings from running with Puppet 4.4.0 **(PDOC-75)** ## 2015-09-22 - Release 0.3.1 ### Summary This is a minor bug fix release. All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.3.1](https://tickets.puppetlabs.com/issues/?filter=15530). ### Bugfixes - Prevent strings from printing unnecessary quotes in error messages **(PDOC-57)** - Issue correct type check warnings for defined types **(PDOC-56)** - Allow providers, types, and defines to have the same name **(PDOC-54)** ## 2015-09-21 - Release 0.3.0 ### Summary This release includes support for Puppet Types and Providers, as well as type checking Puppet 4x functions and defined types. All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.3.0](https://tickets.puppetlabs.com/issues/?filter=15529). #### Features - Support for Puppet Types and Providers **(PDOC-35)** - Type check Puppet 4x functions and defined types where possible and warn the user when types don't match. - Type check defined types **(PDOC-21)** - Type check Puppet 4x functions **(PDOC-38)** **(PDOC-19)** **(PDOC-37)** - Output type info in generated HTML **(PDOC-19)** - Improved warnings and logging. - Create a consistent style for warnings. **(PDOC-49)** - All warnings get printed on stderr. - Yard warnings are redirected to a log file **(PDOC-38)** - Prevent duplicate warnings **(PDOC-38)** - Improved README installation and usage instructions. - Installation instructions using Puppet **(PDOC-33)** #### Bugfixes - Fix markdown list processing **(PDOC-30)** - Fix namespacing for nested classes and defined types **(PDOC-20)** ## 2015-03-17 - Release 0.2.0 ### Summary This release includes improvements to the HTML output generated by strings and a few bug fixes. All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.2.0](https://tickets.puppetlabs.com/issues/?filter=13760). [PDOC JIRA]: https://tickets.puppetlabs.com/browse/PDOC #### Features - Custom YARD templates for classes and defined types **(PDOC-17)** - Improved HMTL output that is more appropriate for Puppet code (especially for parameters) - Support for the explicit list of YARD tags we will be supporting initially (@param, @return, @since, @example) - Our own custom YARD templates which can be easily extended and tweaked - Custom YARD templates for 3.x and 4.x functions **(PDOC-24)** - Improved HMTL output that is more appropriate for listing several functions on one webpage in addition to being more consistent with the HTML produced for classes and defined types. - Support for the explicit list of YARD tags we will be supporting initially (@param, @return, @since, @example) - Our own custom YARD templates which can be easily extended and tweaked - Addition of RubCop Travis CI job to ensure code quality and consistency **(PDOC-8)** #### Bugfixes - 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)* puppet-strings-2.1.0/COMMITTERS.md000066400000000000000000000207561331446220200165350ustar00rootroot00000000000000Committing changes to Strings ==== We would like to make it easier for community members to contribute to strings using pull requests, even if it makes the task of reviewing and committing these changes a little harder. Pull requests are only ever based on a single branch. As a result contributors should target their changes at the master branch. This makes the process of contributing a little easier for the contributor since they don't need to concern themselves with the question, "What branch do I base my changes on?" This is already called out in the [CONTRIBUTING.md](http://goo.gl/XRH2J). Therefore, it is the responsibility of the committer to re-base the change set on the appropriate branch which should receive the contribution. It is also the responsibility of the committer to review the change set in an effort to make sure the end users must opt-in to new behavior that is incompatible with previous behavior. We employ the use of [feature flags](http://stackoverflow.com/questions/7707383/what-is-a-feature-flag) as the primary way to achieve this user opt-in behavior. Finally, it is the responsibility of the committer to make sure the `master` branch is clean and working at all times. Clean means that dead code is not allowed, everything needs to be usable in some manner at all points in time. The rest of this document addresses the concerns of the committer. This document will help guide the committer decide which branch to base, or re-base a contribution on top of. This document also describes our branch management strategy, which is closely related to the decision of what branch to commit changes into. Terminology ==== Many of these terms have more than one meaning. For the purposes of this document, the following terms refer to specific things. **contributor** - A person who makes a change to strings and submits a change set in the form of a pull request. **change set** - A set of discrete patches which combined together form a contribution. A change set takes the form of Git commits and is submitted to strings in the form of a pull request. **committer** - A person responsible for reviewing a pull request and then making the decision what base branch to merge the change set into. **base branch** - A branch in Git that contains an active history of changes and will eventually be released using semantic version guidelines. The branch named `master` will always exist as a base branch. **master branch** - The branch where new functionality that and bug fixes are merged. **security** - Where critical security fixes are merged. These change sets will then be merged into release branches independently from one another. (i.e. no merging up). Please do not submit pull requests against the security branch and instead report all security related issues to security@puppet.com as per our security policy published at [https://puppet.com/security/](https://puppet.com/security/). Committer Guide ==== This section provides a guide to follow while committing change sets to strings base branches. How to decide what release(s) should be patched --- This section provides a guide to help a committer decide the specific base branch that a change set should be merged into. The latest minor release of a major release is the only base branch that should be patched. These patches will be merged into `master` if they contain new functionality and if they fix a critical bug. Older minor releases in a major release do not get patched. Before the switch to [semantic versions](http://semver.org/) committers did not have to think about the difference between minor and major releases. Committing to the latest minor release of a major release is a policy intended to limit the number of active base branches that must be managed. Security patches are handled as a special case. Security patches may be applied to earlier minor releases of a major release, but the patches should first be merged into the `security` branch. Security patches should be merged by Puppet Labs staff members. Pull requests should not be submitted with the security branch as the base branch. Please send all security related information or patches to security@puppet.com as per our [Security Policy](https://puppet.com/security/). The CI systems are configured to run against `master`. Over time, this branch will refer to different versions, but its name will remain fixed to avoid having to update CI jobs and tasks as new versions are released. Code review checklist --- This section aims to provide a checklist of things to look for when reviewing a pull request and determining if the change set should be merged into a base branch: * All tests pass * Are there any platform gotchas? (Does a change make an assumption about platform specific behavior that is incompatible with other platforms? e.g. Windows paths vs. POSIX paths.) * Is the change backwards compatible? (It should be) * Are there YARD docs for API changes? * Does the change set also require documentation changes? If so is the documentation being kept up to date? * Does the change set include clean code? (software code that is formatted correctly and in an organized manner so that another coder can easily read or modify it.) HINT: `git diff master --check` * Does the change set conform to the contributing guide? Commit citizen guidelines: --- This section aims to provide guidelines for being a good commit citizen by paying attention to our automated build tools. * Don’t push on a broken build. (A broken build is defined as a failing job in [Puppet Strings](https://jenkins.puppetlabs.com/job/platform_puppet-strings_unit-ruby_master/) page.) * Watch the build until your changes have gone through green * Update the ticket status and target version. The target version field in our issue tracker should be updated to be the next release of Puppet. For example, if the most recent release of Puppet is 3.1.1 and you merge a backwards compatible change set into master, then the target version should be 3.2.0 in the issue tracker.) * Ensure the pull request is closed (Hint: amend your merge commit to contain the string `closes #123` where 123 is the pull request number and github will automatically close the pull request when the branch is pushed.) Example Procedure ==== This section helps a committer rebase and merge a contribution into the base branch. Suppose a contributor submits a pull request based on master. The change set fixes a bug reported against strings 0.1.0 which is the most recently released version of strings. First, the committer pulls down the branch using the `hub` gem. This tool automates the process of adding the remote repository and creating a local branch to track the remote branch. $ hub checkout https://github.com/puppetlabs/puppet-strings/pull/123 Branch jeffmccune-pdoc-34_fix_foo_error set up to track remote branch pdoc-34-fix_foo_error from jeffmccune. Switched to a new branch 'jeffmccune-pdoc-34_fix_foo_error' It's possible that more changes have been merged into master since the pull request was submitted. In this case it may be necessary to rebase the branch that contains the changes: $ git rebase upstream/master After the branch has been checked out and rebased, the committer should ensure that the code review check list has been completed. Now that we have a topic branch containing the change set based on the most recent `master` branch, the committer merges in: $ git checkout master Switched to branch 'master' $ git merge --no-ff --log jeffmccune-pdoc-34_fix_foo_error Merge made by the 'recursive' strategy. foo | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 foo Once the change set has been merged into one base branch, the change set should not be modified in order to keep the history clean, avoid "double" commits, and preserve the usefulness of `git branch --contains`. If there are any merge conflicts, they are to be resolved in the merge commit itself and not by re-writing (rebasing) the patches for one base branch, but not another. Once the change set has been merged into `master`, the committer pushes. Please note, the checklist should be complete at this point. It's helpful to make sure your local branches are up to date to avoid one of the branches failing to fast forward while the other succeeds. $ git push origin master:master That's it! The committer then updates the pull request, updates the issue in our issue tracker, and keeps an eye on the [build status](http://jenkins.puppetlabs.com). puppet-strings-2.1.0/CONTRIBUTING.md000066400000000000000000000113511331446220200167450ustar00rootroot00000000000000# How to contribute Third-party patches are essential for keeping Puppet Strings great. We want to keep it as easy as possible to contribute changes that get things working in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. ## Getting Started * Make sure you have a [Jira account](http://tickets.puppetlabs.com) * Make sure you have a [GitHub account](https://github.com/signup/free) * Submit a ticket for your issue, assuming one does not already exist. * Clearly describe the issue including steps to reproduce when it is a bug. * Make sure you fill in the earliest version that you know has the issue. * Fork the repository on GitHub ## Making Changes * Create a topic branch from where you want to base your work. * This is usually the master branch. * Only target release branches if you are certain your fix must be on that branch. * To quickly create a topic branch based on master; `git checkout -b fix/master/my_contribution master`. Please avoid working directly on the `master` branch. * Make commits of logical units. * Check for unnecessary whitespace with `git diff --check` before committing. * Make sure your commit messages are in the proper format. ```` (PDOC-123) Make the example in CONTRIBUTING imperative and concrete Without this patch applied the example commit message in the CONTRIBUTING document is not a concrete example. This is a problem because the contributor is left to imagine what the commit message should look like based on a description rather than an example. This patch fixes the problem by making the example concrete and imperative. The first line is a real life imperative statement with a ticket number from our issue tracker. The body describes the behavior without the patch, why this is a problem, and how the patch fixes the problem when applied. ```` * Make sure you have added the necessary tests for your changes. * Run _all_ the tests to assure nothing else was accidentally broken. ## Making Trivial Changes ### Documentation For changes of a trivial nature to comments and documentation, it is not always necessary to create a new ticket in Jira. In this case, it is appropriate to start the first line of a commit with '(doc)' instead of a ticket number. ```` (doc) Add documentation commit example to CONTRIBUTING There is no example for contributing a documentation commit to the Puppet repository. This is a problem because the contributor is left to assume how a commit of this nature may appear. The first line is a real life imperative statement with '(doc)' in place of what would have been the ticket number in a non-documentation related commit. The body describes the nature of the new documentation or comments added. ```` ## Submitting Changes * Sign the [Contributor License Agreement](http://links.puppet.com/cla). * Push your changes to a topic branch in your fork of the repository. * Submit a pull request to the repository in the puppetlabs organization. * Update your Jira ticket to mark that you have submitted code and are ready for it to be reviewed (Status: Ready for Merge). * Include a link to the pull request in the ticket. * After feedback has been given we expect responses within two weeks. After two weeks will may close the pull request if it isn't showing any activity. ## Cutting a release To cut a new release, from a current `master` checkout: * Start the release branch with `git checkout -b release-prep` * Update `lib/puppet-strings/version.rb` to the new version * Update the CHANGELOG * Have a [CHANGELOG_GITHUB_TOKEN](https://github.com/skywinder/github-changelog-generator#github-token) set in your environment * run `rake changelog` * double check the PRs to make sure they're all tagged correctly (using the new CHANGELOG for cross-checking) * Check README and other materials for up-to-date-ness * Commit changes with title "Release prep for v\" * Upload and PR the release-prep branch to the puppetlabs GitHub repo * Check that CI is green and merge the PR * Run `rake release[upstream]` to release from your checkout * make sure to use the name of your git remote pointing to the puppetlabs GitHub repo * Remove the release-prep branch * Send the release announcements using the template in [misc/ANNOUNCEMENT_TEMPLATE.md](misc/ANNOUNCEMENT_TEMPLATE.md) # Additional Resources * [More information on contributing](http://links.puppet.com/contribute-to-puppet) * [Bug tracker (Jira)](http://tickets.puppet.com) * [Contributor License Agreement](http://links.puppet.com/cla) * [General GitHub documentation](http://help.github.com/) * [GitHub pull request documentation](http://help.github.com/send-pull-requests/) puppet-strings-2.1.0/Gemfile000066400000000000000000000014601331446220200160070ustar00rootroot00000000000000source ENV['GEM_SOURCE'] || "https://rubygems.org" gemspec gem 'rgen' gem 'redcarpet' gem 'yard', '~> 0.9.11' if ENV['PUPPET_GEM_VERSION'] gem 'puppet', ENV['PUPPET_GEM_VERSION'], :require => false else gem 'puppet', :require => false end group :test do gem 'codecov' gem 'mocha' gem 'puppetlabs_spec_helper' gem 'serverspec' gem 'simplecov-console' gem "rspec", "~> 3.1" end group :acceptance do gem 'beaker', '< 3.0' gem 'beaker-rspec' gem 'beaker-hostgenerator' gem 'beaker-abs' end group :development do gem 'github_changelog_generator', git: 'https://github.com/skywinder/github-changelog-generator', ref: '20ee04ba1234e9e83eb2ffb5056e23d641c7a018' if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.2.2') gem 'pry' gem 'pry-byebug' end gem 'rubocop', '<= 0.47.0' puppet-strings-2.1.0/HISTORY.md000066400000000000000000000314231331446220200162010ustar00rootroot00000000000000# Previous Changes ## [2.0.0](https://github.com/puppetlabs/puppet-strings/tree/2.0.0) (2018-05-11) [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/1.2.1...2.0.0) ### Changed - bump required ruby and puppet versions [\#178](https://github.com/puppetlabs/puppet-strings/pull/178) ([eputnam](https://github.com/eputnam)) ### Added - \(PDOC-238\) add generated message to markdown [\#175](https://github.com/puppetlabs/puppet-strings/pull/175) ([eputnam](https://github.com/eputnam)) - \(PDOC-228\) puppet plan support [\#168](https://github.com/puppetlabs/puppet-strings/pull/168) ([eputnam](https://github.com/eputnam)) - \(PDOC-206\) support for tasks [\#161](https://github.com/puppetlabs/puppet-strings/pull/161) ([eputnam](https://github.com/eputnam)) ### Fixed - \(PDOC-36\) fix hack for README urls [\#176](https://github.com/puppetlabs/puppet-strings/pull/176) ([eputnam](https://github.com/eputnam)) - \(PDOC-240\) add handling for :array node type in rsapi\_handler [\#174](https://github.com/puppetlabs/puppet-strings/pull/174) ([eputnam](https://github.com/eputnam)) - \(PDOC-159\) server urls fix [\#173](https://github.com/puppetlabs/puppet-strings/pull/173) ([eputnam](https://github.com/eputnam)) - \(maint\) display Plans in markdown table of contents [\#171](https://github.com/puppetlabs/puppet-strings/pull/171) ([eputnam](https://github.com/eputnam)) - \(PDOC-233\) markdown whitespace fixes [\#170](https://github.com/puppetlabs/puppet-strings/pull/170) ([JohnLyman](https://github.com/JohnLyman)) - \(PDOC-229\) fix error with return\_type and @return [\#169](https://github.com/puppetlabs/puppet-strings/pull/169) ([eputnam](https://github.com/eputnam)) - \(PDOC-36\) hack to fix README links in generated HTML [\#167](https://github.com/puppetlabs/puppet-strings/pull/167) ([eputnam](https://github.com/eputnam)) - \(PDOC-192\) remove warning for title/name [\#166](https://github.com/puppetlabs/puppet-strings/pull/166) ([eputnam](https://github.com/eputnam)) - \(maint\) add condition for misleading warning [\#155](https://github.com/puppetlabs/puppet-strings/pull/155) ([eputnam](https://github.com/eputnam)) ## [1.2.1](https://github.com/puppetlabs/puppet-strings/tree/1.2.1) (2018-03-01) [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/1.2.0...1.2.1) ### Fixed - (PDOC-224) Handle --emit-json(-stdout) again [\#162](https://github.com/puppetlabs/puppet-strings/pull/162) ([ekohl](https://github.com/ekohl)) ## [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 - Remove timestamps from footer of generated HTML pages ([GeoffWilliams](https://github.com/GeoffWilliams)) - Fix argument handling for `rake strings::generate` ([hashar](https://github.com/hashar)) ### Other - Fixed Markdown formatting issues in CHANGELOG ([maju6406](https://github.com/maju6406)) - Fixed typo in README ([hfm](https://github.com/hfm)) - Fixed Markdown formatting issues in README ([gguillotte](https://github.com/gguillotte)) - Update Travis CI configurations for Ruby and Puppet versions ([ghoneycutt](https://github.com/ghoneycutt)) ## 2017-03-20 - Release 1.1.0 ### Summary This release adds a new `summary` tag which can be used to add a short description to classes, functions, types, and providers. In addition, `@param` tags can now include type information in Puppet 4 code without warnings being issued. All related tickets can be found under the [PDOC](https://tickets.puppetlabs.com/browse/PDOC) JIRA project with the fix version of [1.1.0](https://tickets.puppetlabs.com/issues/?filter=25603). ### Features - The `summary` tag can be added to any code that puppet-strings supports. The recommended length limit for a summary is 140 characters. Warnings will be issued for strings longer than this limit. - Puppet 4 parameter types can now be explicitly documented. Previously, this was not allowed because Puppet 4 parameter types can be automatically determined without extra documentation. However, users may desire to do so anyway for consistency. Strings will emit a warning if the documented type does not match the actual type. In such an event, the incorrect documented type will be ignored in favor of the real one. ## 2016-11-28 - Release 1.0.0 ### Summary This release fixes up minor bugs from the 0.99.0 release and modifies the JSON schema for Puppet functions. All related tickets can be found under the [PDOC](https://tickets.puppetlabs.com/browse/PDOC) JIRA project with the fix version of [1.0.0](https://tickets.puppetlabs.com/issues/?filter=23607). ### Features - The JSON schema for Puppet functions has been altered to include a new 'signatures' top-level key **(PDOC-125)** - Includes information about all function signatures (overloads). Existing overload key format has been preserved. - Reworked README for enhanced clarity **(PDOC-133)** ### BugFixes - Fixed an issue where the search box in the code navigator overlapped list items below it **(PDOC-93)** - Strings can now handle multiple `defaultfor` calls in Puppet providers **(PDOC-95)** - Fixed an issue preventing the generated \_index.html file from being uploaded to GitHub pages via the gh_pages task **(PDOC-120)** - Fixed several issues with String's handling of Puppet 3.x and 4.x function return types **(PDOC-135)**, **(PDOC-136)** - Fixed an issue where String's didn't properly parse overloads if no summary description was provided **(PDOC-129)** - Strings now correctly handles Puppet 3.x functions when the `newfunction` call is on a newline **(PDOC-122)** - Fixed an issue where certain Ruby string constructs were incompletely stripped from some docstrings **(PDOC-126)** - Hanging indents from type feature descriptions are now properly stripped **(PDOC-127)** ## 2016-10-10 - Release 0.99.0 ### Summary This release includes a complete rewrite of strings, fixing many bugs from previous versions and generally improving the user experience. This release is intended to be the last stop before the strings major version 1.0 is released, and nearly all of the functionality of the major release is included. All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.99.0](https://tickets.puppetlabs.com/issues/?filter=22705). ### Features - Complete overhaul, including code cleanup, bug fixes and new functionality **(PDOC-63)** - Documentation has been split into sections based on type: puppet 3x API functions, puppet 4x API functions, ruby classes, puppet language functions, types, and providers - New JSON schema organized to reflect the separation of types - Support for custom functions written in the puppet language - Support for puppet function overloads via the create_function 4.x API - YARD bumped to latest version, 0.9.5 - Markdown is now the default format for parsing docstring text **(PDOC-86)** - Note: this means Markdown text in YARD comments and tags, not a change in the output of strings - New commandline options: --emit-json and --emit-json-stdout to generate JSON documentation **(PDOC-84)** - Runtime dependency on Puppet has been removed, allowing strings to function in Puppet Enterprise 3.8 **(PDOC-80)** - Note that the gem still requires puppet. We recommend that the strings gem be installed with puppet, as suggested in the [README](https://github.com/puppetlabs/puppet-strings/blob/master/README.md#installing-puppet-strings) - New gemspec requirement on Ruby version 1.9.3, the oldest supported Ruby version ### BugFixes - Prevents a blizzard of errors when documenting Puppet Core source and some puppet modules **(PDOC-63)** - As this is a complete rewrite, many known and unknown bugs from the original code were fixed along the way - Allow strings to be installed in PE 3.8 without overwriting existing puppet and facter installations with newer gems ## 2016-03-30 - Release 0.4.0 ### Summary This release adds JSON output support for strings, fixes a major bug that prevented strings from working with the 4.4.0 release of puppet, and is the last version of strings that will be released as a module. All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.4.0](https://tickets.puppetlabs.com/issues/?filter=18810). ### Features - Support for JSON output **(PDOC-23)** - Strings now has the ability to produce a JSON representation of a given puppet module - The details of the JSON schema can be found [here](https://github.com/puppetlabs/puppet-strings/blob/master/json_dom.md) - For details on how to generate JSON, see the [README](https://github.com/puppetlabs/puppet-strings/blob/master/README.md#running-puppet-strings) - Migrate to ruby gems as a distribution method **(PDOC-28)** - This is the last release of strings that will be available as a puppet module - The 0.4.0 release will be released concurrently as a ruby gem - After this release, all updates will only be available via the gem ### Bugfixes - Fix issue that prevented strings from running with Puppet 4.4.0 **(PDOC-75)** ## 2015-09-22 - Release 0.3.1 ### Summary This is a minor bug fix release. All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.3.1](https://tickets.puppetlabs.com/issues/?filter=15530). ### Bugfixes - Prevent strings from printing unnecessary quotes in error messages **(PDOC-57)** - Issue correct type check warnings for defined types **(PDOC-56)** - Allow providers, types, and defines to have the same name **(PDOC-54)** ## 2015-09-21 - Release 0.3.0 ### Summary This release includes support for Puppet Types and Providers, as well as type checking Puppet 4x functions and defined types. All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.3.0](https://tickets.puppetlabs.com/issues/?filter=15529). #### Features - Support for Puppet Types and Providers **(PDOC-35)** - Type check Puppet 4x functions and defined types where possible and warn the user when types don't match. - Type check defined types **(PDOC-21)** - Type check Puppet 4x functions **(PDOC-38)** **(PDOC-19)** **(PDOC-37)** - Output type info in generated HTML **(PDOC-19)** - Improved warnings and logging. - Create a consistent style for warnings. **(PDOC-49)** - All warnings get printed on stderr. - Yard warnings are redirected to a log file **(PDOC-38)** - Prevent duplicate warnings **(PDOC-38)** - Improved README installation and usage instructions. - Installation instructions using Puppet **(PDOC-33)** #### Bugfixes - Fix markdown list processing **(PDOC-30)** - Fix namespacing for nested classes and defined types **(PDOC-20)** ## 2015-03-17 - Release 0.2.0 ### Summary This release includes improvements to the HTML output generated by strings and a few bug fixes. All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with the fix version of [0.2.0](https://tickets.puppetlabs.com/issues/?filter=13760). [PDOC JIRA]: https://tickets.puppetlabs.com/browse/PDOC #### Features - Custom YARD templates for classes and defined types **(PDOC-17)** - Improved HMTL output that is more appropriate for Puppet code (especially for parameters) - Support for the explicit list of YARD tags we will be supporting initially (@param, @return, @since, @example) - Our own custom YARD templates which can be easily extended and tweaked - Custom YARD templates for 3.x and 4.x functions **(PDOC-24)** - Improved HMTL output that is more appropriate for listing several functions on one webpage in addition to being more consistent with the HTML produced for classes and defined types. - Support for the explicit list of YARD tags we will be supporting initially (@param, @return, @since, @example) - Our own custom YARD templates which can be easily extended and tweaked - Addition of RubCop Travis CI job to ensure code quality and consistency **(PDOC-8)** #### Bugfixes - 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)** puppet-strings-2.1.0/JSON.md000066400000000000000000000652611331446220200156200ustar00rootroot00000000000000Puppet Strings JSON Data ======================== Puppet Strings can generate JSON to STDOUT with the `--format` option: ```shell puppet strings generate --format json ``` Document Schema =============== At the top level, there are seven arrays in the JSON document: | Document Key | Description | | ---------------- | ----------------------------------------------------------------------------- | | puppet_classes | The list of Puppet classes that were parsed. | | defined_types | The list of defined types that were parsed. | | resource_types | The list of resource types that were parsed. | | providers | The list of resource providers that were parsed. | | puppet_functions | The list of Puppet functions (4.x, 4.x and Puppet language) that were parsed. | | puppet_tasks | The list of Puppet tasks that were parsed. | | puppet_plans | The list of Puppet plans that were parsed. | Puppet Classes -------------- Each entry in the `puppet_classes` list is an object with the following attributes: | Attribute Key | Description | | ------------- | ----------------------------------------------------- | | name | The name of the Puppet class. | | file | The file defining the Puppet class. | | line | The line where the Puppet class is defined. | | inherits | The name of the Puppet class the class inherits from. | | docstring | The *DocString* object for the class (see below). | | defaults | The map of parameter names to default values. | | source | The Puppet source code for the class. | Defined Types ------------- Each entry in the `defined_types` list is an object with the following attributes: | Attribute Key | Description | | ------------- | -------------------------------------------------------- | | name | The name of the defined type. | | file | The file defining the defined type. | | line | The line where the defined type is defined. | | docstring | The *DocString* object for the defined type (see below). | | defaults | The map of parameter names to default values. | | source | The Puppet source code for the defined type. | Resource Types -------------- Each entry in the `resource_types` list is an object with the following attributes: | Attribute Key | Description | | ------------- | --------------------------------------------------------- | | name | The name of the resource type. | | file | The file defining the resource type. | | line | The line where the resource type is defined. | | docstring | The *DocString* object for the resource type (see below). | | properties | The list of properties for the resource type (see below). | | parameters | The list of parameters for the resource type (see below). | | features | The list of features for the resource type (see below). | Each entry in the `properties` list is an object with the following attributes: | Attribute Key | Description | | ------------- | ------------------------------------------------------- | | name | The name of the property. | | description | The description of the property. | | values | The array of acceptable string values for the property. | | aliases | The map of new values aliased to existing values. | | isnamevar | True if the property is a namevar or false if not. | | default | The default value for the property. | Each entry in the `parameters` list is an object with the following attributes: | Attribute Key | Description | | ------------- | -------------------------------------------------------- | | name | The name of the parameter. | | description | The description of the parameter. | | values | The array of acceptable string values for the parameter. | | aliases | The map of new values aliased to existing values. | | isnamevar | True if the parameter is a namevar or false if not. | | default | The default value for the parameter. | Each entry in the `features` list is an object with the following attributes: | Attribute Key | Description | | ------------- | ------------------------------- | | name | The name of the feature. | | description | The description of the feature. | Providers --------- Each entry in the `providers` list is an object with the following attributes: | Attribute Key | Description | | ------------- | ---------------------------------------------------- | | name | The name of the provider. | | type_name | The name of the resource type of the provider. | | file | The file defining the provider. | | line | The line where the provider is defined. | | docstring | The *DocString* object for the provider (see below). | | confines | The string map of confines for the provider. | | features | The list of features implemented by the provider. | | defaults | The list of lists of "default for" for the provider. | | commands | The string map of commands for the provider. | Puppet Functions ---------------- Each entry in the `puppet_functions` list is an object with the following attributes: | Attribute Key | Description | | ------------- | ----------------------------------------------------------------------------- | | name | The name of the function. | | file | The file defining the function. | | line | The line where the function is defined. | | type | The function type (e.g. ruby3x, ruby4x, puppet). | | signatures | A list of Puppet signatures of the function, including overloads if present. | | docstring | The *DocString* object for the function (see below). | | defaults | The map of parameter names to default values. | | source | The source code for the function. | Puppet Tasks ------------ Each entry in the `puppet_tasks` list is an object with the following attributes: | Attribute Key | Description | | ------------- | ----------------------------------------------------------------------------- | | name | The name of the task. | | file | The file defining the task. | | line | The line where the task is defined. | | docstring | The *DocString* object for the task (see below). | | source | The source code for the task. | | supports_noop | Whether the task supports noop mode | | input_method | Maps to the `input_method` key in the task json | Puppet Plans ------------ Each entry in the `puppet_plans` list is an object with the following attributes: | Attribute Key | Description | | ------------- | ----------------------------------------------------------------------------- | | name | The name of the plan. | | file | The file defining the plan. | | line | The line where the plan is defined. | | docstring | The *DocString* object for the plan (see below). | | defaults | The map of parameter names to default values. | | source | The source code for the plan. | Signature Objects ----------------- The `signatures` key is a function-specific list containing an object for each signature of a function. Each object includes the `signature` itself, as well as each of its `param` and `return` tags. Puppet 4.x functions with overloads will contain multiple signatures, while other function types will contain only one. Each signature is represented as an object with the following attributes: | Attribute Key | Description | | ------------- | -------------------------------------------------------------------------------------------------- | | signature | The signature of the function. | | docstring | The *DocString* object describing the signature, which includes `text`, `param` and `return` tags. | DocString Objects ----------------- For the above types, their docstrings are represented as an object with the following attributes: | Attribute Key | Description | | ------------- | --------------------------------------------------- | | text | The textual part of the DocString. | | tags | The array of tag objects, if any are present. | Each entry in the `tags` list is an object with the following properties: | Attribute Key | Description | | ------------- | ------------------------------------------------------- | | tag_name | The name of the tag (e.g. param, return, etc.). | | text | The descriptive text of the tag. | | types | The array of types associated with the tag. | | name | The name associated with the tag (e.g. parameter name). | For Puppet 4.x functions with overloads, `overload` tags will contain three additional attributes: | Attribute Key | Description | | ------------- | ----------------------------------------------- | | signature | The Puppet signature of the overload. | | docstring | The *DocString* object describing the overload. | | defaults | The map of parameter names to default values. | Example JSON Document --------------------- An example JSON document describing a Puppet class, defined type, resource type, provider, and Puppet functions: ```json { "puppet_classes": [ { "name": "foo", "file": "site.pp", "line": 5, "inherits": "foo::bar", "docstring": { "text": "A simple class.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" } ] }, "defaults": { "param3": "hi" }, "source": "class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {\n}" } ], "defined_types": [ { "name": "dt", "file": "site.pp", "line": 12, "docstring": { "text": "A simple defined type.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" } ] }, "defaults": { "param3": "hi" }, "source": "define dt(Integer $param1, $param2, String $param3 = hi) {\n}" } ], "resource_types": [ { "name": "database", "file": "database.rb", "line": 43, "docstring": { "text": "An example database server resource type." }, "properties": [ { "name": "ensure", "description": "What state the database should be in.", "values": [ "present", "absent", "up", "down" ], "aliases": { "up": "present", "down": "absent" }, "default": "up" }, { "name": "file", "description": "The database file to use." }, { "name": "log_level", "description": "The log level to use.", "values": [ "debug", "warn", "error" ], "default": "warn" } ], "parameters": [ { "name": "address", "description": "The database server name.", "isnamevar": true }, { "name": "encryption_key", "description": "The encryption key to use." }, { "name": "encrypt", "description": "Whether or not to encrypt the database.", "values": [ "true", "false", "yes", "no" ], "default": "false" } ], "features": [ { "name": "encryption", "description": "The provider supports encryption." } ] } ], "providers": [ { "name": "linux", "type_name": "database", "file": "linux.rb", "line": 33, "docstring": { "text": "An example provider on Linux." }, "confines": { "kernel": "Linux", "osfamily": "RedHat" }, "features": [ "implements_some_feature", "some_other_feature" ], "defaults": [ [ [ "kernel", "Linux" ] ], [ [ "osfamily", "RedHat", ], [ "operatingsystemmajrelease", "7" ] ] ], "commands": { "foo": "/usr/bin/foo" } } ], "puppet_functions": [ { "name": "func", "file": "site.pp", "line": 20, "type": "puppet", "signatures": [ { "signature": "func(Integer $param1, Any $param2, String $param3 = hi)", "docstring": { "text": "A simple function.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } } ], "docstring": { "text": "A simple function.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "defaults": { "param3": "hi" }, "source": "function func(Integer $param1, $param2, String $param3 = hi) {\n}" }, { "name": "func3x", "file": "func3x.rb", "line": 1, "type": "ruby3x", "signatures": [ { "signature": "func3x(String $first, Any $second)", "docstring": { "text": "An example 3.x function.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "String" ], "name": "first" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "second" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } } ], "docstring": { "text": "An example 3.x function.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "String" ], "name": "first" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "second" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "source": "Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC\nAn example 3.x function.\n@param [String] first The first parameter.\n@param second The second parameter.\n@return [Undef] Returns nothing.\nDOC\n) do |*args|\nend" }, { "name": "func4x", "file": "func4x.rb", "line": 11, "type": "ruby4x", "signatures": [ { "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)", "docstring": { "text": "The first overload.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "The third parameter.", "types": [ "Optional[Array[String]]" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } }, { "signature": "func4x(Boolean $param, Callable &$block)", "docstring": { "text": "The second overload.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Boolean" ], "name": "param" }, { "tag_name": "param", "text": "The block parameter.", "types": [ "Callable" ], "name": "&block" }, { "tag_name": "return", "text": "Returns a string.", "types": [ "String" ] } ] } } ], "docstring": { "text": "An example 4.x function.", "tags": [ { "tag_name": "overload", "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)", "docstring": { "text": "The first overload.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "The third parameter.", "types": [ "Optional[Array[String]]" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "name": "func4x" }, { "tag_name": "overload", "signature": "func4x(Boolean $param, Callable &$block)", "docstring": { "text": "The second overload.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Boolean" ], "name": "param" }, { "tag_name": "param", "text": "The block parameter.", "types": [ "Callable" ], "name": "&block" }, { "tag_name": "return", "text": "Returns a string.", "types": [ "String" ] } ] }, "name": "func4x" } ] }, "source": "Puppet::Functions.create_function(:func4x) do\n # The first overload.\n # @param param1 The first parameter.\n # @param param2 The second parameter.\n # @param param3 The third parameter.\n # @return [Undef] Returns nothing.\n dispatch :foo do\n param 'Integer', :param1\n param 'Any', :param2\n optional_param 'Array[String]', :param3\n end\n\n # The second overload.\n # @param param The first parameter.\n # @param block The block parameter.\n # @return [String] Returns a string.\n dispatch :other do\n param 'Boolean', :param\n block_param\n end\nend" } ], "puppet_tasks": [ { "name": "(stdin)", "file": "(stdin)", "line": 0, "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]" ] } ] }, "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": false, "input_method": "stdin" } ], "puppet_plans": [ { "name": "plann", "file": "(stdin)", "line": 5, "docstring": { "text": "A simple plan.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "String" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "Integer" ], "name": "param3" } ] }, "defaults": { "param3": "1" }, "source": "plan plann(String $param1, $param2, Integer $param3 = 1) {\n}" } ] } ``` puppet-strings-2.1.0/LICENSE000066400000000000000000000011011331446220200155110ustar00rootroot00000000000000 Copyright (C) 2014 Puppet Labs Inc Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. puppet-strings-2.1.0/README.md000066400000000000000000000114721331446220200157770ustar00rootroot00000000000000Puppet Strings ============== [![Build Status](https://travis-ci.org/puppetlabs/puppet-strings.png?branch=master)](https://travis-ci.org/puppetlabs/puppet-strings) [![Gem Version](https://badge.fury.io/rb/puppet-strings.svg)](https://badge.fury.io/rb/puppet-strings) Puppet Strings generates documentation for Puppet code and extensions written in Puppet and Ruby. Strings processes code and YARD-style code comments to create documentation in HTML, Markdown, or JSON formats. | | | | -------------- |---------------------------------------------------------------- | | *Code* | [GitHub][repo] | | *Issues* | [Puppet JIRA Tracker][JIRA] | | *License* | [Apache 2.0][LICENSE] | | *Change log* | [CHANGELOG.md][changelog] | | *Contributing* | [CONTRIBUTING.md][contributing] and [COMMITTERS.md][committers] | [repo]: https://github.com/puppetlabs/puppet-strings [JIRA]: https://tickets.puppetlabs.com/browse/PDOC [LICENSE]: https://github.com/puppetlabs/puppet-strings/blob/master/LICENSE [changelog]: https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md [contributing]: https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md [committers]: https://github.com/puppetlabs/puppet-strings/blob/master/COMMITTERS.md ## Installing Puppet Strings ### Requirements * Ruby 2.1.9 or newer * Puppet 4.0 or newer * The `yard` Ruby gem ### Install Puppet Strings 1. Install the YARD gem by running `gem install yard` 1. Install the `puppet-strings` gem by running `gem install puppet-strings` 1. **Optional**: Set YARD options for Strings To use YARD options with Puppet Strings, specify a `yardopts` file in the same directory in which you run `puppet strings`. Puppet Strings supports the Markdown format and automatically sets the YARD `markup` option to `markdown`. To see a list of available YARD options, run `yard help doc`. For details about YARD options configuration, see the [YARD docs](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#config). ## Generating documentation with Puppet Strings By default, Puppet Strings outputs documentation as HTML, or you can specify JSON or Markdown output instead. Strings generates reference documentation based on the code and Strings code comments in all Puppet and Ruby source files under the `./manifests/`, `./functions/`, `./lib/`, `./types/`, and `./tasks/` directories. Strings outputs HTML of the reference information and the module README to the module's `./doc/` directory. This output can be rendered in any browser. JSON and Markdown output include the reference documentation only. Strings sends JSON output to either STDOUT or to a file. Markdown output is written to a REFERENCE.md file in the module's main directory. See the [Puppet Strings documentation](https://puppet.com/docs/puppet/latest/puppet_strings.html) for complete instructions for generating documentation with Strings. For code comment style guidelines and examples, see the [Puppet Strings style guide](https://puppet.com/docs/puppet/5.5/puppet_strings_style.html). ### Additional Resources Here are a few other good resources for getting started with documentation: * [Module README Template](https://docs.puppet.com/puppet/latest/reference/modules_documentation.html) * [YARD Getting Started Guide](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md) * [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md) ## Developing and Contributing We love contributions from the community! If you'd like to contribute to `puppet-strings`, check out [CONTRIBUTING.md](https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md) to get information on the contribution process. ### Running Specs If you plan on developing features or fixing bugs in Puppet Strings, it is essential that you run specs before opening a pull request. To run specs, run the `spec` rake task: $ bundle install --path .bundle/gems $ bundle exec rake spec ## Support Please log tickets and issues in our [JIRA tracker][JIRA]. A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users) is available for asking questions and getting help from others. There is also an active #puppet channel on the Freenode IRC network. We use semantic version numbers for our releases and recommend that users upgrade to patch releases and minor releases as they become available. Bug fixes and ongoing development will occur in minor releases for the current major version. Security fixes will be ported to a previous major version on a best-effort basis, until the previous major version is no longer maintained. puppet-strings-2.1.0/Rakefile000066400000000000000000000054611331446220200161660ustar00rootroot00000000000000require 'bundler/gem_tasks' #require 'puppetlabs_spec_helper/rake_tasks' require 'puppet-lint/tasks/puppet-lint' # Add our own tasks require 'puppet-strings/tasks' PuppetLint.configuration.send('disable_80chars') PuppetLint.configuration.ignore_paths = %w(acceptance/**/*.pp spec/**/*.pp pkg/**/*.pp) desc 'Validate Ruby source files and ERB templates.' task :validate do Dir['spec/**/*.rb','lib/**/*.rb'].each do |ruby_file| sh "ruby -c #{ruby_file}" unless ruby_file =~ /spec\/fixtures/ end Dir['lib/puppet-strings/yard/templates/**/*.erb'].each do |template| sh "erb -P -x -T '-' #{template} | ruby -c" end end task :acceptance do require 'beaker-hostgenerator' install_type = 'aio' target = ENV['platform'] abs = if ENV['BEAKER_ABS'] then 'abs' else 'vmpooler' end if ! target STDERR.puts 'TEST_TARGET environment variable is not set' STDERR.puts 'setting to default value of "centos7-64ma".' target = "centos7-64ma{type=#{install_type}}" end unless target =~ /type=/ puts "INFO: adding 'type=#{install_type}' to host config" target += "{type=#{install_type}}" end cli = BeakerHostGenerator::CLI.new([target, '--hypervisor', abs]) nodeset_dir = 'spec/acceptance/nodesets' nodeset = "#{nodeset_dir}/#{target}.yml" FileUtils.mkdir_p(nodeset_dir) File.open(nodeset, 'w') do |fh| fh.print(cli.execute) end puts "nodeset file:" puts nodeset sh 'gem build puppet-strings.gemspec' sh 'puppet module build spec/fixtures/acceptance/modules/test' if ENV['BEAKER_keyfile'] sh "BEAKER_set=#{target} rspec spec/acceptance/*.rb" else sh "BEAKER_keyfile=$HOME/.ssh/id_rsa-acceptance BEAKER_set=#{target} rspec spec/acceptance/*.rb" end end task(:rubocop) do require 'rubocop' cli = RuboCop::CLI.new cli.run(%w(-D -f s)) end #### CHANGELOG #### begin require 'github_changelog_generator/task' GitHubChangelogGenerator::RakeTask.new :changelog do |config| require 'puppet-strings/version' config.future_release = "v#{PuppetStrings::VERSION}" config.header = "# Changelog\n\n" \ "All significant changes to this repo will be summarized in this file.\n" config.configure_sections = { added: { prefix: "Added", labels: ["enhancement"] }, fixed: { prefix: "Fixed", labels: ["bugfix"] }, breaking: { prefix: "Changed", labels: ["backwards-incompatible"] } } config.exclude_labels = ['maintenance'] config.user = 'puppetlabs' config.project = 'puppet-strings' end rescue LoadError desc 'Install github_changelog_generator to get access to automatic changelog generation' task :changelog do raise 'Install github_changelog_generator to get access to automatic changelog generation' end end puppet-strings-2.1.0/codecov.yml000066400000000000000000000002161331446220200166570ustar00rootroot00000000000000--- # disable comments, info can be gotten from the pr status updates, and the comment editing spams the hipchat notifications comment: false puppet-strings-2.1.0/lib/000077500000000000000000000000001331446220200152615ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings.rb000066400000000000000000000052021331446220200206110ustar00rootroot00000000000000# The root module for Puppet Strings. module PuppetStrings # The glob patterns used to search for files to document. DEFAULT_SEARCH_PATTERNS = %w( manifests/**/*.pp functions/**/*.pp types/**/*.pp lib/**/*.rb tasks/*.json plans/*.pp ).freeze # Generates documentation. # @param [Array] search_patterns The search patterns (e.g. manifests/**/*.pp) to look for files. # @param [Hash] options The options hash. # @option options [Boolean] :debug Enable YARD debug output. # @option options [Boolean] :backtrace Enable YARD backtraces. # @option options [String] :markup The YARD markup format to use (defaults to 'markdown'). # @option options [String] :path Write the selected format to a file path # @option options [Boolean] :markdown From the --format option, is the format Markdown? # @option options [Boolean] :json Is the format JSON? # @option options [Array] :yard_args The arguments to pass to yard. # @return [void] def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {}) require 'puppet-strings/yard' PuppetStrings::Yard.setup! # Format the arguments to YARD args = ['doc'] args << '--debug' if options[:debug] args << '--backtrace' if options[:backtrace] args << "-m#{options[:markup] || 'markdown'}" file = nil if options[:json] || options[:markdown] file = if options[:json] options[:path] elsif options[:markdown] options[:path] || "REFERENCE.md" end # Disable output and prevent stats/progress when writing to STDOUT args << '-n' args << '-q' unless file args << '--no-stats' unless file args << '--no-progress' unless file end yard_args = options[:yard_args] args += yard_args if yard_args args += search_patterns # Run YARD YARD::CLI::Yardoc.run(*args) # If outputting JSON, render the output if options[:json] render_json(file) end # If outputting Markdown, render the output if options[:markdown] render_markdown(file) end end def self.puppet_5? Puppet::Util::Package.versioncmp(Puppet.version, "5.0.0") >= 0 end def self.render_json(path) require 'puppet-strings/json' PuppetStrings::Json.render(path) end def self.render_markdown(path) require 'puppet-strings/markdown' PuppetStrings::Markdown.render(path) end # Runs the YARD documentation server. # @param [Array] args The arguments to YARD. def self.run_server(*args) require 'puppet-strings/yard' PuppetStrings::Yard.setup! YARD::CLI::Server.run(*args) end end puppet-strings-2.1.0/lib/puppet-strings/000077500000000000000000000000001331446220200202655ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/json.rb000066400000000000000000000051611331446220200215660ustar00rootroot00000000000000require 'json' # The module for JSON related functionality. module PuppetStrings::Json # Renders the current YARD registry as JSON to the given file (or STDOUT if nil). # @param [String] file The path to the output file to render the registry to. If nil, output will be to STDOUT. # @return [void] def self.render(file = nil) document = { puppet_classes: YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash), defined_types: YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash), resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash), providers: YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash), puppet_functions: YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash), puppet_tasks: YARD::Registry.all(:puppet_task).sort_by!(&:name).map!(&:to_hash), puppet_plans: YARD::Registry.all(:puppet_plan).sort_by!(&:name).map!(&:to_hash) # TODO: Need Ruby documentation? } if file File.open(file, 'w') do |f| f.write(JSON.pretty_generate(document)) f.write("\n") end else puts JSON.pretty_generate(document) end end # Converts a list of tags into an array of hashes. # @param [Array] tags List of tags to be converted into an array of hashes. # @return [Array] Returns an array of tag hashes. def self.tags_to_hashes(tags) # Skip over the API tags that are public tags.select { |t| (t.tag_name != 'api' || t.text != 'public') }.map do |t| next t.to_hash if t.respond_to?(:to_hash) tag = { tag_name: t.tag_name } # grab nested information for @option tags if tag[:tag_name] == 'option' tag[:opt_name] = t.pair.name tag[:opt_text] = t.pair.text tag[:opt_types] = t.pair.types tag[:parent] = t.name end tag[:text] = t.text if t.text tag[:types] = t.types if t.types tag[:name] = t.name if t.name tag end end # Converts a YARD::Docstring (or String) to a docstring hash for JSON output. # @param [YARD::Docstring, String] docstring The docstring to convert to a hash. # @param [Array] select_tags List of tags to select. Other tags will be filtered out. # @return [Hash] Returns a hash representation of the given docstring. def self.docstring_to_hash(docstring, select_tags=nil) hash = {} hash[:text] = docstring if docstring.is_a? YARD::Docstring tags = tags_to_hashes(docstring.tags.select { |t| select_tags.nil? || select_tags.include?(t.tag_name.to_sym) }) hash[:tags] = tags unless tags.empty? end hash end end puppet-strings-2.1.0/lib/puppet-strings/markdown.rb000066400000000000000000000026071331446220200224410ustar00rootroot00000000000000require 'puppet-strings/json' # module for parsing Yard Registries and generating markdown module PuppetStrings::Markdown require_relative 'markdown/puppet_classes' require_relative 'markdown/functions' require_relative 'markdown/defined_types' require_relative 'markdown/resource_types' require_relative 'markdown/puppet_tasks' require_relative 'markdown/puppet_plans' require_relative 'markdown/table_of_contents' # generates markdown documentation # @return [String] markdown doc def self.generate final = "# Reference\n" final << "\n\n" final << PuppetStrings::Markdown::TableOfContents.render final << PuppetStrings::Markdown::PuppetClasses.render final << PuppetStrings::Markdown::DefinedTypes.render final << PuppetStrings::Markdown::ResourceTypes.render final << PuppetStrings::Markdown::Functions.render final << PuppetStrings::Markdown::PuppetTasks.render final << PuppetStrings::Markdown::PuppetPlans.render final end # mimicks the behavior of the json render, although path will never be nil # @param [String] path path to destination file def self.render(path = nil) if path.nil? puts generate exit else File.open(path, 'w') { |file| file.write(generate) } YARD::Logger.instance.debug "Wrote markdown to #{path}" end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/000077500000000000000000000000001331446220200221075ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/markdown/base.rb000066400000000000000000000130451331446220200233510ustar00rootroot00000000000000require 'puppet-strings' require 'puppet-strings/json' require 'puppet-strings/yard' module PuppetStrings::Markdown # This class makes elements in a YARD::Registry hash easily accessible for templates. # # Here's an example hash: #{:name=>:klass, # :file=>"(stdin)", # :line=>16, # :inherits=>"foo::bar", # :docstring=> # {:text=>"An overview for a simple class.", # :tags=> # [{:tag_name=>"summary", :text=>"A simple class."}, # {:tag_name=>"since", :text=>"1.0.0"}, # {:tag_name=>"see", :name=>"www.puppet.com"}, # {:tag_name=>"example", # :text=> # "class { 'klass':\n" + # " param1 => 1,\n" + # " param3 => 'foo',\n" + # "}", # :name=>"This is an example"}, # {:tag_name=>"author", :text=>"eputnam"}, # {:tag_name=>"option", :name=>"opts"}, # {:tag_name=>"raise", :text=>"SomeError"}, # {:tag_name=>"param", # :text=>"First param.", # :types=>["Integer"], # :name=>"param1"}, # {:tag_name=>"param", # :text=>"Second param.", # :types=>["Any"], # :name=>"param2"}, # {:tag_name=>"param", # :text=>"Third param.", # :types=>["String"], # :name=>"param3"}]}, # :defaults=>{"param1"=>"1", "param2"=>"undef", "param3"=>"'hi'"}, # :source=> # "class klass (\n" + # " Integer $param1 = 1,\n" + # " $param2 = undef,\n" + # " String $param3 = 'hi'\n" + # ") inherits foo::bar {\n" + # "}"} class Base def initialize(registry, component_type) @type = component_type @registry = registry @tags = registry[:docstring][:tags] || [] end # generate 1:1 tag methods # e.g. {:tag_name=>"author", :text=>"eputnam"} { :return_val => 'return', :since => 'since', :summary => 'summary', :note => 'note', :todo => 'todo' }.each do |method_name, tag_name| # @return [String] unless the tag is nil or the string.length == 0 define_method method_name do @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text] unless @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0].nil? || @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text].length.zero? end end # @return [String] top-level name def name @registry[:name].to_s unless @registry[:name].nil? end # @return [String] 'Overview' text (untagged text) def text @registry[:docstring][:text] unless @registry[:docstring][:text].empty? end # @return [String] data type of return value def return_type @tags.select { |tag| tag[:tag_name] == 'return' }[0][:types][0] unless @tags.select { |tag| tag[:tag_name] == 'return' }[0].nil? end # @return [String] text from @since tag def since @tags.select { |tag| tag[:tag_name] == 'since' }[0][:text] unless @tags.select { |tag| tag[:tag_name] == 'since' }[0].nil? end # @return [Array] @see tag hashes def see @tags.select { |tag| tag[:tag_name] == 'see' } unless @tags.select { |tag| tag[:tag_name] == 'see' }[0].nil? end # @return [Array] parameter tag hashes def params @tags.select { |tag| tag[:tag_name] == 'param' } unless @tags.select { |tag| tag[:tag_name] == 'param' }[0].nil? end # @return [Array] example tag hashes def examples @tags.select { |tag| tag[:tag_name] == 'example' } unless @tags.select { |tag| tag[:tag_name] == 'example' }[0].nil? end # @return [Array] raise tag hashes def raises @tags.select { |tag| tag[:tag_name] == 'raise' } unless @tags.select { |tag| tag[:tag_name] == 'raise' }[0].nil? end # @return [Array] option tag hashes def options @tags.select { |tag| tag[:tag_name] == 'option' } unless @tags.select { |tag| tag[:tag_name] == 'option' }[0].nil? end # @param parameter_name # parameter name to match to option tags # @return [Array] option tag hashes that have a parent parameter_name def options_for_param(parameter_name) opts_for_p = options.select { |o| o[:parent] == parameter_name } unless options.nil? opts_for_p unless opts_for_p.nil? || opts_for_p.length.zero? end # @return [Array] any defaults found for the component def defaults @registry[:defaults] unless @registry[:defaults].nil? end # @return [Hash] information needed for the table of contents def toc_info { name: name.to_s, link: link, desc: summary || @registry[:docstring][:text][0..140].gsub("\n",' '), private: private? } end # @return [String] makes the component name suitable for a GitHub markdown link def link name.delete('::').strip.gsub(' ','-').downcase end # Some return, default, or valid values need to be in backticks. Instead of fu in the handler or code_object, this just does the change on the front. # @param value # any string # @return [String] value or value in backticks if it is in a list def value_string(value) to_symbol = %w[undef true false] if to_symbol.include? value return "`#{value}`" else return value end end def private? result = false api = @tags.find { |tag| tag[:tag_name] == 'api' } unless api.nil? result = api[:text] == 'private' ? true : false end result end # @return [String] full markdown rendering of a component def render(template) file = File.join(File.dirname(__FILE__),"templates/#{template}") ERB.new(File.read(file), nil, '-').result(binding) end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/defined_type.rb000066400000000000000000000004221331446220200250710ustar00rootroot00000000000000require 'puppet-strings/markdown/base' module PuppetStrings::Markdown class DefinedType < Base def initialize(registry) @template = 'classes_and_defines.erb' super(registry, 'defined type') end def render super(@template) end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/defined_types.rb000066400000000000000000000015111331446220200252540ustar00rootroot00000000000000require_relative 'defined_type' module PuppetStrings::Markdown module DefinedTypes # @return [Array] list of defined types def self.in_dtypes arr = YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash) arr.map! { |a| PuppetStrings::Markdown::DefinedType.new(a) } end def self.contains_private? result = false unless in_dtypes.nil? in_dtypes.find { |type| type.private? }.nil? ? false : true end end def self.render final = in_dtypes.length > 0 ? "## Defined types\n\n" : "" in_dtypes.each do |type| final << type.render unless type.private? end final end def self.toc_info final = ["Defined types"] in_dtypes.each do |type| final.push(type.toc_info) end final end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/function.rb000066400000000000000000000017151331446220200242650ustar00rootroot00000000000000require 'puppet-strings/markdown/base' module PuppetStrings::Markdown class Function < Base attr_reader :signatures def initialize(registry) @template = 'function.erb' super(registry, 'function') @signatures = [] registry[:signatures].each do |sig| @signatures.push(Signature.new(sig)) end end def render super(@template) end def type t = @registry[:type] if t =~ /ruby4x/ "Ruby 4.x API" elsif t =~ /ruby3/ "Ruby 3.x API" elsif t =~ /ruby/ "Ruby" else "Puppet Language" end end def error_type(r) "`#{r.split(' ')[0]}`" end def error_text(r) "#{r.split(' ').drop(1).join(' ')}" end end class Function::Signature < Base def initialize(registry) @registry = registry super(@registry, 'function signature') end def signature @registry[:signature] end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/functions.rb000066400000000000000000000015021331446220200244420ustar00rootroot00000000000000require_relative 'function' module PuppetStrings::Markdown module Functions # @return [Array] list of functions def self.in_functions arr = YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash) arr.map! { |a| PuppetStrings::Markdown::Function.new(a) } end def self.contains_private? result = false unless in_functions.nil? in_functions.find { |func| func.private? }.nil? ? false : true end end def self.render final = in_functions.length > 0 ? "## Functions\n\n" : "" in_functions.each do |func| final << func.render unless func.private? end final end def self.toc_info final = ["Functions"] in_functions.each do |func| final.push(func.toc_info) end final end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/puppet_class.rb000066400000000000000000000004131331446220200251340ustar00rootroot00000000000000require 'puppet-strings/markdown/base' module PuppetStrings::Markdown class PuppetClass < Base def initialize(registry) @template = 'classes_and_defines.erb' super(registry, 'class') end def render super(@template) end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/puppet_classes.rb000066400000000000000000000014761331446220200254760ustar00rootroot00000000000000require_relative 'puppet_class' module PuppetStrings::Markdown module PuppetClasses # @return [Array] list of classes def self.in_classes arr = YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash) arr.map! { |a| PuppetStrings::Markdown::PuppetClass.new(a) } end def self.contains_private? result = false unless in_classes.nil? in_classes.find { |klass| klass.private? }.nil? ? false : true end end def self.render final = in_classes.length > 0 ? "## Classes\n\n" : "" in_classes.each do |klass| final << klass.render unless klass.private? end final end def self.toc_info final = ["Classes"] in_classes.each do |klass| final.push(klass.toc_info) end final end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/puppet_plan.rb000066400000000000000000000004111331446220200247570ustar00rootroot00000000000000require 'puppet-strings/markdown/base' module PuppetStrings::Markdown class PuppetPlan < Base def initialize(registry) @template = 'classes_and_defines.erb' super(registry, 'plan') end def render super(@template) end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/puppet_plans.rb000066400000000000000000000014421331446220200251470ustar00rootroot00000000000000require_relative 'puppet_plan' module PuppetStrings::Markdown module PuppetPlans # @return [Array] list of classes def self.in_plans arr = YARD::Registry.all(:puppet_plan).sort_by!(&:name).map!(&:to_hash) arr.map! { |a| PuppetStrings::Markdown::PuppetPlan.new(a) } end def self.contains_private? result = false unless in_plans.nil? in_plans.find { |plan| plan.private? }.nil? ? false : true end end def self.render final = in_plans.length > 0 ? "## Plans\n\n" : "" in_plans.each do |plan| final << plan.render unless plan.private? end final end def self.toc_info final = ["Plans"] in_plans.each do |plan| final.push(plan.toc_info) end final end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/puppet_task.rb000066400000000000000000000006311331446220200247730ustar00rootroot00000000000000require 'puppet-strings/markdown/base' module PuppetStrings::Markdown class PuppetTask < Base def initialize(registry) @template = 'puppet_task.erb' @registry = registry super(registry, 'task') end def render super(@template) end def supports_noop @registry[:supports_noop] end def input_method @registry[:input_method] end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/puppet_tasks.rb000066400000000000000000000012611331446220200251560ustar00rootroot00000000000000require_relative 'puppet_task' module PuppetStrings::Markdown module PuppetTasks # @return [Array] list of classes def self.in_tasks arr = YARD::Registry.all(:puppet_task).sort_by!(&:name).map!(&:to_hash) arr.map! { |a| PuppetStrings::Markdown::PuppetTask.new(a) } end def self.contains_private? false end def self.render final = in_tasks.length > 0 ? "## Tasks\n\n" : "" in_tasks.each do |task| final << task.render unless task.private? end final end def self.toc_info final = ["Tasks"] in_tasks.each do |task| final.push(task.toc_info) end final end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/resource_type.rb000066400000000000000000000007721331446220200253320ustar00rootroot00000000000000require 'puppet-strings/markdown/base' module PuppetStrings::Markdown class ResourceType < Base def initialize(registry) @template = 'resource_type.erb' super(registry, 'type') end def render super(@template) end def properties @registry[:properties] end def parameters @registry[:parameters] end def regex_in_data_type?(data_type) m = data_type.match(/\w+\[\/.*\/\]/) m unless m.nil? || m.length.zero? end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/resource_types.rb000066400000000000000000000015071331446220200255120ustar00rootroot00000000000000require_relative 'resource_type' module PuppetStrings::Markdown module ResourceTypes # @return [Array] list of resource types def self.in_rtypes arr = YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash) arr.map! { |a| PuppetStrings::Markdown::ResourceType.new(a) } end def self.contains_private? result = false unless in_rtypes.nil? in_rtypes.find { |type| type.private? }.nil? ? false : true end end def self.render final = in_rtypes.length > 0 ? "## Resource types\n\n" : "" in_rtypes.each do |type| final << type.render unless type.private? end final end def self.toc_info final = ["Resource types"] in_rtypes.each do |type| final.push(type.toc_info) end final end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/table_of_contents.rb000066400000000000000000000013051331446220200261230ustar00rootroot00000000000000module PuppetStrings::Markdown module TableOfContents def self.render final = "## Table of Contents\n\n" [PuppetStrings::Markdown::PuppetClasses, PuppetStrings::Markdown::DefinedTypes, PuppetStrings::Markdown::ResourceTypes, PuppetStrings::Markdown::Functions, PuppetStrings::Markdown::PuppetTasks, PuppetStrings::Markdown::PuppetPlans].each do |r| toc = r.toc_info group_name = toc.shift group = toc priv = r.contains_private? template = File.join(File.dirname(__FILE__),"templates/table_of_contents.erb") final << ERB.new(File.read(template), nil, '-').result(binding) end final end end end puppet-strings-2.1.0/lib/puppet-strings/markdown/templates/000077500000000000000000000000001331446220200241055ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/markdown/templates/classes_and_defines.erb000066400000000000000000000022661331446220200305610ustar00rootroot00000000000000### <%= name %> <% if text -%> <%= text %> <% elsif summary -%> <%= summary %> <% else -%> <%= "The #{name} class." %> <% end -%> <% if todo -%> * **TODO** <%= todo %> <% end -%> <% if note -%> * **Note** <%= note %> <% end -%> <% if since -%> * **Since** <%= since %> <% end -%> <% if see -%> * **See also** <% see.each do |sa| -%> <% if sa[:name] -%> <%= sa[:name] %> <% end -%> <% if sa[:text] -%> <%= sa[:text] %> <% end -%> <% end -%> <% end -%> <% if examples -%> #### Examples <% examples.each do |eg| -%> ##### <%= eg[:name] %> ```puppet <%= eg[:text] %> ``` <% end -%> <% end -%> <% if params -%> #### Parameters The following parameters are available in the `<%= name %>` <%= @type %>. <% params.each do |param| -%> ##### `<%= param[:name] %>` <% if param[:types] -%> Data type: `<%= param[:types].join(', ') -%>` <% end -%> <%= param[:text] %> <% if options_for_param(param[:name]) -%> Options: <% options_for_param(param[:name]).each do |o| -%> * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %> <% end -%> <% end -%> <% if defaults && defaults[param[:name]] -%> Default value: <%= value_string(defaults[param[:name]]) %> <% end -%> <% end -%> <% end -%> puppet-strings-2.1.0/lib/puppet-strings/markdown/templates/function.erb000066400000000000000000000021771331446220200264330ustar00rootroot00000000000000### <%= name %> Type: <%= type %> <% if text -%> <%= text %> <% elsif summary -%> <%= summary %> <% else -%> <%= "The #{name} function." %> <% end -%> <% if todo -%> * **TODO** <%= todo %> <% end -%> <% if note -%> * **Note** <%= note %> <% end -%> <% signatures.each do |sig| -%> #### `<%= sig.signature %>` <% if sig.text -%> <%= sig.text %> <% elsif sig.summary -%> <%= sig.summary %> <% else -%> <%= "The #{name} function." %> <% end -%> <% if sig.note -%> * **Note** <%= sig.note %> <% end -%> <% if sig.return_type -%> Returns: `<%= sig.return_type %>`<% if sig.return_val %> <%= sig.return_val %><% end %> <% end -%> <% if raises -%> Raises: <% raises.each do |r| -%> * <%= error_type(r[:text]) %> <%= error_text(r[:text]) %> <% end -%> <% end -%> <% if sig.params -%> <% sig.params.each do |param| -%> ##### `<%= param[:name] %>` Data type: `<%= param[:types][0] %>` <%= param[:text] %> <% if sig.options_for_param(param[:name]) -%> Options: <% sig.options_for_param(param[:name]).each do |o| -%> * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %> <% end -%> <% end -%> <% end -%> <% end -%> <% end -%> puppet-strings-2.1.0/lib/puppet-strings/markdown/templates/puppet_task.erb000066400000000000000000000006101331446220200271330ustar00rootroot00000000000000### <%= name %> <% if text -%> <%= text %> <% elsif summary -%> <%= summary %> <% else -%> <%= "The #{name} task." %> <% end -%> **Supports noop?** <%= supports_noop %> <% if params -%> #### Parameters <% params.each do |param| -%> ##### `<%= param[:name] %>` <% if param[:types] -%> Data type: `<%= param[:types].join(', ') -%>` <% end -%> <%= param[:text] %> <% end -%> <% end -%> puppet-strings-2.1.0/lib/puppet-strings/markdown/templates/resource_type.erb000066400000000000000000000050401331446220200274660ustar00rootroot00000000000000### <%= name %> <% if text -%> <%= text %> <% elsif summary -%> <%= summary %> <% else -%> <%= "The #{name} type." %> <% end -%> <% if todo -%> * **TODO** <%= todo %> <% end -%> <% if note -%> * **Note** <%= note %> <% end -%> <% if since -%> * **Since** <%= since %> <% end -%> <% if see -%> * **See also** <% see.each do |sa| -%> <% if sa[:name] -%> <%= sa[:name] %> <% end -%> <% if sa[:text] -%> <%= sa[:text] %> <% end -%> <% end -%> <% end -%> <% if examples -%> #### Examples <% examples.each do |eg| -%> ##### <%= eg[:name] %> ```puppet <%= eg[:text] %> ``` <% end -%> <% end -%> <% if properties -%> #### Properties The following properties are available in the `<%= name %>` <%= @type %>. <% properties.each do |prop| -%> ##### `<%= prop[:name] %>` <% if prop[:values] -%> Valid values: <%= prop[:values].map { |value| value_string(value) }.join(', ') %> <% end -%> <% if prop[:isnamevar] -%> namevar <% end -%> <% if prop[:aliases] -%> Aliases: <%= prop[:aliases].to_s.delete('{').delete('}') %> <% end -%> <% if prop[:data_type] -%> Data type: `<%= prop[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(prop[:data_type]) %> <% end -%> <%= prop[:description] %> <% if options_for_param(prop[:name]) -%> Options: <% options_for_param(prop[:name]).each do |o| -%> * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %> <% end -%> <% end -%> <% if prop[:default] -%> Default value: <%= prop[:default] %> <% end -%> <% end -%> <% end -%> <% if parameters -%> #### Parameters The following parameters are available in the `<%= name %>` <%= @type %>. <% parameters.each do |param| -%> ##### `<%= param[:name] %>` <% if param[:values] -%> Valid values: <%= param[:values].map { |value| value_string(value) }.join(', ') %> <% end -%> <% if param[:isnamevar] -%> namevar <% end -%> <% if param[:aliases] -%> Aliases: <%= param[:aliases].to_s.delete('{').delete('}') %> <% end -%> <% if param[:data_type] -%> Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(param[:data_type]) %> <% end -%> <%= param[:description] %> <% if options_for_param(param[:name]) -%> Options: <% options_for_param(param[:name]).each do |o| -%> * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %> <% end -%> <% end -%> <% if param[:default] -%> Default value: <%= value_string(param[:default]) %> <% end -%> <% end -%> <% end -%> puppet-strings-2.1.0/lib/puppet-strings/markdown/templates/table_of_contents.erb000066400000000000000000000010161331446220200302650ustar00rootroot00000000000000<% if group.length > 0 -%> **<%= group_name %>** <% if priv -%> _Public <%= group_name %>_ <% group.each do |item| -%> <% unless item[:private] -%> * [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %> <% end -%> <% end -%> _Private <%= group_name %>_ <% group.each do |item| -%> <% if item[:private] -%> * `<%= item[:name] %>`: <%= item[:desc] %> <% end -%> <% end -%> <% else -%> <% group.each do |item| -%> * [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %> <% end -%> <% end -%> <% end -%> puppet-strings-2.1.0/lib/puppet-strings/monkey_patches/000077500000000000000000000000001331446220200232765ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/monkey_patches/display_object_command.rb000066400000000000000000000006141331446220200303150ustar00rootroot00000000000000# Monkey patch URL decoding in object displays. Usually :: is interpreted as a # namespace, but this is disabled in our base object, and so instead gets # URL-encoded. require 'yard/server/commands/display_object_command' class YARD::Server::Commands::DisplayObjectCommand private alias_method :object_path_yard, :object_path def object_path object_path_yard.gsub('_3A', ':') end end puppet-strings-2.1.0/lib/puppet-strings/tasks.rb000066400000000000000000000003411331446220200217350ustar00rootroot00000000000000require 'rake' require 'rake/tasklib' module PuppetStrings # The module for Puppet Strings rake tasks. module Tasks require 'puppet-strings/tasks/generate.rb' require 'puppet-strings/tasks/gh_pages.rb' end end puppet-strings-2.1.0/lib/puppet-strings/tasks/000077500000000000000000000000001331446220200214125ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/tasks/generate.rb000066400000000000000000000034401331446220200235320ustar00rootroot00000000000000require 'puppet-strings' # Implements the strings:generate task. namespace :strings do desc 'Generate Puppet documentation with YARD.' 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 options = { debug: args[:debug] == 'true', backtrace: args[:backtrace] == 'true', markup: args[:markup] || 'markdown', } 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 PuppetStrings.generate(patterns, options) end end puppet-strings-2.1.0/lib/puppet-strings/tasks/gh_pages.rb000066400000000000000000000033101331446220200235110ustar00rootroot00000000000000require 'puppet-strings/tasks' namespace :strings do namespace :gh_pages do task :checkout do if Dir.exist?('doc') fail "The 'doc' directory (#{File.expand_path('doc')}) is not a Git repository! Remove it and run the Rake task again." unless Dir.exist?('doc/.git') Dir.chdir('doc') do system 'git checkout gh-pages' system 'git pull --rebase origin gh-pages' end else git_uri = `git config --get remote.origin.url`.strip fail "Could not determine the remote URL for origin: ensure the current directory is a Git repro with a remote named 'origin'." unless $?.success? Dir.mkdir('doc') Dir.chdir('doc') do system 'git init' system "git remote add origin #{git_uri}" system 'git pull origin gh-pages' system 'git checkout -b gh-pages' end end end task :configure do unless File.exist?(File.join('doc', '_config.yml')) Dir.chdir('doc') do File.open('_config.yml', 'w+') {|f| f.write("include: _index.html") } end end end task :push do output = `git describe --long 2>/dev/null` # If a project has never been tagged, fall back to latest SHA output.empty? ? git_sha = `git log --pretty=format:'%H' -n 1` : git_sha = output Dir.chdir('doc') do system 'git add .' system "git commit -m '[strings] Generated Documentation Update at Revision #{git_sha}'" system 'git push origin gh-pages -f' end end desc 'Update docs on the gh-pages branch and push to GitHub.' task :update => [ :checkout, :'strings:generate', :configure, :push, ] end end puppet-strings-2.1.0/lib/puppet-strings/version.rb000066400000000000000000000000641331446220200222770ustar00rootroot00000000000000module PuppetStrings VERSION = '2.1.0'.freeze end puppet-strings-2.1.0/lib/puppet-strings/yard.rb000066400000000000000000000072121331446220200215530ustar00rootroot00000000000000require 'yard' # Module for YARD related functionality. module PuppetStrings::Yard require 'puppet-strings/yard/code_objects' require 'puppet-strings/yard/handlers' require 'puppet-strings/yard/tags' require 'puppet-strings/yard/parsers' require 'puppet-strings/monkey_patches/display_object_command' # Sets up YARD for use with puppet-strings. # @return [void] def self.setup! # Register the template path YARD::Templates::Engine.register_template_path(File.join(File.dirname(__FILE__), 'yard', 'templates')) # Register the Puppet parser YARD::Parser::SourceParser.register_parser_type(:puppet, PuppetStrings::Yard::Parsers::Puppet::Parser, ['pp']) YARD::Parser::SourceParser.register_parser_type(:json, PuppetStrings::Yard::Parsers::JSON::Parser, ['json']) # Register our handlers YARD::Handlers::Processor.register_handler_namespace(:puppet, PuppetStrings::Yard::Handlers::Puppet) YARD::Handlers::Processor.register_handler_namespace(:puppet_ruby, PuppetStrings::Yard::Handlers::Ruby) YARD::Handlers::Processor.register_handler_namespace(:json, PuppetStrings::Yard::Handlers::JSON) # Register the tag directives PuppetStrings::Yard::Tags::ParameterDirective.register! PuppetStrings::Yard::Tags::PropertyDirective.register! # Register the summary tag PuppetStrings::Yard::Tags::SummaryTag.register! # Ignore documentation on Puppet DSL calls # This prevents the YARD DSL parser from emitting warnings for Puppet's Ruby DSL YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS['create_function'] = true YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS['newtype'] = true end end # Monkey patch YARD::CLI::Yardoc#all_objects to return our custom code objects. # @private class YARD::CLI::Yardoc def all_objects YARD::Registry.all( :root, :module, :class, :puppet_class, :puppet_defined_type, :puppet_type, :puppet_provider, :puppet_function, :puppet_task, :puppet_plan ) end end # Monkey patch the stats object to return statistics for our objects. # This is the recommended way to add custom stats. # @private class YARD::CLI::Stats def stats_for_puppet_classes output 'Puppet Classes', *type_statistics_all(:puppet_class) end def stats_for_puppet_defined_types output 'Puppet Defined Types', *type_statistics_all(:puppet_defined_type) end def stats_for_puppet_types output 'Puppet Types', *type_statistics_all(:puppet_type) end def stats_for_puppet_providers output 'Puppet Providers', *type_statistics_all(:puppet_provider) end def stats_for_puppet_functions output 'Puppet Functions', *type_statistics_all(:puppet_function) end def stats_for_puppet_tasks output 'Puppet Tasks', *type_statistics_all(:puppet_task) end def stats_for_puppet_plans return unless PuppetStrings.puppet_5? output 'Puppet Plans', *type_statistics_all(:puppet_plan) end def output(name, data, undoc = nil) # Monkey patch output to accommodate our larger header widths @total += data if data.is_a?(Integer) && undoc @undocumented += undoc if undoc.is_a?(Integer) data = if undoc ('%5s (% 5d undocumented)' % [data, undoc]) else '%5s' % data end log.puts('%-21s %s' % [name + ':', data]) end # This differs from the YARD implementation in that it considers # a docstring without text but with tags to be undocumented. def type_statistics_all(type) objs = all_objects.select {|m| m.type == type } undoc = objs.find_all {|m| m.docstring.all.empty? } @undoc_list |= undoc if @undoc_list [objs.size, undoc.size] end end puppet-strings-2.1.0/lib/puppet-strings/yard/000077500000000000000000000000001331446220200212245ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/code_objects.rb000066400000000000000000000007061331446220200241770ustar00rootroot00000000000000# The module for custom YARD code objects. module PuppetStrings::Yard::CodeObjects require 'puppet-strings/yard/code_objects/class' require 'puppet-strings/yard/code_objects/defined_type' require 'puppet-strings/yard/code_objects/type' require 'puppet-strings/yard/code_objects/provider' require 'puppet-strings/yard/code_objects/function' require 'puppet-strings/yard/code_objects/task' require 'puppet-strings/yard/code_objects/plan' end puppet-strings-2.1.0/lib/puppet-strings/yard/code_objects/000077500000000000000000000000001331446220200236475ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/code_objects/base.rb000066400000000000000000000012101331446220200251000ustar00rootroot00000000000000# Implements the base code object. class PuppetStrings::Yard::CodeObjects::Base < YARD::CodeObjects::NamespaceObject # Allocates a new code object. # @param [Array] args The arguments to initialize the code object with. # @return Returns the code object. def self.new(*args) # Skip the super class' implementation because it detects :: in names and this will cause namespaces in the output we don't want object = Object.class.instance_method(:new).bind(self).call(*args) existing = YARD::Registry.at(object.path) object = existing if existing && existing.class == self yield(object) if block_given? object end end puppet-strings-2.1.0/lib/puppet-strings/yard/code_objects/class.rb000066400000000000000000000036501331446220200253050ustar00rootroot00000000000000require 'puppet-strings/yard/code_objects/group' # Implements the group for Puppet classes. class PuppetStrings::Yard::CodeObjects::Classes < PuppetStrings::Yard::CodeObjects::Group # Gets the singleton instance of the group. # @return Returns the singleton instance of the group. def self.instance super(:puppet_classes) end # Gets the display name of the group. # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces. # @return [String] Returns the display name of the group. def name(prefix = false) 'Puppet Classes' end end # Implements the Puppet class code object. class PuppetStrings::Yard::CodeObjects::Class < PuppetStrings::Yard::CodeObjects::Base attr_reader :statement attr_reader :parameters # Initializes a Puppet class code object. # @param [PuppetStrings::Parsers::ClassStatement] statement The class statement that was parsed. # @return [void] def initialize(statement) @statement = statement @parameters = statement.parameters.map { |p| [p.name, p.value] } super(PuppetStrings::Yard::CodeObjects::Classes.instance, statement.name) end # Gets the type of the code object. # @return Returns the type of the code object. def type :puppet_class end # Gets the source of the code object. # @return Returns the source of the code object. def source @statement.source end # Converts the code object to a hash representation. # @return [Hash] Returns a hash representation of the code object. def to_hash hash = {} hash[:name] = name hash[:file] = file hash[:line] = line hash[:inherits] = statement.parent_class if statement.parent_class hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten] hash[:defaults] = defaults unless defaults.empty? hash[:source] = source unless source && source.empty? hash end end puppet-strings-2.1.0/lib/puppet-strings/yard/code_objects/defined_type.rb000066400000000000000000000036361331446220200266430ustar00rootroot00000000000000require 'puppet-strings/yard/code_objects/group' # Implements the group for Puppet defined types. class PuppetStrings::Yard::CodeObjects::DefinedTypes < PuppetStrings::Yard::CodeObjects::Group # Gets the singleton instance of the group. # @return Returns the singleton instance of the group. def self.instance super(:puppet_defined_types) end # Gets the display name of the group. # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces. # @return [String] Returns the display name of the group. def name(prefix = false) 'Defined Types' end end # Implements the Puppet defined type code object. class PuppetStrings::Yard::CodeObjects::DefinedType < PuppetStrings::Yard::CodeObjects::Base attr_reader :statement attr_reader :parameters # Initializes a Puppet defined type code object. # @param [PuppetStrings::Parsers::DefinedTypeStatement] statement The defined type statement that was parsed. # @return [void] def initialize(statement) @statement = statement @parameters = statement.parameters.map { |p| [p.name, p.value] } super(PuppetStrings::Yard::CodeObjects::DefinedTypes.instance, statement.name) end # Gets the type of the code object. # @return Returns the type of the code object. def type :puppet_defined_type end # Gets the source of the code object. # @return Returns the source of the code object. def source @statement.source end # Converts the code object to a hash representation. # @return [Hash] Returns a hash representation of the code object. def to_hash hash = {} hash[:name] = name hash[:file] = file hash[:line] = line hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten] hash[:defaults] = defaults unless defaults.empty? hash[:source] = source unless source && source.empty? hash end end puppet-strings-2.1.0/lib/puppet-strings/yard/code_objects/function.rb000066400000000000000000000066441331446220200260330ustar00rootroot00000000000000require 'puppet-strings/yard/code_objects/group' # Implements the group for Puppet functions. class PuppetStrings::Yard::CodeObjects::Functions < PuppetStrings::Yard::CodeObjects::Group # Gets the singleton instance of the group. # @param [Symbol] type The function type to get the group for. # @return Returns the singleton instance of the group. def self.instance(type) super("puppet_functions_#{type}".intern) end # Gets the display name of the group. # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces. # @return [String] Returns the display name of the group. def name(prefix = false) 'Puppet Functions' end end # Implements the Puppet function code object. class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObjects::Base # Identifier for 3.x Ruby API functions RUBY_3X = :ruby3x # Identifier for 4.x Ruby API functions RUBY_4X = :ruby4x # Identifier for Puppet language functions PUPPET = :puppet attr_accessor :parameters # Initializes a Puppet function code object. # @param [String] name The name of the function. # @param [Symbol] function_type The type of function (e.g. :ruby3x, :ruby4x, :puppet) # @return [void] def initialize(name, function_type) super(PuppetStrings::Yard::CodeObjects::Functions.instance(function_type), name) @parameters = [] @function_type = function_type end # Gets the type of the code object. # @return Returns the type of the code object. def type :puppet_function end # Gets the function type display string. # @return Returns the function type display string. def function_type case @function_type when RUBY_3X 'Ruby 3.x API' when RUBY_4X 'Ruby 4.x API' else 'Puppet Language' end end # Gets the Puppet signature of the function (single overload only). # @return [String] Returns the Puppet signature of the function. def signature return '' if self.has_tag? :overload tags = self.tags(:param) args = @parameters.map do |parameter| name, default = parameter tag = tags.find { |t| t.name == name } if tags type = tag && tag.types ? "#{tag.type} " : 'Any ' prefix = "#{name[0]}" if name.start_with?('*', '&') name = name[1..-1] if prefix default = " = #{default}" if default "#{type}#{prefix}$#{name}#{default}" end.join(', ') @name.to_s + '(' + args + ')' end # Converts the code object to a hash representation. # @return [Hash] Returns a hash representation of the code object. def to_hash hash = {} hash[:name] = name hash[:file] = file hash[:line] = line hash[:type] = @function_type.to_s hash[:signatures] = [] if self.has_tag? :overload # loop over overloads and append onto the signatures array self.tags(:overload).each do |o| hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Json.docstring_to_hash(o.docstring, [:param, :option, :return]) } end else hash[:signatures] << { :signature => self.signature, :docstring => PuppetStrings::Json.docstring_to_hash(docstring, [:param, :option, :return]) } end hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten] hash[:defaults] = defaults unless defaults.empty? hash[:source] = source unless source && source.empty? hash end end puppet-strings-2.1.0/lib/puppet-strings/yard/code_objects/group.rb000066400000000000000000000016171331446220200253350ustar00rootroot00000000000000require 'puppet-strings/yard/code_objects/base' # Implements the base class for "groups". # # A group behaves like a YARD namespace object, but displays differently in the HTML output. class PuppetStrings::Yard::CodeObjects::Group < PuppetStrings::Yard::CodeObjects::Base # Gets the singleton instance of the group. # @param [Symbol] key The key to lookup the group for. # @return Returns the singleton instance of the group. def self.instance(key) instance = P(:root, key) return instance unless instance.is_a?(YARD::CodeObjects::Proxy) instance = self.new(:root, key) instance.visibility = :hidden P(:root).children << instance instance end # Gets the path to the group. # @return [String] Returns the path to the group. def path @name.to_s end # Gets the type of the group. # @return [Symbol] Returns the type of the group. def type @name end end puppet-strings-2.1.0/lib/puppet-strings/yard/code_objects/plan.rb000066400000000000000000000033761331446220200251370ustar00rootroot00000000000000require 'puppet-strings/yard/code_objects/group' class PuppetStrings::Yard::CodeObjects::Plans < PuppetStrings::Yard::CodeObjects::Group # Gets the singleton instance of the group. # @return Returns the singleton instance of the group. def self.instance super(:puppet_plans) end # Gets the display name of the group. # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces. # @return [String] Returns the display name of the group. def name(prefix = false) 'Puppet Plans' end end class PuppetStrings::Yard::CodeObjects::Plan < PuppetStrings::Yard::CodeObjects::Base attr_reader :statement attr_reader :parameters # Initializes a Puppet plan code object. # @param [PuppetStrings::Parsers::PlanStatement] statement The plan statement that was parsed. # @return [void] def initialize(statement) @statement = statement @parameters = statement.parameters.map { |p| [p.name, p.value] } super(PuppetStrings::Yard::CodeObjects::Plans.instance, statement.name) end # Gets the type of the code object. # @return Returns the type of the code object. def type :puppet_plan end # Gets the source of the code object. # @return Returns the source of the code object. def source @statement.source end # Converts the code object to a hash representation. # @return [Hash] Returns a hash representation of the code object. def to_hash hash = {} hash[:name] = name hash[:file] = file hash[:line] = line hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten] hash[:defaults] = defaults unless defaults.empty? hash[:source] = source unless source && source.empty? hash end end puppet-strings-2.1.0/lib/puppet-strings/yard/code_objects/provider.rb000066400000000000000000000056021331446220200260310ustar00rootroot00000000000000require 'puppet-strings/yard/code_objects/group' # Implements the group for Puppet providers. class PuppetStrings::Yard::CodeObjects::Providers < PuppetStrings::Yard::CodeObjects::Group # Gets the singleton instance of the group. # @param [String] type The resource type name for the provider. # @return Returns the singleton instance of the group. def self.instance(type) super("puppet_providers_#{type}".intern) end # Gets the display name of the group. # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces. # @return [String] Returns the display name of the group. def name(prefix = false) 'Providers' end end # Implements the Puppet provider code object. class PuppetStrings::Yard::CodeObjects::Provider < PuppetStrings::Yard::CodeObjects::Base attr_reader :type_name, :confines, :features, :defaults, :commands # Initializes a Puppet provider code object. # @param [String] type_name The resource type name for the provider. # @param [String] name The name of the provider.s # @return [void] def initialize(type_name, name) @type_name = type_name super(PuppetStrings::Yard::CodeObjects::Providers.instance(type_name), name) end # Gets the type of the code object. # @return Returns the type of the code object. def type :puppet_provider end # Adds a confine to the provider. # @param [String] key The confine's key. # @param [String] value The confine's value. # @return [void] def add_confine(key, value) return unless key && value @confines ||= {} @confines[key] = value end # Adds a feature to the provider. # @param [String] feature The feature to add to the provider. # @return [void] def add_feature(feature) return unless feature @features ||= [] @features << feature end # Adds a default to the provider. # @param [Array] constraints List of related key-pair values for the default. # @return [void] def add_default(constraints) return unless constraints @defaults ||= [] @defaults << constraints end # Adds a command to the provider. # @param [String] key The command's key. # @param [String] value The command's value. # @return [void] def add_command(key, value) return unless key && value @commands ||= {} @commands[key] = value end # Converts the code object to a hash representation. # @return [Hash] Returns a hash representation of the code object. def to_hash hash = {} hash[:name] = name hash[:type_name] = type_name hash[:file] = file hash[:line] = line hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) hash[:confines] = confines if confines && !confines.empty? hash[:features] = features if features && !features.empty? hash[:defaults] = defaults if defaults && !defaults.empty? hash[:commands] = commands if commands && !commands.empty? hash end end puppet-strings-2.1.0/lib/puppet-strings/yard/code_objects/task.rb000066400000000000000000000037151331446220200251440ustar00rootroot00000000000000require 'puppet-strings/yard/code_objects/group' # Implements the group for Puppet tasks. class PuppetStrings::Yard::CodeObjects::Tasks < PuppetStrings::Yard::CodeObjects::Group # Gets the singleton instance of the group. # @return Returns the singleton instance of the group. def self.instance super(:puppet_tasks) end # Gets the display name of the group. # @param [Boolean] prefix whether to show a prefix. # @return [String] Returns the display name of the group. def name(prefix = false) 'Puppet Tasks' end end # Implements the Puppet task code object. class PuppetStrings::Yard::CodeObjects::Task < PuppetStrings::Yard::CodeObjects::Base attr_reader :statement # Initializes a JSON task code object. # @param statement TaskStatement object # @return [void] def initialize(statement) @name = statement.name @statement = statement super(PuppetStrings::Yard::CodeObjects::Tasks.instance, name) end # Gets the type of the code object. # @return Returns the type of the code object. def type :puppet_task end # Gets the source of the code object. # @return Returns the source of the code object. def source @statement.source end def parameters parameters = [] statement.json['parameters'].each do |name,props| parameters.push({ name: name.to_s, tag_name: 'param', text: props['description'] || "", types: [props['type']] || "" }) end parameters end # Converts the code object to a hash representation. # @return [Hash] Returns a hash representation of the code object. def to_hash { name: name.to_s, file: statement.file, line: statement.line, docstring: { text: statement.docstring, tags: parameters }, source: statement.source, supports_noop: statement.json['supports_noop'] || false, input_method: statement.json['input_method'] } end end puppet-strings-2.1.0/lib/puppet-strings/yard/code_objects/type.rb000066400000000000000000000111421331446220200251540ustar00rootroot00000000000000require 'puppet-strings/yard/code_objects/group' require 'puppet-strings/yard/util' # Implements the group for Puppet resource types. class PuppetStrings::Yard::CodeObjects::Types < PuppetStrings::Yard::CodeObjects::Group # Gets the singleton instance of the group. # @return Returns the singleton instance of the group. def self.instance super(:puppet_types) end # Gets the display name of the group. # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces. # @return [String] Returns the display name of the group. def name(prefix = false) 'Resource Types' end end # Implements the Puppet resource type code object. class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects::Base # Represents a resource type parameter. class Parameter attr_reader :name, :values, :aliases attr_accessor :docstring, :isnamevar, :default, :data_type # Initializes a resource type parameter or property. # @param [String] name The name of the parameter or property. # @param [String] docstring The docstring for the parameter or property.s def initialize(name, docstring = nil) @name = name @docstring = docstring || '' @values = [] @data_type = [] @aliases = {} @isnamevar = false @default = nil end # Adds a value to the parameter or property. # @param [String] value The value to add. # @return [void] def add(value) @values << value end # Aliases a value to another value. # @param [String] new The new (alias) value. # @param [String] old The old (existing) value. # @return [void] def alias(new, old) @values << new unless @values.include? new @aliases[new] = old end # Converts the parameter to a hash representation. # @return [Hash] Returns a hash representation of the parameter. def to_hash hash = {} hash[:name] = name hash[:description] = docstring unless docstring.empty? hash[:values] = values unless values.empty? hash[:data_type] = data_type unless data_type.empty? hash[:aliases] = aliases unless aliases.empty? hash[:isnamevar] = true if isnamevar hash[:default] = default if default hash end end # Represents a resource type property (same attributes as a parameter). class Property < Parameter end # Represents a resource type feature. class Feature attr_reader :name, :docstring # Initializes a new feature. # @param [String] name The name of the feature. # @param [String] docstring The docstring of the feature. def initialize(name, docstring) @name = name @docstring = PuppetStrings::Yard::Util.scrub_string(docstring).gsub("\n", ' ') end # Converts the feature to a hash representation. # @return [Hash] Returns a hash representation of the feature. def to_hash hash = {} hash[:name] = name hash[:description] = docstring unless docstring.empty? hash end end attr_reader :properties, :parameters, :features # Initializes a new resource type. # @param [String] name The resource type name. # @return [void] def initialize(name) super(PuppetStrings::Yard::CodeObjects::Types.instance, name) end # Gets the type of the code object. # @return Returns the type of the code object. def type :puppet_type end # Adds a parameter to the resource type # @param [PuppetStrings::Yard::CodeObjects::Type::Parameter] parameter The parameter to add. # @return [void] def add_parameter(parameter) @parameters ||= [] @parameters << parameter end # Adds a property to the resource type # @param [PuppetStrings::Yard::CodeObjects::Type::Property] property The property to add. # @return [void] def add_property(property) @properties ||= [] @properties << property end # Adds a feature to the resource type. # @param [PuppetStrings::Yard::CodeObjects::Type::Feature] feature The feature to add. # @return [void] def add_feature(feature) @features ||= [] @features << feature end # Converts the code object to a hash representation. # @return [Hash] Returns a hash representation of the code object. def to_hash hash = {} hash[:name] = name hash[:file] = file hash[:line] = line hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) hash[:properties] = properties.map(&:to_hash) if properties && !properties.empty? hash[:parameters] = parameters.map(&:to_hash) if parameters && !parameters.empty? hash[:features] = features.map(&:to_hash) if features && !features.empty? hash end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers.rb000066400000000000000000000015371331446220200233570ustar00rootroot00000000000000# The module for custom YARD handlers. module PuppetStrings::Yard::Handlers # The module for custom Ruby YARD handlers. module Ruby require 'puppet-strings/yard/handlers/ruby/type_handler' require 'puppet-strings/yard/handlers/ruby/rsapi_handler' require 'puppet-strings/yard/handlers/ruby/provider_handler' require 'puppet-strings/yard/handlers/ruby/function_handler' end # The module for custom JSON YARD handlers. module JSON require 'puppet-strings/yard/handlers/json/task_handler' end # The module for custom Puppet YARD handlers. module Puppet require 'puppet-strings/yard/handlers/puppet/class_handler' require 'puppet-strings/yard/handlers/puppet/defined_type_handler' require 'puppet-strings/yard/handlers/puppet/function_handler' require 'puppet-strings/yard/handlers/puppet/plan_handler' end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/000077500000000000000000000000001331446220200230245ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/helpers.rb000066400000000000000000000005641331446220200250200ustar00rootroot00000000000000module PuppetStrings::Yard::Handlers::Helpers # Logs a warning if a summary tag has more than 140 characters def self.validate_summary_tag(object) if object.has_tag?(:summary) && object.tag(:summary).text.length > 140 log.warn "The length of the summary for #{object.type} '#{object.name}' exceeds the recommended limit of 140 characters." end end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/json/000077500000000000000000000000001331446220200237755ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/json/base.rb000066400000000000000000000002471331446220200252370ustar00rootroot00000000000000class PuppetStrings::Yard::Handlers::JSON::Base < YARD::Handlers::Base def self.handles?(statement) handlers.any? {|handler| statement.is_a?(handler)} end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/json/task_handler.rb000066400000000000000000000015741331446220200267700ustar00rootroot00000000000000require 'puppet-strings/yard/handlers/json/base' require 'puppet-strings/yard/parsers' require 'puppet-strings/yard/parsers/json/parser' class PuppetStrings::Yard::Handlers::JSON::TaskHandler < PuppetStrings::Yard::Handlers::JSON::Base handles PuppetStrings::Yard::Parsers::JSON::TaskStatement namespace_only process do object = PuppetStrings::Yard::CodeObjects::Task.new(statement) register object @kind = "Puppet Task #{object.name}." @statement = statement validate_description validate_params end def validate_description log.warn "Missing a description for #{@kind}." if @statement.docstring.empty? end def validate_params unless @statement.parameters.empty? @statement.parameters.each do |param, val| log.warn "Missing description for param '#{param}' in #{@kind}" if val['description'].nil? end end end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/puppet/000077500000000000000000000000001331446220200243415ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/puppet/base.rb000066400000000000000000000037631331446220200256110ustar00rootroot00000000000000# Implements the base handler for Puppet language handlers. class PuppetStrings::Yard::Handlers::Puppet::Base < YARD::Handlers::Base # Determine sif the handler handles the given statement. # @param statement The statement that was parsed. # @return [Boolean] Returns true if the statement is handled by this handler or false if not. def self.handles?(statement) handlers.any? {|handler| statement.is_a?(handler)} end protected # Sets the parameter tag types for the given code object. # This also performs some validation on the parameter tags. # @param object The code object to set the parameter tag types for. # @return [void] def set_parameter_types(object) # Ensure there is an actual parameter for each parameter tag tags = object.tags(:param) tags.each do |tag| next if statement.parameters.find { |p| tag.name == p.name } log.warn "The @param tag for parameter '#{tag.name}' has no matching parameter at #{statement.file}:#{statement.line}." unless tag.name == 'name' || tag.name == 'title' end # Assign the types for the parameter statement.parameters.each do |parameter| tag = tags.find { |t| t.name == parameter.name } unless tag log.warn "Missing @param tag for parameter '#{parameter.name}' near #{statement.file}:#{statement.line}." unless object.docstring.empty? # Add a tag with an empty docstring object.add_tag YARD::Tags::Tag.new(:param, '', [parameter.type || 'Any'], parameter.name) next end # Warn if the parameter type and tag types don't match log.warn "The type of the @param tag for parameter '#{parameter.name}' does not match the parameter type specification near #{statement.file}:#{statement.line}: ignoring in favor of parameter type information." if parameter.type && tag.types && !tag.types.empty? && parameter.type != tag.types[0] if parameter.type tag.types = [parameter.type] elsif !tag.types tag.types = ['Any'] end end end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/puppet/class_handler.rb000066400000000000000000000021351331446220200274710ustar00rootroot00000000000000require 'puppet-strings/yard/handlers/helpers' require 'puppet-strings/yard/handlers/puppet/base' require 'puppet-strings/yard/parsers' require 'puppet-strings/yard/code_objects' # Implements the handler for Puppet classes. class PuppetStrings::Yard::Handlers::Puppet::ClassHandler < PuppetStrings::Yard::Handlers::Puppet::Base handles PuppetStrings::Yard::Parsers::Puppet::ClassStatement process do # Register the object object = PuppetStrings::Yard::CodeObjects::Class.new(statement) register object # Log a warning if missing documentation log.warn "Missing documentation for Puppet class '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty? # Set the parameter types set_parameter_types(object) # Mark the class as public if it doesn't already have an api tag object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api # Warn if a summary longer than 140 characters was provided PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/puppet/defined_type_handler.rb000066400000000000000000000022031331446220200310170ustar00rootroot00000000000000require 'puppet-strings/yard/handlers/helpers' require 'puppet-strings/yard/handlers/puppet/base' require 'puppet-strings/yard/parsers' require 'puppet-strings/yard/code_objects' # Implements the handler for Puppet defined types. class PuppetStrings::Yard::Handlers::Puppet::DefinedTypeHandler < PuppetStrings::Yard::Handlers::Puppet::Base handles PuppetStrings::Yard::Parsers::Puppet::DefinedTypeStatement process do # Register the object object = PuppetStrings::Yard::CodeObjects::DefinedType.new(statement) register object # Log a warning if missing documentation log.warn "Missing documentation for Puppet defined type '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty? # Set the parameter types set_parameter_types(object) # Mark the defined type as public if it doesn't already have an api tag object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api # Warn if a summary longer than 140 characters was provided PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/puppet/function_handler.rb000066400000000000000000000037131331446220200302140ustar00rootroot00000000000000require 'puppet-strings/yard/handlers/helpers' require 'puppet-strings/yard/handlers/puppet/base' require 'puppet-strings/yard/parsers' require 'puppet-strings/yard/code_objects' # Implements the handler for Puppet classes. class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Yard::Handlers::Puppet::Base handles PuppetStrings::Yard::Parsers::Puppet::FunctionStatement process do # Register the object object = PuppetStrings::Yard::CodeObjects::Function.new(statement.name, PuppetStrings::Yard::CodeObjects::Function::PUPPET) object.source = statement.source object.source_type = parser.parser_type register object # Log a warning if missing documentation log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty? # Set the parameter tag types set_parameter_types(object) # Add a return tag add_return_tag(object, statement.type) # Set the parameters on the object object.parameters = statement.parameters.map { |p| [p.name, p.value] } # Mark the class as public if it doesn't already have an api tag object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api # Warn if a summary longer than 140 characters was provided PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary end private def add_return_tag(object, type=nil) tag = object.tag(:return) if tag if (type && tag.types.first) && (type != tag.types.first) log.warn "Documented return type does not match return type in function definition near #{statement.file}:#{statement.line}." end tag.types = type ? [type] : tag.types || ['Any'] return end log.warn "Missing @return tag near #{statement.file}:#{statement.line}." type = type || 'Any' object.add_tag YARD::Tags::Tag.new(:return, '', type) end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/puppet/plan_handler.rb000066400000000000000000000021311331446220200273120ustar00rootroot00000000000000require 'puppet-strings/yard/handlers/helpers' require 'puppet-strings/yard/handlers/puppet/base' require 'puppet-strings/yard/parsers' require 'puppet-strings/yard/code_objects' # Implements the handler for Puppet classes. class PuppetStrings::Yard::Handlers::Puppet::PlanHandler < PuppetStrings::Yard::Handlers::Puppet::Base handles PuppetStrings::Yard::Parsers::Puppet::PlanStatement process do # Register the object object = PuppetStrings::Yard::CodeObjects::Plan.new(statement) register object # Log a warning if missing documentation log.warn "Missing documentation for Puppet plan '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty? # Set the parameter types set_parameter_types(object) # Mark the class as public if it doesn't already have an api tag object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api # Warn if a summary longer than 140 characters was provided PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/ruby/000077500000000000000000000000001331446220200240055ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/ruby/base.rb000066400000000000000000000026561331446220200252550ustar00rootroot00000000000000require 'ripper' # Implements the base handler for Ruby language handlers. class PuppetStrings::Yard::Handlers::Ruby::Base < YARD::Handlers::Ruby::Base # A regular expression for detecting the start of a Ruby heredoc. # Note: the first character of the heredoc start may have been cut off by YARD. HEREDOC_START = /^ 1 end source end end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/ruby/function_handler.rb000066400000000000000000000306401331446220200276570ustar00rootroot00000000000000require 'puppet-strings/yard/handlers/helpers' require 'puppet-strings/yard/handlers/ruby/base' require 'puppet-strings/yard/code_objects' require 'puppet-strings/yard/util' # Implements the handler for Puppet functions written in Ruby. class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard::Handlers::Ruby::Base # Represents the list of Puppet 4.x function API methods to support. DISPATCH_METHOD_NAMES = %w( param required_param optional_param repeated_param optional_repeated_param required_repeated_param block_param required_block_param optional_block_param return_type ).freeze namespace_only handles method_call(:create_function) handles method_call(:newfunction) process do # Only accept calls to Puppet::Functions (4.x) or Puppet::Parser::Functions (3.x) # When `newfunction` is separated from the Puppet::Parser::Functions module name by a # newline, YARD ignores the namespace and uses `newfunction` as the source of the # first statement. return unless statement.count > 1 module_name = statement[0].source return unless module_name == 'Puppet::Functions' || module_name == 'Puppet::Parser::Functions' || module_name == 'newfunction' # Create and register the function object is_3x = module_name == 'Puppet::Parser::Functions' || module_name == 'newfunction' object = PuppetStrings::Yard::CodeObjects::Function.new( get_name, is_3x ? PuppetStrings::Yard::CodeObjects::Function::RUBY_3X : PuppetStrings::Yard::CodeObjects::Function::RUBY_4X ) object.source = statement register object # For 3x, parse the doc parameter for the docstring # This must be done after the `register` call above because `register` always uses the statement's docstring if is_3x docstring = get_3x_docstring(object.name) register_docstring(object, docstring, nil) if docstring # Default any typeless param tag to 'Any' object.tags(:param).each do |tag| tag.types = ['Any'] unless tag.types && !tag.types.empty? end # Populate the parameters and the return tag object.parameters = object.tags(:param).map{ |p| [p.name, nil] } add_return_tag(object, statement.file, statement.line) else # For 4x, auto generate tags based on dispatch docstrings add_tags(object) end # Mark the function as public if it doesn't already have an api tag object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api # Warn if a summary longer than 140 characters was provided PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary end private def get_name parameters = statement.parameters(false) raise YARD::Parser::UndocumentableError, "Expected at least one parameter to Puppet::Functions.create_function at #{statement.file}:#{statement.line}." if parameters.empty? name = node_as_string(parameters.first) raise YARD::Parser::UndocumentableError, "Expected a symbol or string literal for first parameter but found '#{parameters.first.type}' at #{statement.file}:#{statement.line}." unless name name end def add_tags(object) log.warn "Missing documentation for Puppet function '#{object.name}' at #{statement.file}:#{statement.line}." if object.docstring.empty? && object.tags.empty? log.warn "The docstring for Puppet 4.x function '#{object.name}' contains @param tags near #{object.file}:#{object.line}: parameter documentation should be made on the dispatch call." unless object.tags(:param).empty? log.warn "The docstring for Puppet 4.x function '#{object.name}' contains @return tags near #{object.file}:#{object.line}: return value documentation should be made on the dispatch call." unless object.tags(:return).empty? log.warn "The docstring for Puppet 4.x function '#{object.name}' contains @overload tags near #{object.file}:#{object.line}: overload tags are automatically generated from the dispatch calls." unless object.tags(:overload).empty? # Delete any existing param/return/overload tags object.docstring.delete_tags(:param) object.docstring.delete_tags(:return) object.docstring.delete_tags(:overload) block = statement.block return unless block && block.count >= 2 # Get the unqualified name of the Puppet function unqualified_name = object.name.to_s.split('::').last # Walk the block statements looking for dispatch calls and methods with the same name as the Puppet function default = nil block[1].children.each do |node| if node.is_a?(YARD::Parser::Ruby::MethodCallNode) add_overload_tag(object, node) elsif node.is_a?(YARD::Parser::Ruby::MethodDefinitionNode) default = node if node.method_name && node.method_name.source == unqualified_name end end # Create an overload for the default method if there is one overloads = object.tags(:overload) if overloads.empty? && default add_method_overload(object, default) overloads = object.tags(:overload) end # If there's only one overload, move the tags to the object itself if overloads.count == 1 overload = overloads.first object.parameters = overload.parameters object.add_tag(*overload.tags) object.docstring.delete_tags(:overload) end end def add_overload_tag(object, node) # Look for a call to a dispatch method with a block return unless node.is_a?(YARD::Parser::Ruby::MethodCallNode) && node.method_name && node.method_name.source == 'dispatch' && node.parameters(false).count == 1 && node.block && node.block.count >= 2 overload_tag = PuppetStrings::Yard::Tags::OverloadTag.new(object.name, node.docstring || '') param_tags = overload_tag.tags(:param) block = nil node.block[1].children.each do |child| next unless child.is_a?(YARD::Parser::Ruby::MethodCallNode) && child.method_name method_name = child.method_name.source next unless DISPATCH_METHOD_NAMES.include?(method_name) if method_name == 'return_type' # Add a return tag if missing overload_tag.add_tag YARD::Tags::Tag.new(:return, '', 'Any') if overload_tag.tag(:return).nil? overload_tag.tag(:return).types = [node_as_string(child.parameters[0])] next end # Check for block if method_name.include?('block') if block log.warn "A duplicate block parameter was found for Puppet function '#{object.name}' at #{child.file}:#{child.line}." next end # Store the block; needs to be appended last block = child next end # Ensure two parameters to parameter definition parameters = child.parameters(false) unless parameters.count == 2 log.warn "Expected 2 arguments to '#{method_name}' call at #{child.file}:#{child.line}: parameter information may not be correct." next end add_param_tag( overload_tag, param_tags, node_as_string(parameters[1]), child.file, child.line, node_as_string(parameters[0]), nil, # TODO: determine default from corresponding Ruby method signature? method_name.include?('optional'), method_name.include?('repeated') ) end # Handle the block parameter after others so it appears last in the list if block parameters = block.parameters(false) if parameters.empty? name = 'block' type = 'Callable' elsif parameters.count == 1 name = node_as_string(parameters[0]) type = 'Callable' elsif parameters.count == 2 type = node_as_string(parameters[0]) name = node_as_string(parameters[1]) else log.warn "Unexpected number of arguments to block definition at #{block.file}:#{block.line}." end if name && type add_param_tag( overload_tag, param_tags, name, block.file, block.line, type, nil, # TODO: determine default from corresponding Ruby method signature? block.method_name.source.include?('optional'), false, # Not repeated true # Is block ) end end # Add a return tag if missing add_return_tag(overload_tag, node.file, node.line) # Validate that tags have parameters validate_overload(overload_tag, node.file, node.line) object.add_tag overload_tag end def add_method_overload(object, node) overload_tag = PuppetStrings::Yard::Tags::OverloadTag.new(object.name, node.docstring || '') param_tags = overload_tag.tags(:param) parameters = node.parameters # Populate the required parameters params = parameters.unnamed_required_params if params params.each do |parameter| add_param_tag( overload_tag, param_tags, parameter.source, parameter.file, parameter.line ) end end # Populate the optional parameters params = parameters.unnamed_optional_params if params params.each do |parameter| add_param_tag( overload_tag, param_tags, parameter[0].source, parameter.file, parameter.line, nil, parameter[1].source, true ) end end # Populate the splat parameter param = parameters.splat_param if param add_param_tag( overload_tag, param_tags, param.source, param.file, param.line, nil, nil, false, true ) end # Populate the block parameter param = parameters.block_param if param add_param_tag( overload_tag, param_tags, param.source, param.file, param.line, nil, nil, false, false, true ) end # Add a return tag if missing add_return_tag(overload_tag, node.file, node.line) # Validate that tags have parameters validate_overload(overload_tag, node.file, node.line) object.add_tag overload_tag end def add_param_tag(object, tags, name, file, line, type = nil, default = nil, optional = false, repeated = false, block = false) tag = tags.find { |tag| tag.name == name } if tags log.warn "Missing @param tag for parameter '#{name}' near #{file}:#{line}." unless tag || object.docstring.all.empty? log.warn "The @param tag for parameter '#{name}' should not contain a type specification near #{file}:#{line}: ignoring in favor of dispatch type information." if type && tag && tag.types && !tag.types.empty? if repeated name = '*' + name elsif block name = '&' + name end unless type type = tag && tag.types ? tag.type : 'Any' end type = optional ? "Optional[#{type}]" : type object.parameters << [name, to_puppet_literal(default)] if tag tag.name = name tag.types = [type] else object.add_tag YARD::Tags::Tag.new(:param, '', type, name) end end def add_return_tag(object, file, line) tag = object.tag(:return) if tag tag.types = ['Any'] unless tag.types return end log.warn "Missing @return tag near #{file}:#{line}." object.add_tag YARD::Tags::Tag.new(:return, '', 'Any') end def validate_overload(overload, file, line) # Validate that tags have matching parameters overload.tags(:param).each do |tag| next if overload.parameters.find { |p| tag.name == p[0] } log.warn "The @param tag for parameter '#{tag.name}' has no matching parameter at #{file}:#{line}." end end def get_3x_docstring(name) parameters = statement.parameters(false) if parameters.count >= 2 parameters[1].each do |kvp| next unless kvp.count == 2 next unless node_as_string(kvp[0]) == 'doc' docstring = node_as_string(kvp[1]) log.error "Failed to parse docstring for 3.x Puppet function '#{name}' near #{statement.file}:#{statement.line}." and return nil unless docstring return PuppetStrings::Yard::Util.scrub_string(docstring) end end # Log a warning for missing docstring log.warn "Missing documentation for Puppet function '#{name}' at #{statement.file}:#{statement.line}." nil end def to_puppet_literal(literal) case literal when 'nil' 'undef' when ':default' 'default' else literal end end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb000066400000000000000000000124131331446220200276620ustar00rootroot00000000000000require 'puppet-strings/yard/handlers/helpers' require 'puppet-strings/yard/handlers/ruby/base' require 'puppet-strings/yard/code_objects' require 'puppet-strings/yard/util' # Implements the handler for Puppet providers written in Ruby. class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard::Handlers::Ruby::Base namespace_only handles method_call(:provide) process do return unless statement.count >= 2 # Check that provide is being called on Puppet::Type.type() type_call = statement[0] return unless type_call.is_a?(YARD::Parser::Ruby::MethodCallNode) && type_call.count >= 3 return unless type_call[0].source == 'Puppet::Type' return unless type_call[2].source == 'type' # Extract the type name type_call_parameters = type_call.parameters(false) return unless type_call_parameters.count >= 1 type_name = node_as_string(type_call_parameters.first) raise YARD::Parser::UndocumentableError, "Could not determine the resource type name for the provider defined at #{statement.file}:#{statement.line}." unless type_name # Register the object object = PuppetStrings::Yard::CodeObjects::Provider.new(type_name, get_name) register object # Extract the docstring register_provider_docstring object # Populate the provider data populate_provider_data object # Mark the provider as public if it doesn't already have an api tag object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api # Warn if a summary longer than 140 characters was provided PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary end private def get_name parameters = statement.parameters(false) raise YARD::Parser::UndocumentableError, "Expected at least one parameter to 'provide' at #{statement.file}:#{statement.line}." if parameters.empty? name = node_as_string(parameters.first) raise YARD::Parser::UndocumentableError, "Expected a symbol or string literal for first parameter but found '#{parameters.first.type}' at #{statement.file}:#{statement.line}." unless name name end def register_provider_docstring(object) # Walk the tree searching for assignments or calls to desc/doc= statement.traverse do |child| if child.type == :assign ivar = child.jump(:ivar) next unless ivar != child && ivar.source == '@doc' docstring = node_as_string(child[1]) log.error "Failed to parse docstring for Puppet provider '#{object.name}' (resource type '#{object.type_name}') near #{child.file}:#{child.line}." and return nil unless docstring register_docstring(object, PuppetStrings::Yard::Util.scrub_string(docstring), nil) return nil elsif child.is_a?(YARD::Parser::Ruby::MethodCallNode) # Look for a call to a dispatch method with a block next unless child.method_name && (child.method_name.source == 'desc' || child.method_name.source == 'doc=') && child.parameters(false).count == 1 docstring = node_as_string(child.parameters[0]) log.error "Failed to parse docstring for Puppet provider '#{object.name}' (resource type '#{object.type_name}') near #{child.file}:#{child.line}." and return nil unless docstring register_docstring(object, PuppetStrings::Yard::Util.scrub_string(docstring), nil) return nil end end log.warn "Missing a description for Puppet provider '#{object.name}' (resource type '#{object.type_name}') at #{statement.file}:#{statement.line}." end def populate_provider_data(object) # Traverse the block looking for confines/defaults/commands block = statement.block return unless block && block.count >= 2 block[1].children.each do |node| next unless node.is_a?(YARD::Parser::Ruby::MethodCallNode) && node.method_name method_name = node.method_name.source parameters = node.parameters(false) if method_name == 'confine' # Add a confine to the object next unless parameters.count >= 1 parameters[0].each do |kvp| next unless kvp.count == 2 object.add_confine(node_as_string(kvp[0]) || kvp[0].source, node_as_string(kvp[1]) || kvp[1].source) end elsif method_name == 'has_feature' || method_name == 'has_features' # Add the features to the object parameters.each do |parameter| object.add_feature(node_as_string(parameter) || parameter.source) end elsif method_name == 'defaultfor' # Add a default to the object next unless parameters.count >= 1 # Some defaultfor statements contain multiple constraints. parameters.each do |kvps| next unless kvps.count >= 1 defaultfor = [] kvps.each do |kvp| defaultfor << [node_as_string(kvp[0]) || kvp[0].source, node_as_string(kvp[1]) || kvp[1].source] end object.add_default(defaultfor) end elsif method_name == 'commands' # Add the commands to the object next unless parameters.count >= 1 parameters[0].each do |kvp| next unless kvp.count == 2 object.add_command(node_as_string(kvp[0]) || kvp[0].source, node_as_string(kvp[1]) || kvp[1].source) end end end end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/ruby/rsapi_handler.rb000066400000000000000000000111771331446220200271540ustar00rootroot00000000000000require 'puppet-strings/yard/handlers/helpers' require 'puppet-strings/yard/handlers/ruby/base' require 'puppet-strings/yard/code_objects' require 'puppet-strings/yard/util' # Implements the handler for Puppet resource types written in Ruby. class PuppetStrings::Yard::Handlers::Ruby::RsapiHandler < PuppetStrings::Yard::Handlers::Ruby::Base # The default docstring when ensurable is used without given a docstring. DEFAULT_ENSURABLE_DOCSTRING = 'The basic property that the resource should be in.'.freeze namespace_only handles method_call(:register_type) process do # Only accept calls to Puppet::ResourceApi return unless statement.count > 1 module_name = statement[0].source return unless [ 'Puppet::ResourceApi' ].include? module_name schema = extract_schema # puts "Schema: #{schema.inspect}" object = PuppetStrings::Yard::CodeObjects::Type.new(schema['name']) register object docstring = schema['docs'] if docstring register_docstring(object, PuppetStrings::Yard::Util.scrub_string(docstring.to_s), nil) else log.warn "Missing a description for Puppet resource type '#{object.name}' at #{statement.file}:#{statement.line}." end # Populate the parameters/properties/features to the type populate_type_data(object, schema) # Mark the type as public if it doesn't already have an api tag object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api # Warn if a summary longer than 140 characters was provided PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary end private def raise_parse_error(msg, location = statement) raise YARD::Parser::UndocumentableError, "#{msg} at #{location.file}:#{location.line}." end # check that the params of the register_type call are key/value pairs. def kv_arg_list?(params) params.type == :list && params.children.count > 0 && params.children.first.type == :list && params.children.first.children.count > 0 && statement.parameters.children.first.children.first.type == :assoc end def extract_schema raise_parse_error("Expected list of key/value pairs as argument") unless kv_arg_list?(statement.parameters) hash_from_node(statement.parameters.children.first) end def value_from_node(node) return nil unless node # puts "value from #{node.inspect}" case node.type when :int node.source.to_i when :hash hash_from_node(node) when :array array_from_node(node) when :var_ref var_ref_from_node(node) when :symbol, :symbol_literal, :label, :dyna_symbol, :string_literal node_as_string(node) else raise_parse_error("unexpected construct #{node.type}") end end def array_from_node(node) return nil unless node arr = node.children.collect do |assoc| value_from_node(assoc.children[0]) end end def hash_from_node(node) return nil unless node # puts "hash from #{node.inspect}" kv_pairs = node.children.collect do |assoc| [ value_from_node(assoc.children[0]), value_from_node(assoc.children[1]) ] end Hash[kv_pairs] end def var_ref_from_node(node) return nil unless node # puts "var_ref from #{node.inspect}" if node.children.first.type == :kw case node.children.first.source when "false" return false when "true" return true when "nil" return nil else raise_parse_error("unexpected keyword '#{node.children.first.source}'") end end raise_parse_error("unexpected variable") end def populate_type_data(object, schema) return if schema['attributes'].nil? schema['attributes'].each do |name, definition| # puts "Processing #{name}: #{definition.inspect}" if ['parameter', 'namevar'].include? definition['behaviour'] object.add_parameter(create_parameter(name, definition)) else object.add_property(create_property(name, definition)) end end end def create_parameter(name, definition) parameter = PuppetStrings::Yard::CodeObjects::Type::Parameter.new(name, definition['desc']) set_values(definition, parameter) parameter end def create_property(name, definition) property = PuppetStrings::Yard::CodeObjects::Type::Property.new(name, definition['desc']) set_values(definition, property) property end def set_values(definition, object) object.data_type = definition['type'] if definition.key? 'type' object.default = definition['default'] if definition.key? 'default' object.isnamevar = definition.key?('behaviour') && definition['behaviour'] == 'namevar' end end puppet-strings-2.1.0/lib/puppet-strings/yard/handlers/ruby/type_handler.rb000066400000000000000000000171661331446220200270230ustar00rootroot00000000000000require 'puppet-strings/yard/handlers/helpers' require 'puppet-strings/yard/handlers/ruby/base' require 'puppet-strings/yard/code_objects' require 'puppet-strings/yard/util' # Implements the handler for Puppet resource types written in Ruby. class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Handlers::Ruby::Base # The default docstring when ensurable is used without given a docstring. DEFAULT_ENSURABLE_DOCSTRING = 'The basic property that the resource should be in.'.freeze namespace_only handles method_call(:newtype) process do # Only accept calls to Puppet::Type return unless statement.count > 1 module_name = statement[0].source return unless module_name == 'Puppet::Type' || module_name == 'Type' object = PuppetStrings::Yard::CodeObjects::Type.new(get_name) register object docstring = find_docstring(statement, "Puppet resource type '#{object.name}'") register_docstring(object, docstring, nil) if docstring # Populate the parameters/properties/features to the type populate_type_data(object) # Set the default namevar set_default_namevar(object) # Mark the type as public if it doesn't already have an api tag object.add_tag YARD::Tags::Tag.new(:api, 'public') unless object.has_tag? :api # Warn if a summary longer than 140 characters was provided PuppetStrings::Yard::Handlers::Helpers.validate_summary_tag(object) if object.has_tag? :summary end private def get_name parameters = statement.parameters(false) raise YARD::Parser::UndocumentableError, "Expected at least one parameter to Puppet::Type.newtype at #{statement.file}:#{statement.line}." if parameters.empty? name = node_as_string(parameters.first) raise YARD::Parser::UndocumentableError, "Expected a symbol or string literal for first parameter but found '#{parameters.first.type}' at #{statement.file}:#{statement.line}." unless name name end def find_docstring(node, kind) # Walk the tree searching for assignments or calls to desc/doc= node.traverse do |child| if child.type == :assign ivar = child.jump(:ivar) next unless ivar != child && ivar.source == '@doc' docstring = node_as_string(child[1]) log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring return PuppetStrings::Yard::Util.scrub_string(docstring) elsif child.is_a?(YARD::Parser::Ruby::MethodCallNode) # Look for a call to a dispatch method with a block next unless child.method_name && (child.method_name.source == 'desc' || child.method_name.source == 'doc=') && child.parameters(false).count == 1 docstring = node_as_string(child.parameters[0]) log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring return PuppetStrings::Yard::Util.scrub_string(docstring) end end log.warn "Missing a description for #{kind} at #{node.file}:#{node.line}." nil end def populate_type_data(object) # Traverse the block looking for properties/parameters/features block = statement.block return unless block && block.count >= 2 block[1].children.each do |node| next unless node.is_a?(YARD::Parser::Ruby::MethodCallNode) && node.method_name method_name = node.method_name.source parameters = node.parameters(false) if method_name == 'newproperty' # Add a property to the object next unless parameters.count >= 1 name = node_as_string(parameters[0]) next unless name object.add_property(create_property(name, node)) elsif method_name == 'newparam' # Add a parameter to the object next unless parameters.count >= 1 name = node_as_string(parameters[0]) next unless name object.add_parameter(create_parameter(name, node)) elsif method_name == 'feature' # Add a feature to the object next unless parameters.count >= 2 name = node_as_string(parameters[0]) next unless name docstring = node_as_string(parameters[1]) next unless docstring object.add_feature(PuppetStrings::Yard::CodeObjects::Type::Feature.new(name, docstring)) elsif method_name == 'ensurable' if node.block property = create_property('ensure', node) property.docstring = DEFAULT_ENSURABLE_DOCSTRING if property.docstring.empty? else property = PuppetStrings::Yard::CodeObjects::Type::Property.new('ensure', DEFAULT_ENSURABLE_DOCSTRING) property.add('present') property.add('absent') property.default = 'present' end object.add_property property end end end def create_parameter(name, node) parameter = PuppetStrings::Yard::CodeObjects::Type::Parameter.new(name, find_docstring(node, "Puppet resource parameter '#{name}'")) set_values(node, parameter) parameter end def create_property(name, node) property = PuppetStrings::Yard::CodeObjects::Type::Property.new(name, find_docstring(node, "Puppet resource property '#{name}'")) set_values(node, property) property end def set_values(node, object) return unless node.block && node.block.count >= 2 node.block[1].children.each do |child| next unless child.is_a?(YARD::Parser::Ruby::MethodCallNode) && child.method_name method_name = child.method_name.source parameters = child.parameters(false) if method_name == 'newvalue' next unless parameters.count >= 1 object.add(node_as_string(parameters[0]) || parameters[0].source) elsif method_name == 'newvalues' parameters.each do |p| object.add(node_as_string(p) || p.source) end elsif method_name == 'aliasvalue' next unless parameters.count >= 2 object.alias(node_as_string(parameters[0]) || parameters[0].source, node_as_string(parameters[1]) || parameters[1].source) elsif method_name == 'defaultto' next unless parameters.count >= 1 object.default = node_as_string(parameters[0]) || parameters[0].source elsif method_name == 'isnamevar' object.isnamevar = true elsif method_name == 'defaultvalues' && object.name == 'ensure' object.add('present') object.add('absent') object.default = 'present' end end if object.is_a? PuppetStrings::Yard::CodeObjects::Type::Parameter # Process the options for parameter base types parameters = node.parameters(false) if parameters.count >= 2 parameters[1].each do |kvp| next unless kvp.count == 2 next unless node_as_string(kvp[0]) == 'parent' if kvp[1].source == 'Puppet::Parameter::Boolean' object.add('true') unless object.values.include? 'true' object.add('false') unless object.values.include? 'false' object.add('yes') unless object.values.include? 'yes' object.add('no') unless object.values.include? 'no' end break end end end end def set_default_namevar(object) return unless object.properties || object.parameters default = nil if object.properties object.properties.each do |property| return nil if property.isnamevar default = property if property.name == 'name' end end if object.parameters object.parameters.each do |parameter| return nil if parameter.isnamevar default ||= parameter if parameter.name == 'name' end end default.isnamevar = true if default end end puppet-strings-2.1.0/lib/puppet-strings/yard/parsers.rb000066400000000000000000000005271331446220200232340ustar00rootroot00000000000000# The module for custom YARD parsers. module PuppetStrings::Yard::Parsers # The module for custom YARD parsers for JSON. module JSON require 'puppet-strings/yard/parsers/json/parser' end # The module for custom YARD parsers for the Puppet language. module Puppet require 'puppet-strings/yard/parsers/puppet/parser' end end puppet-strings-2.1.0/lib/puppet-strings/yard/parsers/000077500000000000000000000000001331446220200227035ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/parsers/json/000077500000000000000000000000001331446220200236545ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/parsers/json/parser.rb000066400000000000000000000014341331446220200254770ustar00rootroot00000000000000require 'puppet-strings/yard/parsers/json/task_statement' class PuppetStrings::Yard::Parsers::JSON::Parser < YARD::Parser::Base attr_reader :file, :source # Initializes the parser. # @param [String] source The source being parsed. # @param [String] filename The file name of the file being parsed. # @return [void] def initialize(source, filename) @file = filename @source = source @statements = [] end def enumerator @statements end # Parses the source # @return [void] def parse begin json = JSON.parse(source) @statements.push(PuppetStrings::Yard::Parsers::JSON::TaskStatement.new(json, @source, @file)) rescue log.error "Failed to parse #{@file}: " @statements = [] end @statements.freeze self end end puppet-strings-2.1.0/lib/puppet-strings/yard/parsers/json/task_statement.rb000066400000000000000000000012371331446220200272320ustar00rootroot00000000000000module PuppetStrings::Yard::Parsers::JSON # Represents the Puppet Task statement. class TaskStatement 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 @docstring = YARD::Docstring.new(@json['description']) end def parameters json['parameters'] || {} end def comments_hash_flag false end def show "" end def comments docstring.all end def name File.basename(@file).gsub('.json','') || "" end end end puppet-strings-2.1.0/lib/puppet-strings/yard/parsers/puppet/000077500000000000000000000000001331446220200242205ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/parsers/puppet/parser.rb000066400000000000000000000046241331446220200260470ustar00rootroot00000000000000require 'puppet' require 'puppet/pops' require 'puppet-strings/yard/parsers/puppet/statement' # Implements the Puppet language parser. class PuppetStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base attr_reader :file, :source # Initializes the parser. # @param [String] source The source being parsed. # @param [String] filename The file name of the file being parsed. # @return [void] def initialize(source, filename) @source = source @file = filename @visitor = ::Puppet::Pops::Visitor.new(self, 'transform') end # Parses the source. # @return [void] def parse begin Puppet[:tasks] = true if Puppet.settings.include?(:tasks) if Puppet::Util::Package.versioncmp(Puppet.version, "5.0.0") < 0 && @file.to_s.match(/^plans\//) log.warn "Skipping #{@file}: Puppet Plans require Puppet 5 or greater." return end @statements ||= (@visitor.visit(::Puppet::Pops::Parser::Parser.new.parse_string(source)) || []).compact rescue ::Puppet::ParseError => ex log.error "Failed to parse #{@file}: #{ex.message}" @statements = [] end @statements.freeze self end # Gets an enumerator for the statements that were parsed. # @return Returns an enumerator for the statements that were parsed. def enumerator @statements end private def transform_Program(o) # Cache the lines of the source text; we'll use this to locate comments @lines = o.source_text.lines.to_a o.definitions.map { |d| @visitor.visit(d) } end def transform_Factory(o) @visitor.visit(o.current) end def transform_HostClassDefinition(o) statement = PuppetStrings::Yard::Parsers::Puppet::ClassStatement.new(o, @file) statement.extract_docstring(@lines) statement end def transform_ResourceTypeDefinition(o) statement = PuppetStrings::Yard::Parsers::Puppet::DefinedTypeStatement.new(o, @file) statement.extract_docstring(@lines) statement end def transform_FunctionDefinition(o) statement = PuppetStrings::Yard::Parsers::Puppet::FunctionStatement.new(o, @file) statement.extract_docstring(@lines) statement end def transform_PlanDefinition(o) statement = PuppetStrings::Yard::Parsers::Puppet::PlanStatement.new(o, @file) statement.extract_docstring(@lines) statement end def transform_Object(o) # Ignore anything else (will be compacted out of the resulting array) end end puppet-strings-2.1.0/lib/puppet-strings/yard/parsers/puppet/statement.rb000066400000000000000000000125501331446220200265540ustar00rootroot00000000000000require 'puppet' require 'puppet/pops' module PuppetStrings::Yard::Parsers::Puppet # Represents the base Puppet language statement. class Statement # The pattern for parsing docstring comments. COMMENT_REGEX = /^\s*#+\s?/ attr_reader :source attr_reader :file attr_reader :line attr_reader :docstring attr_reader :comments_range # Initializes the Puppet language statement. # @param object The Puppet parser model object for the statement. # @param [String] file The file name of the file containing the statement. def initialize(object, file) @file = file adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(object) @source = adapter.extract_text @line = adapter.line @comments_range = nil end # Extracts the docstring for the statement given the source lines. # @param [Array] lines The source lines for the file containing the statement. # @return [void] def extract_docstring(lines) comment = [] (0..@line-2).reverse_each do |index| break unless index <= lines.count line = lines[index].strip count = line.size line.gsub!(COMMENT_REGEX, '') # Break out if nothing was removed (wasn't a comment line) break unless line.size < count comment << line end @comments_range = (@line - comment.size - 1..@line - 1) @docstring = YARD::Docstring.new(comment.reverse.join("\n")) end # Shows the first line context for the statement. # @return [String] Returns the first line context for the statement. def show "\t#{@line}: #{first_line}" end # Gets the full comments of the statement. # @return [String] Returns the full comments of the statement. def comments @docstring.all end # Determines if the comments have hash flag. # @return [Boolean] Returns true if the comments have a hash flag or false if not. def comments_hash_flag false end private def first_line @source.split(/\r?\n/).first.strip end end # Implements a parameterized statement (a statement that takes parameters). class ParameterizedStatement < Statement # Implements a parameter for a parameterized statement. class Parameter attr_reader :name attr_reader :type attr_reader :value # Initializes the parameter. # @param [Puppet::Pops::Model::Parameter] parameter The parameter model object. def initialize(parameter) @name = parameter.name # Take the exact text for the type expression if parameter.type_expr adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(parameter.type_expr) @type = adapter.extract_text end # Take the exact text for the default value expression if parameter.value adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(parameter.value) @value = adapter.extract_text end end end attr_reader :parameters # Initializes the parameterized statement. # @param object The Puppet parser model object that has parameters. # @param [String] file The file containing the statement. def initialize(object, file) super(object, file) @parameters = object.parameters.map { |parameter| Parameter.new(parameter) } end end # Implements the Puppet class statement. class ClassStatement < ParameterizedStatement attr_reader :name attr_reader :parent_class # Initializes the Puppet class statement. # @param [Puppet::Pops::Model::HostClassDefinition] object The model object for the class statement. # @param [String] file The file containing the statement. def initialize(object, file) super(object, file) @name = object.name @parent_class = object.parent_class end end # Implements the Puppet defined type statement. class DefinedTypeStatement < ParameterizedStatement attr_reader :name # Initializes the Puppet defined type statement. # @param [Puppet::Pops::Model::ResourceTypeDefinition] object The model object for the defined type statement. # @param [String] file The file containing the statement. def initialize(object, file) super(object, file) @name = object.name end end # Implements the Puppet function statement. class FunctionStatement < ParameterizedStatement attr_reader :name attr_reader :type # Initializes the Puppet function statement. # @param [Puppet::Pops::Model::FunctionDefinition] object The model object for the function statement. # @param [String] file The file containing the statement. def initialize(object, file) super(object, file) @name = object.name if object.respond_to? :return_type type = object.return_type if type adapter = ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(type) @type = adapter.extract_text.gsub('>> ', '') end end end end # Implements the Puppet plan statement. class PlanStatement < ParameterizedStatement attr_reader :name # Initializes the Puppet plan statement. # @param [Puppet::Pops::Model::PlanDefinition] object The model object for the plan statement. # @param [String] file The file containing the statement. def initialize(object, file) super(object, file) @name = object.name end end end puppet-strings-2.1.0/lib/puppet-strings/yard/tags.rb000066400000000000000000000004341331446220200225100ustar00rootroot00000000000000# The module for custom YARD tags. module PuppetStrings::Yard::Tags require 'puppet-strings/yard/tags/parameter_directive' require 'puppet-strings/yard/tags/property_directive' require 'puppet-strings/yard/tags/overload_tag' require 'puppet-strings/yard/tags/summary_tag' end puppet-strings-2.1.0/lib/puppet-strings/yard/tags/000077500000000000000000000000001331446220200221625ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/tags/overload_tag.rb000066400000000000000000000076201331446220200251620ustar00rootroot00000000000000# Implements an overload tag for Puppet functions # # This differs from Yard's overload tag in that the signatures are formatted according to Puppet language rules. class PuppetStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag attr_reader :parameters, :docstring # Initializes the overload tag. # @param [String, Symbol] name The name of the function being overloaded. # @param [String] docstring The docstring for the overload. # @return [void] def initialize(name, docstring) super(:overload, nil) @name = name.to_s @parameters = [] @docstring = YARD::Docstring.new(docstring) end # Gets the signature of the overload. # @return [String] Returns the signature of the overload. def signature tags = self.tags(:param) args = @parameters.map do |parameter| name, default = parameter tag = tags.find { |t| t.name == name } if tags type = tag && tag.types ? "#{tag.type} " : 'Any ' prefix = "#{name[0]}" if name.start_with?('*', '&') name = name[1..-1] if prefix default = " = #{default}" if default "#{type}#{prefix}$#{name}#{default}" end.join(', ') @name + '(' + args + ')' end # Adds a tag to the overload's docstring. # @param [YARD::Tag] tag The tag to add to the overload's docstring. # @return [void] def add_tag(tag) @docstring.add_tag(tag) end # Gets the first tag of the given name. # @param [String, Symbol] name The name of the tag. # @return [YARD::Tag] Returns the first tag if found or nil if not found. def tag(name) @docstring.tag(name) end # Gets all tags or tags of a given name. # @param [String, Symbol] name The name of the tag to get or nil for all tags. # @return [Array] Returns an array of tags. def tags(name = nil) @docstring.tags(name) end # Determines if a tag with the given name is present. # @param [String, Symbol] name The tag name. # @return [Boolean] Returns true if there is at least one tag with the given name or false if not. def has_tag?(name) @docstring.has_tag?(name) end # Sets the object associated with this tag. # @param [Object] value The object to associate with this tag. # @return [void] def object=(value) super(value) @docstring.object = value @docstring.tags.each {|tag| tag.object = value } end # Responsible for forwarding method calls to the associated object. # @param [Symbol] method_name The method being invoked. # @param [Array] args The args passed to the method. # @param block The block passed to the method. # @return Returns what the method call on the object would return. def method_missing(method_name, *args, &block) return object.send(method_name, *args, &block) if object.respond_to? method_name super end # Determines if the associated object responds to the give missing method name. # @param [Symbol, String] method_name The name of the method to check. # @param [Boolean] include_all True to include all methods in the check or false for only public methods. # @return [Boolean] Returns true if the object responds to the method or false if not. def respond_to_missing?(method_name, include_all = false) object.respond_to?(method_name, include_all) || super end # Gets the type of the object associated with this tag. # @return [Symbol] Returns the type of the object associated with this tag. def type object.type end # Converts the overload tag to a hash representation. # @return [Hash] Returns a hash representation of the overload. def to_hash hash = {} hash[:tag_name] = tag_name hash[:text] = text if text hash[:signature] = signature hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring) if !docstring.blank? defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten] hash[:defaults] = defaults unless defaults.empty? hash[:types] = types if types hash[:name] = name if name hash end end puppet-strings-2.1.0/lib/puppet-strings/yard/tags/parameter_directive.rb000066400000000000000000000014341331446220200265270ustar00rootroot00000000000000require 'puppet-strings/yard/code_objects' # Implements a parameter directive (e.g. #@!puppet.type.param) for documenting Puppet resource types. class PuppetStrings::Yard::Tags::ParameterDirective < YARD::Tags::Directive # Called to invoke the directive. # @return [void] def call return unless object && object.respond_to?(:add_parameter) # Add a parameter to the resource parameter = PuppetStrings::Yard::CodeObjects::Type::Parameter.new(tag.name, tag.text) if tag.types tag.types.each do |value| parameter.add(value) end end object.add_parameter parameter end # Registers the directive with YARD. # @return [void] def self.register! YARD::Tags::Library.define_directive('puppet.type.param', :with_types_and_name, self) end end puppet-strings-2.1.0/lib/puppet-strings/yard/tags/property_directive.rb000066400000000000000000000014321331446220200264310ustar00rootroot00000000000000require 'puppet-strings/yard/code_objects' # Implements a parameter directive (e.g. #@!puppet.type.property) for documenting Puppet resource types. class PuppetStrings::Yard::Tags::PropertyDirective < YARD::Tags::Directive # Called to invoke the directive. # @return [void] def call return unless object && object.respond_to?(:add_property) # Add a property to the resource property = PuppetStrings::Yard::CodeObjects::Type::Property.new(tag.name, tag.text) if tag.types tag.types.each do |value| property.add(value) end end object.add_property property end # Registers the directive with YARD. # @return [void] def self.register! YARD::Tags::Library.define_directive('puppet.type.property', :with_types_and_name, self) end end puppet-strings-2.1.0/lib/puppet-strings/yard/tags/summary_tag.rb000066400000000000000000000004231331446220200250360ustar00rootroot00000000000000# Implements a summary tag for general purpose short descriptions class PuppetStrings::Yard::Tags::SummaryTag < YARD::Tags::Tag # Registers the tag with YARD. # @return [void] def self.register! YARD::Tags::Library.define_tag("puppet.summary", :summary) end end puppet-strings-2.1.0/lib/puppet-strings/yard/templates/000077500000000000000000000000001331446220200232225ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/000077500000000000000000000000001331446220200246465ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/000077500000000000000000000000001331446220200262765ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/html/000077500000000000000000000000001331446220200272425ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/html/css/000077500000000000000000000000001331446220200300325ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/html/css/common.css000066400000000000000000000002061331446220200320320ustar00rootroot00000000000000/* Ensure the search bar doesn't overlap with links */ .fixed_header { padding-bottom: 25px; } #full_list { padding-top: 15px; } full_list_puppet_class.erb000066400000000000000000000003721331446220200344360ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/html<% even = false %> <% @items.each do |item| %>
  • <%= linkify item, h(item.name(true)) %>
    • <% even = !even %> <% end %> full_list_puppet_defined_type.erb000066400000000000000000000003721331446220200357700ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/html<% even = false %> <% @items.each do |item| %>
  • <%= linkify item, h(item.name(true)) %>
    • <% even = !even %> <% end %> full_list_puppet_function.erb000066400000000000000000000004541331446220200351570ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/html<% even = false %> <% @items.each do |item| %>
  • <%= linkify item, h(item.name(false)) %> <%= item.function_type %>
    • <% even = !even %> <% end %> full_list_puppet_plan.erb000066400000000000000000000003721331446220200342630ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/html<% even = false %> <% @items.each do |item| %>
  • <%= linkify item, h(item.name(true)) %>
    • <% even = !even %> <% end %> full_list_puppet_provider.erb000066400000000000000000000004751331446220200351670ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/html<% even = false %> <% @items.each do |item| %>
  • <%= linkify item, h(item.name(true)) %> Resource type: <%=item.type_name%>
    • <% even = !even %> <% end %> full_list_puppet_task.erb000066400000000000000000000003721331446220200342730ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/html<% even = false %> <% @items.each do |item| %>
  • <%= linkify item, h(item.name(true)) %>
    • <% even = !even %> <% end %> full_list_puppet_type.erb000066400000000000000000000003721331446220200343120ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/html<% even = false %> <% @items.each do |item| %>
  • <%= linkify item, h(item.name(true)) %>
    • <% even = !even %> <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/fulldoc/html/setup.rb000066400000000000000000000045701331446220200307350ustar00rootroot00000000000000# Generates the searchable Puppet class list. # @return [void] def generate_puppet_class_list @items = Registry.all(:puppet_class).sort_by { |c| c.name.to_s } @list_title = 'Puppet Class List' @list_type = 'puppet_class' generate_list_contents end # Generates the searchable Puppet defined type list. # @return [void] def generate_puppet_defined_type_list @items = Registry.all(:puppet_defined_type).sort_by {|dt| dt.name.to_s } @list_title = 'Defined Type List' @list_type = 'puppet_defined_type' generate_list_contents end # Generates the searchable Puppet resource type list. # @return [void] def generate_puppet_type_list @items = Registry.all(:puppet_type).sort_by {|t| t.name.to_s } @list_title = 'Resource Type List' @list_type = 'puppet_type' generate_list_contents end # Generates the searchable Puppet provider list. # @return [void] def generate_puppet_provider_list @items = Registry.all(:puppet_provider).sort_by {|p| p.name.to_s } @list_title = 'Provider List' @list_type = 'puppet_provider' generate_list_contents end # Generates the searchable Puppet function list. # @return [void] def generate_puppet_function_list @items = Registry.all(:puppet_function).sort_by {|f| f.name.to_s } @list_title = 'Puppet Function List' @list_type = 'puppet_function' generate_list_contents end # Generates the searchable Ruby method list. # @return [void] def generate_method_list @items = prune_method_listing(Registry.all(:method), false) @items = @items.reject {|m| m.name.to_s =~ /=$/ && m.is_attribute? } @items = @items.sort_by {|m| m.name.to_s } @list_title = 'Ruby Method List' @list_type = 'method' generate_list_contents end # Generate a searchable Ruby class list in the output. # @return [void] def generate_class_list @items = options.objects if options.objects @list_title = 'Ruby Class List' @list_type = 'class' generate_list_contents end # Generates the searchable Puppet Task list. # @return [void] def generate_puppet_task_list @items = Registry.all(:puppet_task).sort_by {|t| t.name.to_s } @list_title = 'Puppet Task List' @list_type = 'puppet_task' generate_list_contents end # Generates the searchable Puppet Plan list. # @return [void] def generate_puppet_plan_list @items = Registry.all(:puppet_plan).sort_by {|t| t.name.to_s } @list_title = 'Puppet Plan List' @list_type = 'puppet_plan' generate_list_contents end puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/layout/000077500000000000000000000000001331446220200261635ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/layout/html/000077500000000000000000000000001331446220200271275ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/layout/html/footer.erb000066400000000000000000000002111331446220200311110ustar00rootroot00000000000000 puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/layout/html/objects.erb000066400000000000000000000017251331446220200312570ustar00rootroot00000000000000<% unless @objects_by_letter.empty? %>

    <%= @title %>

    <% i = 0 %>
    <% @objects_by_letter.sort_by {|l,o| l.to_s }.each do |letter, objects| %> <% if (i += 1) % 8 == 0 %> <% i = 0 %> <% end %>
    • <%= letter %>
        • <% objects.each do |obj| %>
      • <%= linkify obj, obj.name %> <% if (obj.type == :module || obj.type == :class) && !obj.namespace.root? %> (<%= obj.namespace.path %>) <% elsif obj.type == :puppet_provider %> (Resource type: <%= obj.type_name %>) <% elsif obj.type == :puppet_function %> (<%= obj.function_type %>) <% end %>
        • <% end %>
    <% end %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/layout/html/setup.rb000066400000000000000000000132251331446220200306170ustar00rootroot00000000000000# Initializes the template. # @return [void] def init case object when '_index.html' @page_title = options.title sections :layout, [:index, [:listing, [:classes, :defined_types, :types, :providers, :functions, :tasks, :plans, :files, :objects]]] else super end end # Renders the layout section. # @return [String] Returns the rendered section. def layout @nav_url = url_for_list(!@file || options.index ? menu_lists.first[:type] : 'file') case object when nil, String @path = nil when @file @path = @file.path when !object.is_a?(YARD::CodeObjects::NamespaceObject) @path = object.parent.path @nav_url = url_for_list('class') when YARD::CodeObjects::ClassObject @path = object.path @nav_url = url_for_list('class') when PuppetStrings::Yard::CodeObjects::Class @nav_url = url_for_list('puppet_class') @page_title = "Puppet Class: #{object.name}" @path = object.path when PuppetStrings::Yard::CodeObjects::DefinedType @nav_url = url_for_list('puppet_defined_type') @page_title = "Defined Type: #{object.name}" @path = object.path when PuppetStrings::Yard::CodeObjects::Type @nav_url = url_for_list('puppet_type') @page_title = "Resource Type: #{object.name}" @path = object.path when PuppetStrings::Yard::CodeObjects::Provider @nav_url = url_for_list('puppet_provider') @page_title = "Provider: #{object.name}" @path = object.path when PuppetStrings::Yard::CodeObjects::Function @nav_url = url_for_list('puppet_function') @page_title = "Puppet Function: #{object.name} (#{object.function_type})" @path = object.path when PuppetStrings::Yard::CodeObjects::Task @nav_url = url_for_list('puppet_task') @page_title = "Puppet Task: #{object.name}" @path = object.path when PuppetStrings::Yard::CodeObjects::Plan @nav_url = url_for_list('puppet_plan') @page_title = "Puppet Plan: #{object.name}" @path = object.path else @path = object.path end final_layout = erb(:layout) if @file && @file.name == 'README' PuppetStrings::Yard::Util.github_to_yard_links(final_layout) end final_layout end # Creates the dynamic menu lists. # @return [Array] Returns the dynamic menu list. def create_menu_lists menu_lists = [ { type: 'puppet_class', title: 'Puppet Classes', search_title: 'Puppet Classes' }, { type: 'puppet_defined_type', title: 'Defined Types', search_title: 'Defined Types', }, { type: 'puppet_type', title: 'Resource Types', search_title: 'Resource Types' }, { type: 'puppet_provider', title: 'Providers', search_title: 'Providers' }, { type: 'puppet_function', title: 'Puppet Functions', search_title: 'Puppet Functions' }, { type: 'puppet_task', title: 'Puppet Tasks', search_totle: 'Puppet Tasks' }, { type: 'puppet_plan', title: 'Puppet Plans', search_totle: 'Puppet Plans' }, { type: 'class', title: 'Ruby Classes', search_title: 'Class List' }, { type: 'method', title: 'Ruby Methods', search_title: 'Method List' }, ] menu_lists.delete_if { |e| YARD::Registry.all(e[:type].intern).empty? } # We must always return at least one group, so always keep the files list menu_lists << { type: 'file', title: 'Files', search_title: 'File List' } if menu_lists.empty? || !YARD::Registry.all(:file).empty? menu_lists end # Gets the menu lists to use. # @return [Array <% if object.statement.parent_class %>
    Inherits:
    <%= linkify(Registry["puppet_classes::#{object.statement.parent_class}"], object.statement.parent_class.dup) %>
    <% end %> <% if @subclasses && !@subclasses.empty? %>
    Inherited by:
    <% @subclasses.each do |subclass| %> <%= linkify(subclass, subclass.name.to_s) %>
    <% end %>
    <% end %>
    Defined in:
    <%= object.file %><% if object.files.size > 1 %>,
    <%= object.files[1..-1].map {|f| f.first }.join(",
    ") %> <% end %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_class/html/header.erb000066400000000000000000000000521331446220200322330ustar00rootroot00000000000000

    Puppet Class: <%= object.name %>

    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_class/html/note.erb000077500000000000000000000002231331446220200317530ustar00rootroot00000000000000<% object.tags(:note).each do |tag| %>
    Note: <%= htmlify_line tag.text %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_class/html/overview.erb000066400000000000000000000001721331446220200326540ustar00rootroot00000000000000

    Overview

    <%= htmlify(object.docstring) %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_class/html/setup.rb000066400000000000000000000005631331446220200320050ustar00rootroot00000000000000# Initializes the template. # @return [void] def init sections :header, :box_info, :summary, :overview, :note, :todo, T('tags'), :source end # Renders the box_info section. # @return [String] Returns the rendered section. def box_info @subclasses = Registry.all(:puppet_class).find_all { |c| c.statement.parent_class == object.name.to_s } erb(:box_info) end puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_class/html/source.erb000066400000000000000000000006531331446220200323120ustar00rootroot00000000000000
    <%= "\n\n\n" %><%= h format_lines(object) %>
    		 
    # File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %><%= "\n\n" %><%= html_syntax_highlight object.source %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_class/html/summary.erb000066400000000000000000000001671331446220200325070ustar00rootroot00000000000000<% if object.docstring.has_tag?(:summary) %>

    Summary

    <%= object.docstring.tag(:summary).text %> <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_class/html/todo.erb000077500000000000000000000002201331446220200317500ustar00rootroot00000000000000<% object.tags(:todo).each do |tag| %>
    TODO: <%= htmlify_line tag.text %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_defined_type/000077500000000000000000000000001331446220200307025ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/000077500000000000000000000000001331446220200316465ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/box_info.erb000066400000000000000000000004101331446220200341360ustar00rootroot00000000000000
    Defined in:
    <%= object.file %><% if object.files.size > 1 %>,
    <%= object.files[1..-1].map {|f| f.first }.join(",
    ") %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/header.erb000066400000000000000000000000521331446220200335650ustar00rootroot00000000000000

    Defined Type: <%= object.name %>

    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/note.erb000077500000000000000000000002231331446220200333050ustar00rootroot00000000000000<% object.tags(:note).each do |tag| %>
    Note: <%= htmlify_line tag.text %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/overview.erb000066400000000000000000000001721331446220200342060ustar00rootroot00000000000000

    Overview

    <%= htmlify(object.docstring) %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/setup.rb000066400000000000000000000002171331446220200333330ustar00rootroot00000000000000# Initializes the template. # @return [void] def init sections :header, :box_info, :summary, :overview, :note, :todo, T('tags'), :source end puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/source.erb000066400000000000000000000006531331446220200336440ustar00rootroot00000000000000
    <%= "\n\n\n" %><%= h format_lines(object) %>
    		 
    # File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %><%= "\n\n" %><%= html_syntax_highlight object.source %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/summary.erb000066400000000000000000000001671331446220200340410ustar00rootroot00000000000000<% if object.docstring.has_tag?(:summary) %>

    Summary

    <%= object.docstring.tag(:summary).text %> <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_defined_type/html/todo.erb000077500000000000000000000002201331446220200333020ustar00rootroot00000000000000<% object.tags(:todo).each do |tag| %>
    TODO: <%= htmlify_line tag.text %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_function/000077500000000000000000000000001331446220200300705ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_function/html/000077500000000000000000000000001331446220200310345ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_function/html/box_info.erb000066400000000000000000000005341331446220200333330ustar00rootroot00000000000000
    Defined in:
    <%= object.file %><% if object.files.size > 1 %>,
    <%= object.files[1..-1].map {|f| f.first }.join(",
    ") %>
    <% end %>
    Function type:
    <%= object.function_type %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_function/html/header.erb000066400000000000000000000000551331446220200327560ustar00rootroot00000000000000

    Puppet Function: <%= object.name %>

    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_function/html/note.erb000077500000000000000000000002231331446220200324730ustar00rootroot00000000000000<% object.tags(:note).each do |tag| %>
    Note: <%= htmlify_line tag.text %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_function/html/overview.erb000066400000000000000000000010461331446220200333750ustar00rootroot00000000000000

    Overview

    <% unless object.has_tag? :overload %>
    <%= "#{h(object.signature)} ⇒ #{signature_types(object, false)}" %>
    <% end %>
    <%= htmlify(object.docstring) %>
    <%= yieldall %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_function/html/setup.rb000066400000000000000000000002211331446220200325140ustar00rootroot00000000000000# Initializes the template. # @return [void] def init sections :header, :box_info, :summary, :overview, :note, :todo, [T('tags'), :source] end puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_function/html/source.erb000066400000000000000000000006531331446220200330320ustar00rootroot00000000000000
    <%= "\n\n\n" %><%= h format_lines(object) %>
    		 
    # File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %><%= "\n\n" %><%= html_syntax_highlight object.source %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_function/html/summary.erb000066400000000000000000000001671331446220200332270ustar00rootroot00000000000000<% if object.docstring.has_tag?(:summary) %>

    Summary

    <%= object.docstring.tag(:summary).text %> <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_function/html/todo.erb000077500000000000000000000002201331446220200324700ustar00rootroot00000000000000<% object.tags(:todo).each do |tag| %>
    TODO: <%= htmlify_line tag.text %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_plan/000077500000000000000000000000001331446220200271755ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_plan/html/000077500000000000000000000000001331446220200301415ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_plan/html/box_info.erb000066400000000000000000000004101331446220200324310ustar00rootroot00000000000000
    Defined in:
    <%= object.file %><% if object.files.size > 1 %>,
    <%= object.files[1..-1].map {|f| f.first }.join(",
    ") %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_plan/html/header.erb000066400000000000000000000000511331446220200320570ustar00rootroot00000000000000

    Puppet Plan: <%= object.name %>

    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_plan/html/note.erb000077500000000000000000000002231331446220200316000ustar00rootroot00000000000000<% object.tags(:note).each do |tag| %>
    Note: <%= htmlify_line tag.text %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_plan/html/overview.erb000066400000000000000000000001721331446220200325010ustar00rootroot00000000000000

    Overview

    <%= htmlify(object.docstring) %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_plan/html/setup.rb000066400000000000000000000004031331446220200316230ustar00rootroot00000000000000# Initializes the template. # @return [void] def init sections :header, :box_info, :summary, :overview, :note, :todo, T('tags'), :source end # Renders the box_info section. # @return [String] Returns the rendered section. def box_info erb(:box_info) end puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_plan/html/source.erb000066400000000000000000000006531331446220200321370ustar00rootroot00000000000000
    <%= "\n\n\n" %><%= h format_lines(object) %>
    		 
    # File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %><%= "\n\n" %><%= html_syntax_highlight object.source %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_plan/html/summary.erb000066400000000000000000000001671331446220200323340ustar00rootroot00000000000000<% if object.docstring.has_tag?(:summary) %>

    Summary

    <%= object.docstring.tag(:summary).text %> <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_plan/html/todo.erb000077500000000000000000000002201331446220200315750ustar00rootroot00000000000000<% object.tags(:todo).each do |tag| %>
    TODO: <%= htmlify_line tag.text %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_provider/000077500000000000000000000000001331446220200300755ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_provider/html/000077500000000000000000000000001331446220200310415ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_provider/html/box_info.erb000066400000000000000000000006201331446220200333340ustar00rootroot00000000000000
    Defined in:
    <%= object.file %><% if object.files.size > 1 %>,
    <%= object.files[1..-1].map {|f| f.first }.join(",
    ") %>
    <% end %>
    Resource type:
    <%= linkify(Registry["puppet_types::#{object.type_name}"], object.type_name) %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_provider/html/collection.erb000066400000000000000000000007221331446220200336670ustar00rootroot00000000000000<% if @collection && !@collection.empty? %>

    <%= @title %>

      <% if @collection.is_a?(Hash) %> <% @collection.each do |key, value| %>
    • <%= key %> — <%= value %>
      • <% end %> <% elsif @collection.is_a?(Array) %> <% @collection.each do |kvps| %>
    • <%= kvps.map{|k,v| "#{k} — #{v}"}.join(', ') %>
      • <% end %> <% end %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_provider/html/features.erb000066400000000000000000000004071331446220200333520ustar00rootroot00000000000000<% if object.features && !object.features.empty? %>

    Features

      <% object.features.each do |feature| %>
    • <%= feature %>
      • <% end %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_provider/html/header.erb000066400000000000000000000000461331446220200327630ustar00rootroot00000000000000

    Provider: <%= object.name %>

    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_provider/html/overview.erb000066400000000000000000000001721331446220200334010ustar00rootroot00000000000000

    Overview

    <%= htmlify(object.docstring) %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_provider/html/setup.rb000066400000000000000000000012641331446220200325310ustar00rootroot00000000000000# Initializes the template. # @return [void] def init sections :header, :box_info, :summary, :overview, T('tags'), :features, :confines, :defaults, :commands end # Renders the confines section. # @return [String] Returns the rendered section. def confines @title = 'Confines' @collection = object.confines erb(:collection) end # Renders the defaults section. # @return [String] Returns the rendered section. def defaults @title = 'Default Provider For' @collection = object.defaults erb(:collection) end # Renders the commands section. # @return [String] Returns the rendered section. def commands @title = 'Commands' @collection = object.commands erb(:collection) end puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_provider/html/summary.erb000066400000000000000000000001671331446220200332340ustar00rootroot00000000000000<% if object.docstring.has_tag?(:summary) %>

    Summary

    <%= object.docstring.tag(:summary).text %> <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_task/000077500000000000000000000000001331446220200272055ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_task/html/000077500000000000000000000000001331446220200301515ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_task/html/box_info.erb000066400000000000000000000002571331446220200324520ustar00rootroot00000000000000
    Defined in:
    <%= object.file %>,
    <%= object.file.gsub('json','rb') %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_task/html/header.erb000066400000000000000000000000511331446220200320670ustar00rootroot00000000000000

    Puppet Task: <%= object.name %>

    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_task/html/input.erb000066400000000000000000000002661331446220200320060ustar00rootroot00000000000000<% if json['input_method'] || json['supports_noop'] %>

    Supports noop? <%= json['supports_noop'] ? "true" : "false" %>

    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_task/html/overview.erb000066400000000000000000000001541331446220200325110ustar00rootroot00000000000000

    Overview

    <%= description %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_task/html/parameters.erb000066400000000000000000000007001331446220200330030ustar00rootroot00000000000000<% if @parameters && !@parameters.empty? %>

    <%= @tag_title %>

      <% @parameters.each do |parameter, values| %>
    • <%= parameter %> (<%= values['type'] %>) <% if values['description'] %> — <%= values['description'] %><% end %>
      • <% end %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_task/html/setup.rb000066400000000000000000000006541331446220200316430ustar00rootroot00000000000000# Initializes the template. # @return [void] def init sections :header, :box_info, T('tags'), :overview, :input, :parameters end def json object.statement.json end def description json['description'] end # Renders the parameters section. # @return [String] Returns the rendered section. def parameters @parameters = json['parameters'] || [] @parameters.to_a.sort! @tag_title = 'Parameters' erb(:parameters) end puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_task/html/supports_noop.erb000066400000000000000000000001461331446220200335760ustar00rootroot00000000000000<% if json['supports_noop'] %> Supports noop? <%= json['supports_noop'] %> <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_type/000077500000000000000000000000001331446220200272245ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_type/html/000077500000000000000000000000001331446220200301705ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_type/html/box_info.erb000066400000000000000000000007561331446220200324750ustar00rootroot00000000000000
    Defined in:
    <%= object.file %><% if object.files.size > 1 %>,
    <%= object.files[1..-1].map {|f| f.first }.join(",
    ") %>
    <% end %> <% if @providers && !@providers.empty? %>
    Providers:
    <% @providers.each do |provider| %> <%= linkify(provider, provider.name.to_s) %>
    <% end %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_type/html/features.erb000066400000000000000000000005601331446220200325010ustar00rootroot00000000000000<% if object.features && !object.features.empty? %>

    Features

      <% object.features.each do |feature| %>
    • <%= feature.name %> <% unless feature.docstring.empty? %> — <%= htmlify_line(feature.docstring) %><% end %>
      • <% end %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_type/html/header.erb000066400000000000000000000000531331446220200321100ustar00rootroot00000000000000

    Resource Type: <%= object.name %>

    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_type/html/note.erb000077500000000000000000000002231331446220200316270ustar00rootroot00000000000000<% object.tags(:note).each do |tag| %>
    Note: <%= htmlify_line tag.text %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_type/html/overview.erb000066400000000000000000000001721331446220200325300ustar00rootroot00000000000000

    Overview

    <%= htmlify(object.docstring) %>
    puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_type/html/parameters.erb000066400000000000000000000017711331446220200330330ustar00rootroot00000000000000<% if @parameters && !@parameters.empty? %>

    <%= @tag_title %>

      <% @parameters.each do |parameter| %>
    • <%= parameter.name + (parameter.isnamevar ? ' (namevar)' : '') %> <% if parameter.default %> (defaults to: <%= parameter.default %>) <% end %> <% unless parameter.docstring.empty? %>
      <%= htmlify(parameter.docstring) %>
      <% end %> <% unless parameter.values.empty? %>
      Supported values:
        <% parameter.values.each do |value| %>
      • <% other = parameter.aliases[value] %> <%= value %><% if other %> (alias for: <%= other %>)<% end %>
        • <% end %>
      <% end %>
      • <% end %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb000066400000000000000000000017411331446220200316600ustar00rootroot00000000000000# Initializes the template. # @return [void] def init sections :header, :box_info, :summary, :overview, :note, :todo, T('tags'), :properties, :parameters, :features end # Renders the box_info section. # @return [String] Returns the rendered section. def box_info @providers = PuppetStrings::Yard::CodeObjects::Providers.instance(object.name).children erb(:box_info) end # Renders the properties section. # @return [String] Returns the rendered section. def properties # Properties are the same thing as parameters (from the documentation standpoint), # so reuse the same template but with a different title and data source. @parameters = object.properties || [] @parameters.sort_by! { |p| p.name } @tag_title = 'Properties' erb(:parameters) end # Renders the parameters section. # @return [String] Returns the rendered section. def parameters @parameters = object.parameters || [] @parameters.sort_by! { |p| p.name } @tag_title = 'Parameters' erb(:parameters) end puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_type/html/summary.erb000066400000000000000000000001671331446220200323630ustar00rootroot00000000000000<% if object.docstring.has_tag?(:summary) %>

    Summary

    <%= object.docstring.tag(:summary).text %> <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/puppet_type/html/todo.erb000077500000000000000000000002201331446220200316240ustar00rootroot00000000000000<% object.tags(:todo).each do |tag| %>
    TODO: <%= htmlify_line tag.text %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/tags/000077500000000000000000000000001331446220200256045ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/tags/html/000077500000000000000000000000001331446220200265505ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb000066400000000000000000000010211331446220200324440ustar00rootroot00000000000000<% if object.has_tag?(:overload) && object.tags(:overload).any? {|o| !o.docstring.blank? } %>

    Signatures:

      <% object.tags(:overload).each_with_index do |overload, index| %> <% next if overload.docstring.blank? %>
    • <%= "#{h(overload.signature)} ⇒ #{signature_types(overload, false)}" %> <%= yieldall :object => overload %>
      • <% end %>
    <% end %> puppet-strings-2.1.0/lib/puppet-strings/yard/templates/default/tags/setup.rb000066400000000000000000000010551331446220200272720ustar00rootroot00000000000000# Called to return parameter tags. # @return [Array] Returns the parameter tags if the object should have parameters. def param tag(:param) if object.type == :method || object.type == :puppet_class || object.type == :puppet_defined_type || object.type == :puppet_function || object.type == :puppet_task || object.type == :puppet_plan end # Renders the overload section. # @return [String] Returns the rendered section. def overload erb(if object.type == :puppet_function then :puppet_overload else :overload end) end puppet-strings-2.1.0/lib/puppet-strings/yard/util.rb000066400000000000000000000023611331446220200225300ustar00rootroot00000000000000require 'puppet/util' # The module for various puppet-strings utility helpers. module PuppetStrings::Yard::Util # Trims indentation from trailing whitespace and removes ruby literal quotation # syntax `%Q{}` and `%{q}` from parsed strings. # @param [String] str The string to scrub. # @return [String] A scrubbed string. def self.scrub_string(str) match = str.match(/^%[Qq]{(.*)}$/m) if match return Puppet::Util::Docs.scrub(match[1]) end Puppet::Util::Docs.scrub(str) end # hacksville, usa # YARD creates ids in the html with with the style of "label-Module+description", where the markdown # we use in the README involves the GitHub-style, which is #module-description. This takes our GitHub-style # links and converts them to reference the YARD-style ids. # @see https://github.com/octokit/octokit.rb/blob/0f13944e8dbb0210d1e266addd3335c6dc9fe36a/yard/default/layout/html/setup.rb#L5-L14 # @param [String] data HTML document to convert # @return [String] HTML document with links converted def self.github_to_yard_links(data) data.scan(/href\=\"\#(.+)\"/).each do |bad_link| data.gsub!("=\"##{bad_link.first}\"", "=\"#label-#{bad_link.first.capitalize.gsub('-', '+')}\"") end data end end puppet-strings-2.1.0/lib/puppet/000077500000000000000000000000001331446220200165765ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet/application/000077500000000000000000000000001331446220200211015ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet/application/strings.rb000066400000000000000000000002361331446220200231200ustar00rootroot00000000000000require 'puppet/application/face_base' # Implements the 'puppet strings' application. class Puppet::Application::Strings < Puppet::Application::FaceBase end puppet-strings-2.1.0/lib/puppet/face/000077500000000000000000000000001331446220200174745ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet/face/strings.rb000066400000000000000000000112261331446220200215140ustar00rootroot00000000000000require 'puppet/face' # Implements the 'puppet strings' interface. Puppet::Face.define(:strings, '0.0.1') do summary 'Generate Puppet documentation with YARD.' action(:generate) do default option '--format OUTPUT_FORMAT' do summary 'Designate output format, JSON or markdown.' end option '--out PATH' do summary 'Write selected format to PATH. If no path is designated, strings prints to STDOUT.' end option '--markup FORMAT' do summary "The markup format to use for docstring text (defaults to 'markdown')." end option '--emit-json-stdout' do summary 'DEPRECATED: Print JSON representation of the documentation to stdout.' end option '--emit-json PATH' do summary 'DEPRECATED: Write JSON representation of the documentation to the given file.' end summary 'Generate documentation from files.' arguments '[[search_pattern] ...]' when_invoked do |*args| check_required_features require 'puppet-strings' PuppetStrings::generate( args.count > 1 ? args[0..-2] : PuppetStrings::DEFAULT_SEARCH_PATTERNS, build_generate_options(args.last) ) nil end end action(:server) do option '--markup FORMAT' do summary "The markup format to use for docstring text (defaults to 'markdown')." end summary 'Runs a local documentation server for the modules in the current Puppet environment.' arguments '[[module_name] ...]' when_invoked do |*args| check_required_features require 'puppet-strings' modules = args.count > 1 ? args[0..-2] : [] # Generate documentation for all (or the given) modules module_docs = [] environment = Puppet.lookup(:current_environment) environment.modules.each do |mod| next unless modules.empty? || modules.include?(mod.name) db = File.join(mod.path, '.yardoc') patterns = PuppetStrings::DEFAULT_SEARCH_PATTERNS.map do |p| File.join(mod.path, p) end puts "Generating documentation for Puppet module '#{mod.name}'." PuppetStrings.generate(patterns, build_generate_options(args.last, '--db', db)) # Clear the registry so that the next call to generate has a clean database YARD::Registry.clear module_docs << mod.name module_docs << db end if module_docs.empty? puts 'No Puppet modules were found to serve documentation for.' return end puts 'Starting YARD documentation server.' PuppetStrings::run_server('-m', *module_docs) nil end end # Checks that the required features are installed. # @return [void] def check_required_features raise RuntimeError, "The 'yard' gem must be installed in order to use this face." unless Puppet.features.yard? raise RuntimeError, "The 'rgen' gem must be installed in order to use this face." unless Puppet.features.rgen? raise RuntimeError, 'This face requires Ruby 1.9 or greater.' if RUBY_VERSION =~ /^1\.8/ end # Builds the options to PuppetStrings.generate. # @param [Hash] options The Puppet face options hash. # @param [Array] yard_args The additional arguments to pass to YARD. # @return [Hash] Returns the PuppetStrings.generate options hash. def build_generate_options(options = nil, *yard_args) generate_options = {} generate_options[:debug] = Puppet[:debug] generate_options[:backtrace] = Puppet[:trace] generate_options[:yard_args] = yard_args unless yard_args.empty? if options if options[:emit_json] $stderr.puts "WARNING: '--emit-json PATH' is deprecated. Use '--format json --out PATH' instead." end if options[:emit_json_stdout] $stderr.puts "WARNING: '--emit-json-stdout' is deprecated. Use '--format json' instead." end markup = options[:markup] generate_options[:markup] = markup if markup generate_options[:path] = options[:out] if options[:out] generate_options[:stdout] = options[:stdout] format = options[:format] if format if format.casecmp('markdown').zero? generate_options[:markdown] = true elsif format.casecmp('json').zero? || options[:emit_json] || options[:emit_json_stdout] generate_options[:json] = true generate_options[:path] ||= options[:emit_json] if options[:emit_json] else raise RuntimeError, "Invalid format #{options[:format]}. Please select 'json' or 'markdown'." end elsif options[:emit_json] || options[:emit_json_stdout] generate_options[:json] = true generate_options[:path] ||= options[:emit_json] if options[:emit_json] end end generate_options end end puppet-strings-2.1.0/lib/puppet/feature/000077500000000000000000000000001331446220200202315ustar00rootroot00000000000000puppet-strings-2.1.0/lib/puppet/feature/rgen.rb000066400000000000000000000001631331446220200215110ustar00rootroot00000000000000require 'puppet/util/feature' Puppet.features.add(:rgen, :libs => ['rgen/metamodel_builder', 'rgen/ecore/ecore']) puppet-strings-2.1.0/lib/puppet/feature/yard.rb000066400000000000000000000001151331446220200215120ustar00rootroot00000000000000require 'puppet/util/feature' Puppet.features.add(:yard, :libs => ['yard']) puppet-strings-2.1.0/misc/000077500000000000000000000000001331446220200154465ustar00rootroot00000000000000puppet-strings-2.1.0/misc/ANNOUNCEMENT_TEMPLATE.md000066400000000000000000000034641331446220200211640ustar00rootroot00000000000000Send out announcements for major new feature releases, and high-impact bugfixes to , , , , and the puppet internal mailing lists and . Before sending, do check that all links are still valid. Feel free to adjust the text to match better with the circumstances of the release, or add other news that are relevant at the time. If you make changes, consider committing them here, for the benefit of future-you. The github rendering of the markdown seems to copy&paste acceptably into Google Inbox. The [CHANGELOG](https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md) is a good starting point for finding enhancements and bug-fixes. --- Subject: [ANN] Puppet Strings vX.Y.Z Release Hi all, We're pleased to announce that version X.Y.Z of the Puppet Strings is being released today. Puppet Strings provides a simple way to extract source documentation into useful docs. It is provided as a Ruby gem to be referenced within modules. See the [README](https://github.com/puppetlabs/puppet-strings#installing-puppet-strings) for documentation on how to install and use it. The new release of Puppet Strings provides the following enhancements: * A * B * C The new release also contains the following notable bugfixes: * D * E * F See the [CHANGELOG](https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md) for a full list of changes We encourage all module developers to review puppet-strings and use it when creating modules. Please let us know of your experiences with Puppet Strings, either here, on [Slack](https://slack.puppet.com/) (#forge-modules), or on the [github repo](https://github.com/puppetlabs/puppet-strings). Thanks, YOUR NAME puppet-strings-2.1.0/puppet-strings.gemspec000066400000000000000000000014411331446220200210640ustar00rootroot00000000000000lib = File.expand_path('../lib', __FILE__) $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) require 'puppet-strings/version' Gem::Specification.new do |s| s.name = 'puppet-strings' s.author = 'Puppet Inc.' s.version = PuppetStrings::VERSION s.license = 'Apache-2.0' s.summary = 'Puppet documentation via YARD' s.email = 'info@puppet.com' s.homepage = 'https://github.com/puppetlabs/puppet-strings' s.description = s.summary s.required_ruby_version = '>= 2.1.0' s.extra_rdoc_files = [ 'CHANGELOG.md', 'COMMITTERS.md', 'CONTRIBUTING.md', 'LICENSE', 'README.md', ] s.files = `git ls-files`.split("\n") - Dir['.*', '*.gemspec'] s.add_runtime_dependency 'yard', '~> 0.9.5' s.add_runtime_dependency 'rgen' s.requirements << 'puppet, >= 4.0.0' end puppet-strings-2.1.0/spec/000077500000000000000000000000001331446220200154455ustar00rootroot00000000000000puppet-strings-2.1.0/spec/acceptance/000077500000000000000000000000001331446220200175335ustar00rootroot00000000000000puppet-strings-2.1.0/spec/acceptance/emit_json_options.rb000066400000000000000000000052521331446220200236260ustar00rootroot00000000000000require 'spec_helper_acceptance' require 'util' require 'json' include PuppetStrings::Acceptance::Util describe 'Emitting JSON' do expected = { "puppet_classes" => [], "defined_types" => [], "resource_types" => [], "providers" => [], "puppet_functions" => [ "name" => "function3x", "file" => "/etc/puppet/modules/test/lib/puppet/parser/functions/function3x.rb", "line" => 1, "type" => "ruby3x", "signatures" => [ { "signature" =>"function3x()", "docstring" => { "text" => "This is the function documentation for `function3x`", "tags" => [ { "tag_name"=>"return", "text"=>"", "types"=>["Any"] } ] } }, ], "docstring" => { "text" => "This is the function documentation for `function3x`", "tags" => ["tag_name" => "return", "text" => "", "types" => ["Any"]]}, "source" => "Puppet::Parser::Functions.newfunction(:function3x, :doc => \"This is the function documentation for `function3x`\") do |args|\nend" ] } it 'should emit JSON to stdout when using --format json and --stdout' do test_module_path = get_test_module_path(master, /Module test/) on master, puppet('strings', 'generate', '--format json', "#{test_module_path}/lib/puppet/parser/functions/function3x.rb") do output = stdout.chomp expect(JSON.parse(output)).to eq(expected) end end it 'should write JSON to a file when using --format json and --out' do test_module_path = get_test_module_path(master, /Module test/) tmpfile = master.tmpfile('json_output.json') on master, puppet('strings', 'generate', '--format json', "--out #{tmpfile}", "#{test_module_path}/lib/puppet/parser/functions/function3x.rb") output = read_file_on(master, tmpfile) expect(JSON.parse(output)).to eq(expected) end it 'should emit JSON to stdout when using --emit-json-stdout' do test_module_path = get_test_module_path(master, /Module test/) on master, puppet('strings', 'generate', '--emit-json-stdout', "#{test_module_path}/lib/puppet/parser/functions/function3x.rb") do output = stdout.chomp expect(JSON.parse(output)).to eq(expected) end end it 'should write JSON to a file when using --emit-json' do test_module_path = get_test_module_path(master, /Module test/) tmpfile = master.tmpfile('json_output.json') on master, puppet('strings', 'generate', '--emit-json', tmpfile, "#{test_module_path}/lib/puppet/parser/functions/function3x.rb") output = read_file_on(master, tmpfile) expect(JSON.parse(output)).to eq(expected) end end puppet-strings-2.1.0/spec/acceptance/generate_markdown_spec.rb000066400000000000000000000023121331446220200245640ustar00rootroot00000000000000require 'spec_helper_acceptance' require 'util' include PuppetStrings::Acceptance::Util describe 'Generating Markdown' do expected = <<-EOF # Reference ## Classes * [`test`](#test): This class exists to serve as fixture data for testing the puppet strings face ## Classes ### test #### Examples ```puppet class { "test": } ``` #### Parameters ##### `package_name` The name of the package ##### `service_name` The name of the service EOF it 'should render Markdown to stdout when using --format markdown and --stdout' do test_module_path = get_test_module_path(master, /Module test/) on master, puppet('strings', 'generate', '--format markdown', "#{test_module_path}/manifests/init.pp") do output = stdout.chomp expect(JSON.parse(output)).to eq(expected) end end it 'should write Markdown to a file when using --format markdown and --out' do test_module_path = get_test_module_path(master, /Module test/) tmpfile = master.tmpfile('md_output.md') on master, puppet('strings', 'generate', '--format markdown', "--out #{tmpfile}", "#{test_module_path}/manifests/init.pp") output = read_file_on(master, tmpfile) expect(JSON.parse(output)).to eq(expected) end end puppet-strings-2.1.0/spec/acceptance/lib/000077500000000000000000000000001331446220200203015ustar00rootroot00000000000000puppet-strings-2.1.0/spec/acceptance/lib/util.rb000066400000000000000000000172141331446220200216100ustar00rootroot00000000000000module PuppetStrings module Acceptance module Util GEOTRUST_GLOBAL_CA = <<-EOM -----BEGIN CERTIFICATE----- MIIDVDCCAjygAwIBAgIDAjRWMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMRswGQYDVQQDExJHZW9UcnVzdCBHbG9i YWwgQ0EwHhcNMDIwNTIxMDQwMDAwWhcNMjIwNTIxMDQwMDAwWjBCMQswCQYDVQQG EwJVUzEWMBQGA1UEChMNR2VvVHJ1c3QgSW5jLjEbMBkGA1UEAxMSR2VvVHJ1c3Qg R2xvYmFsIENBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2swYYzD9 9BcjGlZ+W988bDjkcbd4kdS8odhM+KhDtgPpTSEHCIjaWC9mOSm9BXiLnTjoBbdq fnGk5sRgprDvgOSJKA+eJdbtg/OtppHHmMlCGDUUna2YRpIuT8rxh0PBFpVXLVDv iS2Aelet8u5fa9IAjbkU+BQVNdnARqN7csiRv8lVK83Qlz6cJmTM386DGXHKTubU 1XupGc1V3sjs0l44U+VcT4wt/lAjNvxm5suOpDkZALeVAjmRCw7+OC7RHQWa9k0+ bw8HHa8sHo9gOeL6NlMTOdReJivbPagUvTLrGAMoUgRx5aszPeE4uwc2hGKceeoW MPRfwCvocWvk+QIDAQABo1MwUTAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBTA ephojYn7qwVkDBF9qn1luMrMTjAfBgNVHSMEGDAWgBTAephojYn7qwVkDBF9qn1l uMrMTjANBgkqhkiG9w0BAQUFAAOCAQEANeMpauUvXVSOKVCUn5kaFOSPeCpilKIn Z57QzxpeR+nBsqTP3UEaBU6bS+5Kb1VSsyShNwrrZHYqLizz/Tt1kL/6cdjHPTfS tQWVYrmm3ok9Nns4d0iXrKYgjy6myQzCsplFAMfOEVEiIuCl6rYVSAlk6l5PdPcF PseKUgzbFbS9bZvlxrFUaKnjaZC2mqUPuLk/IH2uSrW4nOQdtqvmlKXBx4Ot2/Un hw4EbNX/3aBd7YdStysVAq45pmp06drE57xNNB6pXE0zX5IJL4hmXXeXxx12E6nV 5fEWCRE11azbJHFwLJhWC9kXtNHjUStedejV0NxPNO3CBWaAocvmMw== -----END CERTIFICATE----- EOM USERTRUST_NETWORK_CA = <<-EOM -----BEGIN CERTIFICATE----- MIIEdDCCA1ygAwIBAgIQRL4Mi1AAJLQR0zYq/mUK/TANBgkqhkiG9w0BAQUFADCB lzELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAlVUMRcwFQYDVQQHEw5TYWx0IExha2Ug Q2l0eTEeMBwGA1UEChMVVGhlIFVTRVJUUlVTVCBOZXR3b3JrMSEwHwYDVQQLExho dHRwOi8vd3d3LnVzZXJ0cnVzdC5jb20xHzAdBgNVBAMTFlVUTi1VU0VSRmlyc3Qt SGFyZHdhcmUwHhcNOTkwNzA5MTgxMDQyWhcNMTkwNzA5MTgxOTIyWjCBlzELMAkG A1UEBhMCVVMxCzAJBgNVBAgTAlVUMRcwFQYDVQQHEw5TYWx0IExha2UgQ2l0eTEe MBwGA1UEChMVVGhlIFVTRVJUUlVTVCBOZXR3b3JrMSEwHwYDVQQLExhodHRwOi8v d3d3LnVzZXJ0cnVzdC5jb20xHzAdBgNVBAMTFlVUTi1VU0VSRmlyc3QtSGFyZHdh cmUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCx98M4P7Sof885glFn 0G2f0v9Y8+efK+wNiVSZuTiZFvfgIXlIwrthdBKWHTxqctU8EGc6Oe0rE81m65UJ M6Rsl7HoxuzBdXmcRl6Nq9Bq/bkqVRcQVLMZ8Jr28bFdtqdt++BxF2uiiPsA3/4a MXcMmgF6sTLjKwEHOG7DpV4jvEWbe1DByTCP2+UretNb+zNAHqDVmBe8i4fDidNd oI6yqqr2jmmIBsX6iSHzCJ1pLgkzmykNRg+MzEk0sGlRvfkGzWitZky8PqxhvQqI DsjfPe58BEydCl5rkdbux+0ojatNh4lz0G6k0B4WixThdkQDf2Os5M1JnMWS9Ksy oUhbAgMBAAGjgbkwgbYwCwYDVR0PBAQDAgHGMA8GA1UdEwEB/wQFMAMBAf8wHQYD VR0OBBYEFKFyXyYbKJhDlV0HN9WFlp1L0sNFMEQGA1UdHwQ9MDswOaA3oDWGM2h0 dHA6Ly9jcmwudXNlcnRydXN0LmNvbS9VVE4tVVNFUkZpcnN0LUhhcmR3YXJlLmNy bDAxBgNVHSUEKjAoBggrBgEFBQcDAQYIKwYBBQUHAwUGCCsGAQUFBwMGBggrBgEF BQcDBzANBgkqhkiG9w0BAQUFAAOCAQEARxkP3nTGmZev/K0oXnWO6y1n7k57K9cM //bey1WiCuFMVGWTYGufEpytXoMs61quwOQt9ABjHbjAbPLPSbtNk28Gpgoiskli CE7/yMgUsogWXecB5BKV5UU0s4tpvc+0hY91UZ59Ojg6FEgSxvunOxqNDYJAB+gE CJChicsZUN/KHAG8HQQZexB2lzvukJDKxA4fFm517zP4029bHpbj4HR3dHuKom4t 3XbWOTCC8KucUvIqx69JXn7HaOWCgchqJ/kniCrVWFCVH/A7HFe7fRQ5YiuayZSS KqMiDP+JJn1fIytH1xUdqWqeUQ0qUZ6B+dQ7XnASfxAynB67nfhmqA== -----END CERTIFICATE----- EOM EQUIFAX_CA = <<-EOM -----BEGIN CERTIFICATE----- MIIDIDCCAomgAwIBAgIENd70zzANBgkqhkiG9w0BAQUFADBOMQswCQYDVQQGEwJV UzEQMA4GA1UEChMHRXF1aWZheDEtMCsGA1UECxMkRXF1aWZheCBTZWN1cmUgQ2Vy dGlmaWNhdGUgQXV0aG9yaXR5MB4XDTk4MDgyMjE2NDE1MVoXDTE4MDgyMjE2NDE1 MVowTjELMAkGA1UEBhMCVVMxEDAOBgNVBAoTB0VxdWlmYXgxLTArBgNVBAsTJEVx dWlmYXggU2VjdXJlIENlcnRpZmljYXRlIEF1dGhvcml0eTCBnzANBgkqhkiG9w0B AQEFAAOBjQAwgYkCgYEAwV2xWGcIYu6gmi0fCG2RFGiYCh7+2gRvE4RiIcPRfM6f BeC4AfBONOziipUEZKzxa1NfBbPLZ4C/QgKO/t0BCezhABRP/PvwDN1Dulsr4R+A cJkVV5MW8Q+XarfCaCMczE1ZMKxRHjuvK9buY0V7xdlfUNLjUA86iOe/FP3gx7kC AwEAAaOCAQkwggEFMHAGA1UdHwRpMGcwZaBjoGGkXzBdMQswCQYDVQQGEwJVUzEQ MA4GA1UEChMHRXF1aWZheDEtMCsGA1UECxMkRXF1aWZheCBTZWN1cmUgQ2VydGlm aWNhdGUgQXV0aG9yaXR5MQ0wCwYDVQQDEwRDUkwxMBoGA1UdEAQTMBGBDzIwMTgw ODIyMTY0MTUxWjALBgNVHQ8EBAMCAQYwHwYDVR0jBBgwFoAUSOZo+SvSspXXR9gj IBBPM5iQn9QwHQYDVR0OBBYEFEjmaPkr0rKV10fYIyAQTzOYkJ/UMAwGA1UdEwQF MAMBAf8wGgYJKoZIhvZ9B0EABA0wCxsFVjMuMGMDAgbAMA0GCSqGSIb3DQEBBQUA A4GBAFjOKer89961zgK5F7WF0bnj4JXMJTENAKaSbn+2kmOeUJXRmm/kEd5jhW6Y 7qj/WsjTVbJmcVfewCHrPSqnI0kBBIZCe/zuf6IWUrVnZ9NA2zsmWLIodz2uFHdh 1voqZiegDfqnc1zqcPGUIWVEX/r87yloqaKHee9570+sB3c4 -----END CERTIFICATE----- EOM GLOBALSIGN_CA = <<-EOM -----BEGIN CERTIFICATE----- MIIDdTCCAl2gAwIBAgILBAAAAAABFUtaw5QwDQYJKoZIhvcNAQEFBQAwVzELMAkG A1UEBhMCQkUxGTAXBgNVBAoTEEdsb2JhbFNpZ24gbnYtc2ExEDAOBgNVBAsTB1Jv b3QgQ0ExGzAZBgNVBAMTEkdsb2JhbFNpZ24gUm9vdCBDQTAeFw05ODA5MDExMjAw MDBaFw0yODAxMjgxMjAwMDBaMFcxCzAJBgNVBAYTAkJFMRkwFwYDVQQKExBHbG9i YWxTaWduIG52LXNhMRAwDgYDVQQLEwdSb290IENBMRswGQYDVQQDExJHbG9iYWxT aWduIFJvb3QgQ0EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDaDuaZ jc6j40+Kfvvxi4Mla+pIH/EqsLmVEQS98GPR4mdmzxzdzxtIK+6NiY6arymAZavp xy0Sy6scTHAHoT0KMM0VjU/43dSMUBUc71DuxC73/OlS8pF94G3VNTCOXkNz8kHp 1Wrjsok6Vjk4bwY8iGlbKk3Fp1S4bInMm/k8yuX9ifUSPJJ4ltbcdG6TRGHRjcdG snUOhugZitVtbNV4FpWi6cgKOOvyJBNPc1STE4U6G7weNLWLBYy5d4ux2x8gkasJ U26Qzns3dLlwR5EiUWMWea6xrkEmCMgZK9FGqkjWZCrXgzT/LCrBbBlDSgeF59N8 9iFo7+ryUp9/k5DPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8E BTADAQH/MB0GA1UdDgQWBBRge2YaRQ2XyolQL30EzTSo//z9SzANBgkqhkiG9w0B AQUFAAOCAQEA1nPnfE920I2/7LqivjTFKDK1fPxsnCwrvQmeU79rXqoRSLblCKOz yj1hTdNGCbM+w6DjY1Ub8rrvrTnhQ7k4o+YviiY776BQVvnGCv04zcQLcFGUl5gE 38NflNUVyRRBnMRddWQVDf9VMOyGj/8N7yy5Y0b2qvzfvGn9LhJIZJrglfCm7ymP AbEVtQwdpf5pLGkkeB6zpxxxYu7KyJesF12KwvhHhm4qxFYxldBniYUr+WymXUad DKqC5JlR3XC321Y9YeRq4VzW9v493kHMB65jUr9TU/Qr6cf9tveCX4XSQRjbgbME HMUfpIBvFSDJ3gyICh3WZlXi/EjJKSZp4A== -----END CERTIFICATE----- EOM def read_file_on(host, filename) on(host, "cat #{filename}").stdout end def get_test_module_path(host, module_regex) modules = JSON.parse(on(host, puppet('module', 'list', '--render-as', 'json')).stdout) test_module_info = modules['modules_by_path'].values.flatten.find { |mod_info| mod_info =~ module_regex } test_module_info.match(/\(([^)]*)\)/)[1] end def install_ca_certs(host) return unless host.platform =~ /windows/ step "Installing Geotrust CA cert" create_remote_file(host, "geotrustglobal.pem", GEOTRUST_GLOBAL_CA) on host, "chmod 644 geotrustglobal.pem" on host, "cmd /c certutil -v -addstore Root `cygpath -w geotrustglobal.pem`" step "Installing Usertrust Network CA cert" create_remote_file(host, "usertrust-network.pem", USERTRUST_NETWORK_CA) on host, "chmod 644 usertrust-network.pem" on host, "cmd /c certutil -v -addstore Root `cygpath -w usertrust-network.pem`" step "Installing Equifax CA cert" create_remote_file(host, "equifax.pem", EQUIFAX_CA) on host, "chmod 644 equifax.pem" on host, "cmd /c certutil -v -addstore Root `cygpath -w equifax.pem`" step "Installing Globalsign CA cert" create_remote_file(host, "globalsign.pem", GLOBALSIGN_CA) on host, "chmod 644 globalsign.pem" on host, "cmd /c certutil -v -addstore Root `cygpath -w globalsign.pem`" on host, "cp globalsign.pem \"$(cygpath \"#{find_windows_rubygems_ssl_certs_dir(host)}\")\"" end def find_windows_rubygems_ssl_certs_dir(host) return unless host.platform =~ /windows/ ssl_certs_dir = File.dirname(on(host, "#{gem_command(host)} which rubygems").stdout.strip) << '/rubygems/ssl_certs' end end module CommandUtils def ruby_command(host) "env PATH=\"#{host['privatebindir']}:${PATH}\" ruby" end module_function :ruby_command def gem_command(host, type='aio') if type == 'aio' if host['platform'] =~ /windows/ "PATH=\"#{host['privatebindir']}:${PATH}\" cmd /c gem" else "PATH=\"#{host['privatebindir']}:${PATH}\" gem" end else on(host, 'which gem').stdout.chomp end end module_function :gem_command end end end puppet-strings-2.1.0/spec/acceptance/running_strings_generate.rb000066400000000000000000000050671331446220200251730ustar00rootroot00000000000000require 'spec_helper_acceptance' require 'util' require 'json' include PuppetStrings::Acceptance::Util describe 'Generating module documentation using generate action' do before :all do test_module_path = get_test_module_path(master, /Module test/) on master, puppet('strings', 'generate', "#{test_module_path}/**/*.{rb,pp}") end it 'should generate documentation for manifests' do expect(read_file_on(master, '/root/doc/puppet_classes/test.html')).to include('Class: test') end it 'should generate documentation for puppet functions' do puppet_version = on(master, facter('puppetversion')).stdout.chomp.to_i if puppet_version >= 4 html_output = read_file_on(master, '/root/doc/puppet_functions_puppet/test_3A_3Aadd.html') expect(html_output).to include('Adds two integers together.') expect(html_output).to include('
    test::add(1, 2) => 3
    ') expect(html_output).to include('

    The first integer to add.

    ') expect(html_output).to include('

    The second integer to add.

    ') expect(html_output).to include('

    Returns the sum of x and y.

    ') end end it 'should generate documentation for 3x functions' do expect(read_file_on(master, '/root/doc/puppet_functions_ruby3x/function3x.html')).to include('This is the function documentation for function3x') end it 'should generate documentation for 4x functions' do expect(read_file_on(master, '/root/doc/puppet_functions_ruby4x/function4x.html')).to include('This is a function which is used to test puppet strings') end it 'should generate documentation for custom types' do html_output = read_file_on(master, '/root/doc/puppet_types/database.html') expect(html_output).to include('

    An example server resource type.

    ') expect(html_output).to include('

    The database file to use.

    ') expect(html_output).to include('

    Documentation for a dynamic property.

    ') expect(html_output).to include('

    The database server name.

    ') expect(html_output).to include('

    Documentation for a dynamic parameter.

    ') expect(html_output).to include('

    The provider supports encryption.

    ') end it 'should generate documentation for custom providers' do html_output = read_file_on(master, '/root/doc/puppet_providers_database/linux.html') expect(html_output).to include('The database provider on Linux') expect(html_output).to include('osfamily — linux') expect(html_output).to include('database — /usr/bin/database') end end puppet-strings-2.1.0/spec/fixtures/000077500000000000000000000000001331446220200173165ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/000077500000000000000000000000001331446220200214045ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/000077500000000000000000000000001331446220200230545ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/000077500000000000000000000000001331446220200240335ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/functions/000077500000000000000000000000001331446220200260435ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/functions/add.pp000066400000000000000000000004261331446220200271360ustar00rootroot00000000000000# Adds two integers together. # @param x The first integer to add. # @param y The second integer to add. # @return [Integer] Returns the sum of x and y. # @example Example of adding two integers. # test::add(1, 2) => 3 function test::add(Integer $x, Integer $y) { $x + $y } puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/000077500000000000000000000000001331446220200246015ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/puppet/000077500000000000000000000000001331446220200261165ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/puppet/functions/000077500000000000000000000000001331446220200301265ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/puppet/functions/4x_function.rb000066400000000000000000000002001331446220200327030ustar00rootroot00000000000000# function 4x # # This is a function which is used to test puppet strings Puppet::Functions.create_function(:function4x) do end puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/puppet/parser/000077500000000000000000000000001331446220200274125ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/puppet/parser/functions/000077500000000000000000000000001331446220200314225ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/puppet/parser/functions/function3x.rb000066400000000000000000000002001331446220200340370ustar00rootroot00000000000000Puppet::Parser::Functions.newfunction(:function3x, :doc => "This is the function documentation for `function3x`") do |args| end puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/puppet/provider/000077500000000000000000000000001331446220200277505ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/puppet/provider/server/000077500000000000000000000000001331446220200312565ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/puppet/provider/server/linux.rb000066400000000000000000000003251331446220200327420ustar00rootroot00000000000000Puppet::Type.type(:database).provide :linux do confine 'osfamily' => 'linux' defaultfor 'osfamily' => 'linux' commands :database => '/usr/bin/database' desc 'The database provider on Linux.' # ... end puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/puppet/type/000077500000000000000000000000001331446220200270775ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/lib/puppet/type/database.rb000066400000000000000000000007551331446220200311770ustar00rootroot00000000000000# @!puppet.type.param [value1, value2, value3] my_param Documentation for a dynamic parameter. # @!puppet.type.property [foo, bar, baz] my_prop Documentation for a dynamic property. Puppet::Type.newtype(:database) do desc 'An example server resource type.' feature :encryption, 'The provider supports encryption.', methods: [:encrypt] newparam(:address) do isnamevar desc 'The database server name.' end newproperty(:file) do desc 'The database file to use.' end end puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/manifests/000077500000000000000000000000001331446220200260245ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/manifests/init.pp000066400000000000000000000010731331446220200273310ustar00rootroot00000000000000# Class: test # # This class exists to serve as fixture data for testing the puppet strings face # # @example # class { "test": } # # @param package_name The name of the package # @param service_name The name of the service class test ( $package_name = $test::params::package_name, $service_name = $test::params::service_name, ) inherits test::params { # validate parameters here class { 'test::install': } -> class { 'test::config': } ~> class { 'test::service': } -> Class['test'] File { owner => 'user', path => 'some/file/path', } } puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/manifests/triple_nested_classes.pp000066400000000000000000000012411331446220200327410ustar00rootroot00000000000000# Testing tested classes # docs stuff # @param nameservers [String] Don't ask me what this does! # @param default_lease_time [Integer[1024, 8192]] text goes here # @param max_lease_time does stuff class outer ( $dnsdomain, $nameservers, $default_lease_time = 3600, $max_lease_time = 86400 ) { # @param options [String[5,7]] gives user choices # @param multicast [Boolean] foobar # @param servers yep, that's right class middle ( $options = "iburst", $servers, $multicast = false ) { class inner ( $choices = "uburst", $secenekler = "weallburst", $boxen, $manyspell = true ) {} } } puppet-strings-2.1.0/spec/fixtures/acceptance/modules/test/metadata.json000066400000000000000000000001471331446220200265100ustar00rootroot00000000000000{ "name": "username-test", "version": "0.0.1", "author": "username", "license": "Apache 2.0" } puppet-strings-2.1.0/spec/fixtures/unit/000077500000000000000000000000001331446220200202755ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/unit/json/000077500000000000000000000000001331446220200212465ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/unit/json/output.json000066400000000000000000000433201331446220200235030ustar00rootroot00000000000000{ "puppet_classes": [ { "name": "klass", "file": "(stdin)", "line": 7, "inherits": "foo::bar", "docstring": { "text": "A simple class.", "tags": [ { "tag_name": "todo", "text": "Do a thing" }, { "tag_name": "note", "text": "Some note" }, { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" } ] }, "defaults": { "param3": "hi" }, "source": "class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {\n}" } ], "defined_types": [ { "name": "dt", "file": "(stdin)", "line": 14, "docstring": { "text": "A simple defined type.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" } ] }, "defaults": { "param3": "hi" }, "source": "define dt(Integer $param1, $param2, String $param3 = hi) {\n}" } ], "resource_types": [ { "name": "apt_key", "file": "(stdin)", "line": 92, "docstring": { "text": "This type provides Puppet with the capabilities to manage GPG keys needed\nby apt to perform package validation. Apt has it's own GPG keyring that can\nbe manipulated through the `apt-key` command.\n**Autorequires**:\nIf Puppet is given the location of a key file which looks like an absolute\npath this type will autorequire that file.", "tags": [ { "tag_name": "summary", "text": "Example resource type using the new API." }, { "tag_name": "raise", "text": "SomeError" }, { "tag_name": "example", "text": "apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':\n source => 'http://apt.puppetlabs.com/pubkey.gpg'\n}", "name": "here's an example" } ] }, "properties": [ { "name": "ensure", "description": "Whether this apt key should be present or absent on the target system.", "data_type": "Enum[present, absent]" }, { "name": "created", "description": "Date the key was created, in ISO format.", "data_type": "String" } ], "parameters": [ { "name": "id", "description": "The ID of the key you want to manage.", "data_type": "Variant[Pattern[/A(0x)?[0-9a-fA-F]{8}Z/], Pattern[/A(0x)?[0-9a-fA-F]{16}Z/], Pattern[/A(0x)?[0-9a-fA-F]{40}Z/]]", "isnamevar": true } ] }, { "name": "database", "file": "(stdin)", "line": 54, "docstring": { "text": "An example database server resource type." }, "properties": [ { "name": "ensure", "description": "What state the database should be in.", "values": [ "present", "absent", "up", "down" ], "aliases": { "up": "present", "down": "absent" }, "default": "up" }, { "name": "file", "description": "The database file to use." }, { "name": "log_level", "description": "The log level to use.", "values": [ "debug", "warn", "error" ], "default": "warn" } ], "parameters": [ { "name": "address", "description": "The database server name.", "isnamevar": true }, { "name": "encryption_key", "description": "The encryption key to use." }, { "name": "encrypt", "description": "Whether or not to encrypt the database.", "values": [ "true", "false", "yes", "no" ], "default": "false" } ], "features": [ { "name": "encryption", "description": "The provider supports encryption." } ] } ], "providers": [ { "name": "linux", "type_name": "database", "file": "(stdin)", "line": 43, "docstring": { "text": "An example provider on Linux." }, "confines": { "kernel": "Linux", "osfamily": "RedHat" }, "features": [ "implements_some_feature", "some_other_feature" ], "defaults": [ [ [ "kernel", "Linux" ] ], [ [ "osfamily", "RedHat" ], [ "operatingsystemmajrelease", "7" ] ] ], "commands": { "foo": "/usr/bin/foo" } } ], "puppet_functions": [ { "name": "func", "file": "(stdin)", "line": 6, "type": "puppet", "signatures": [ { "signature": "func(Integer $param1, Any $param2, String $param3 = hi)", "docstring": { "text": "A simple function.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } } ], "docstring": { "text": "A simple function.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "defaults": { "param3": "hi" }, "source": "function func(Integer $param1, $param2, String $param3 = hi) {\n}" }, { "name": "func3x", "file": "(stdin)", "line": 1, "type": "ruby3x", "signatures": [ { "signature": "func3x(String $first, Any $second)", "docstring": { "text": "An example 3.x function.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "String" ], "name": "first" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "second" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } } ], "docstring": { "text": "An example 3.x function.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "String" ], "name": "first" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "second" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "source": "Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC\nAn example 3.x function.\n@param [String] first The first parameter.\n@param second The second parameter.\n@return [Undef] Returns nothing.\nDOC\n) do |*args|\nend" }, { "name": "func4x", "file": "(stdin)", "line": 11, "type": "ruby4x", "signatures": [ { "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)", "docstring": { "text": "The first overload.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "The third parameter.", "types": [ "Optional[Array[String]]" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } }, { "signature": "func4x(Boolean $param, Callable &$block)", "docstring": { "text": "", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Boolean" ], "name": "param" }, { "tag_name": "param", "text": "The block parameter.", "types": [ "Callable" ], "name": "&block" }, { "tag_name": "return", "text": "Returns a string.", "types": [ "String" ] } ] } } ], "docstring": { "text": "An example 4.x function.", "tags": [ { "tag_name": "overload", "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)", "docstring": { "text": "The first overload.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "The third parameter.", "types": [ "Optional[Array[String]]" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "name": "func4x" }, { "tag_name": "overload", "signature": "func4x(Boolean $param, Callable &$block)", "docstring": { "text": "", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Boolean" ], "name": "param" }, { "tag_name": "param", "text": "The block parameter.", "types": [ "Callable" ], "name": "&block" }, { "tag_name": "return", "text": "Returns a string.", "types": [ "String" ] } ] }, "name": "func4x" } ] }, "source": "Puppet::Functions.create_function(:func4x) do\n # The first overload.\n # @param param1 The first parameter.\n # @param param2 The second parameter.\n # @param param3 The third parameter.\n # @return Returns nothing.\n dispatch :foo do\n param 'Integer', :param1\n param 'Any', :param2\n optional_param 'Array[String]', :param3\n return_type 'Undef'\n end\n\n # @param param The first parameter.\n # @param block The block parameter.\n # @return Returns a string.\n dispatch :other do\n param 'Boolean', :param\n block_param\n return_type 'String'\n end\nend" }, { "name": "func4x_1", "file": "(stdin)", "line": 35, "type": "ruby4x", "signatures": [ { "signature": "func4x_1(Integer $param1)", "docstring": { "text": "An example 4.x function with only one signature.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } } ], "docstring": { "text": "An example 4.x function with only one signature.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "source": "Puppet::Functions.create_function(:func4x_1) do\n # @param param1 The first parameter.\n # @return [Undef] Returns nothing.\n dispatch :foobarbaz do\n param 'Integer', :param1\n end\nend" } ], "puppet_tasks": [ { "name": "(stdin)", "file": "(stdin)", "line": 0, "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]" ] } ] }, "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": false, "input_method": "stdin" } ], "puppet_plans": [ ] } puppet-strings-2.1.0/spec/fixtures/unit/json/output_with_plan.json000066400000000000000000000450411331446220200255520ustar00rootroot00000000000000{ "puppet_classes": [ { "name": "klass", "file": "(stdin)", "line": 7, "inherits": "foo::bar", "docstring": { "text": "A simple class.", "tags": [ { "tag_name": "todo", "text": "Do a thing" }, { "tag_name": "note", "text": "Some note" }, { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" } ] }, "defaults": { "param3": "hi" }, "source": "class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {\n}" } ], "defined_types": [ { "name": "dt", "file": "(stdin)", "line": 14, "docstring": { "text": "A simple defined type.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" } ] }, "defaults": { "param3": "hi" }, "source": "define dt(Integer $param1, $param2, String $param3 = hi) {\n}" } ], "resource_types": [ { "name": "apt_key", "file": "(stdin)", "line": 92, "docstring": { "text": "This type provides Puppet with the capabilities to manage GPG keys needed\nby apt to perform package validation. Apt has it's own GPG keyring that can\nbe manipulated through the `apt-key` command.\n**Autorequires**:\nIf Puppet is given the location of a key file which looks like an absolute\npath this type will autorequire that file.", "tags": [ { "tag_name": "summary", "text": "Example resource type using the new API." }, { "tag_name": "raise", "text": "SomeError" }, { "tag_name": "example", "text": "apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':\n source => 'http://apt.puppetlabs.com/pubkey.gpg'\n}", "name": "here's an example" } ] }, "properties": [ { "name": "ensure", "description": "Whether this apt key should be present or absent on the target system.", "data_type": "Enum[present, absent]" }, { "name": "created", "description": "Date the key was created, in ISO format.", "data_type": "String" } ], "parameters": [ { "name": "id", "description": "The ID of the key you want to manage.", "data_type": "Variant[Pattern[/A(0x)?[0-9a-fA-F]{8}Z/], Pattern[/A(0x)?[0-9a-fA-F]{16}Z/], Pattern[/A(0x)?[0-9a-fA-F]{40}Z/]]", "isnamevar": true } ] }, { "name": "database", "file": "(stdin)", "line": 54, "docstring": { "text": "An example database server resource type." }, "properties": [ { "name": "ensure", "description": "What state the database should be in.", "values": [ "present", "absent", "up", "down" ], "aliases": { "up": "present", "down": "absent" }, "default": "up" }, { "name": "file", "description": "The database file to use." }, { "name": "log_level", "description": "The log level to use.", "values": [ "debug", "warn", "error" ], "default": "warn" } ], "parameters": [ { "name": "address", "description": "The database server name.", "isnamevar": true }, { "name": "encryption_key", "description": "The encryption key to use." }, { "name": "encrypt", "description": "Whether or not to encrypt the database.", "values": [ "true", "false", "yes", "no" ], "default": "false" } ], "features": [ { "name": "encryption", "description": "The provider supports encryption." } ] } ], "providers": [ { "name": "linux", "type_name": "database", "file": "(stdin)", "line": 43, "docstring": { "text": "An example provider on Linux." }, "confines": { "kernel": "Linux", "osfamily": "RedHat" }, "features": [ "implements_some_feature", "some_other_feature" ], "defaults": [ [ [ "kernel", "Linux" ] ], [ [ "osfamily", "RedHat" ], [ "operatingsystemmajrelease", "7" ] ] ], "commands": { "foo": "/usr/bin/foo" } } ], "puppet_functions": [ { "name": "func", "file": "(stdin)", "line": 6, "type": "puppet", "signatures": [ { "signature": "func(Integer $param1, Any $param2, String $param3 = hi)", "docstring": { "text": "A simple function.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } } ], "docstring": { "text": "A simple function.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "defaults": { "param3": "hi" }, "source": "function func(Integer $param1, $param2, String $param3 = hi) {\n}" }, { "name": "func3x", "file": "(stdin)", "line": 1, "type": "ruby3x", "signatures": [ { "signature": "func3x(String $first, Any $second)", "docstring": { "text": "An example 3.x function.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "String" ], "name": "first" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "second" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } } ], "docstring": { "text": "An example 3.x function.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "String" ], "name": "first" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "second" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "source": "Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC\nAn example 3.x function.\n@param [String] first The first parameter.\n@param second The second parameter.\n@return [Undef] Returns nothing.\nDOC\n) do |*args|\nend" }, { "name": "func4x", "file": "(stdin)", "line": 11, "type": "ruby4x", "signatures": [ { "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)", "docstring": { "text": "The first overload.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "The third parameter.", "types": [ "Optional[Array[String]]" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } }, { "signature": "func4x(Boolean $param, Callable &$block)", "docstring": { "text": "", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Boolean" ], "name": "param" }, { "tag_name": "param", "text": "The block parameter.", "types": [ "Callable" ], "name": "&block" }, { "tag_name": "return", "text": "Returns a string.", "types": [ "String" ] } ] } } ], "docstring": { "text": "An example 4.x function.", "tags": [ { "tag_name": "overload", "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)", "docstring": { "text": "The first overload.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "The third parameter.", "types": [ "Optional[Array[String]]" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "name": "func4x" }, { "tag_name": "overload", "signature": "func4x(Boolean $param, Callable &$block)", "docstring": { "text": "", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Boolean" ], "name": "param" }, { "tag_name": "param", "text": "The block parameter.", "types": [ "Callable" ], "name": "&block" }, { "tag_name": "return", "text": "Returns a string.", "types": [ "String" ] } ] }, "name": "func4x" } ] }, "source": "Puppet::Functions.create_function(:func4x) do\n # The first overload.\n # @param param1 The first parameter.\n # @param param2 The second parameter.\n # @param param3 The third parameter.\n # @return Returns nothing.\n dispatch :foo do\n param 'Integer', :param1\n param 'Any', :param2\n optional_param 'Array[String]', :param3\n return_type 'Undef'\n end\n\n # @param param The first parameter.\n # @param block The block parameter.\n # @return Returns a string.\n dispatch :other do\n param 'Boolean', :param\n block_param\n return_type 'String'\n end\nend" }, { "name": "func4x_1", "file": "(stdin)", "line": 35, "type": "ruby4x", "signatures": [ { "signature": "func4x_1(Integer $param1)", "docstring": { "text": "An example 4.x function with only one signature.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } } ], "docstring": { "text": "An example 4.x function with only one signature.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "source": "Puppet::Functions.create_function(:func4x_1) do\n # @param param1 The first parameter.\n # @return [Undef] Returns nothing.\n dispatch :foobarbaz do\n param 'Integer', :param1\n end\nend" } ], "puppet_tasks": [ { "name": "(stdin)", "file": "(stdin)", "line": 0, "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]" ] } ] }, "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": false, "input_method": "stdin" } ], "puppet_plans": [ { "name": "plann", "file": "(stdin)", "line": 5, "docstring": { "text": "A simple plan.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "String" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "Integer" ], "name": "param3" } ] }, "defaults": { "param3": "1" }, "source": "plan plann(String $param1, $param2, Integer $param3 = 1) {\n}" } ] } puppet-strings-2.1.0/spec/fixtures/unit/json/output_without_puppet_function.json000066400000000000000000000305571331446220200306000ustar00rootroot00000000000000{ "puppet_classes": [ { "name": "klass", "file": "(stdin)", "line": 5, "inherits": "foo::bar", "docstring": { "text": "A simple class.", "tags": [ { "tag_name": "todo", "text": "Do a thing" }, { "tag_name": "note", "text": "Some note" }, { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" } ] }, "defaults": { "param3": "hi" }, "source": "class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {\n}" } ], "defined_types": [ { "name": "dt", "file": "(stdin)", "line": 12, "docstring": { "text": "A simple defined type.", "tags": [ { "tag_name": "param", "text": "First param.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "Second param.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "Third param.", "types": [ "String" ], "name": "param3" } ] }, "defaults": { "param3": "hi" }, "source": "define dt(Integer $param1, $param2, String $param3 = hi) {\n}" } ], "resource_types": [ { "name": "database", "file": "(stdin)", "line": 54, "docstring": { "text": "An example database server resource type." }, "properties": [ { "name": "ensure", "description": "What state the database should be in.", "values": [ "present", "absent", "up", "down" ], "aliases": { "up": "present", "down": "absent" }, "default": "up" }, { "name": "file", "description": "The database file to use." }, { "name": "log_level", "description": "The log level to use.", "values": [ "debug", "warn", "error" ], "default": "warn" } ], "parameters": [ { "name": "address", "description": "The database server name.", "isnamevar": true }, { "name": "encryption_key", "description": "The encryption key to use." }, { "name": "encrypt", "description": "Whether or not to encrypt the database.", "values": [ "true", "false", "yes", "no" ], "default": "false" } ], "features": [ { "name": "encryption", "description": "The provider supports encryption." } ] } ], "providers": [ { "name": "linux", "type_name": "database", "file": "(stdin)", "line": 43, "docstring": { "text": "An example provider on Linux." }, "confines": { "kernel": "Linux", "osfamily": "RedHat" }, "features": [ "implements_some_feature", "some_other_feature" ], "defaults": [ [ [ "kernel", "Linux" ] ], [ [ "osfamily", "RedHat" ], [ "operatingsystemmajrelease", "7" ] ] ], "commands": { "foo": "/usr/bin/foo" } } ], "puppet_functions": [ { "name": "func3x", "file": "(stdin)", "line": 1, "type": "ruby3x", "signatures": [ { "signature": "func3x(String $first, Any $second)", "docstring": { "text": "An example 3.x function.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "String" ], "name": "first" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "second" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } } ], "docstring": { "text": "An example 3.x function.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "String" ], "name": "first" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "second" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "source": "Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC\nAn example 3.x function.\n@param [String] first The first parameter.\n@param second The second parameter.\n@return [Undef] Returns nothing.\nDOC\n) do |*args|\nend" }, { "name": "func4x", "file": "(stdin)", "line": 11, "type": "ruby4x", "signatures": [ { "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)", "docstring": { "text": "The first overload.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "The third parameter.", "types": [ "Optional[Array[String]]" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } }, { "signature": "func4x(Boolean $param, Callable &$block)", "docstring": { "text": "", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Boolean" ], "name": "param" }, { "tag_name": "param", "text": "The block parameter.", "types": [ "Callable" ], "name": "&block" }, { "tag_name": "return", "text": "Returns a string.", "types": [ "String" ] } ] } } ], "docstring": { "text": "An example 4.x function.", "tags": [ { "tag_name": "overload", "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)", "docstring": { "text": "The first overload.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "param", "text": "The second parameter.", "types": [ "Any" ], "name": "param2" }, { "tag_name": "param", "text": "The third parameter.", "types": [ "Optional[Array[String]]" ], "name": "param3" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "name": "func4x" }, { "tag_name": "overload", "signature": "func4x(Boolean $param, Callable &$block)", "docstring": { "text": "", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Boolean" ], "name": "param" }, { "tag_name": "param", "text": "The block parameter.", "types": [ "Callable" ], "name": "&block" }, { "tag_name": "return", "text": "Returns a string.", "types": [ "String" ] } ] }, "name": "func4x" } ] }, "source": "Puppet::Functions.create_function(:func4x) do\n # The first overload.\n # @param param1 The first parameter.\n # @param param2 The second parameter.\n # @param param3 The third parameter.\n # @return Returns nothing.\n dispatch :foo do\n param 'Integer', :param1\n param 'Any', :param2\n optional_param 'Array[String]', :param3\n return_type 'Undef'\n end\n\n # @param param The first parameter.\n # @param block The block parameter.\n # @return Returns a string.\n dispatch :other do\n param 'Boolean', :param\n block_param\n return_type 'String'\n end\nend" }, { "name": "func4x_1", "file": "(stdin)", "line": 35, "type": "ruby4x", "signatures": [ { "signature": "func4x_1(Integer $param1)", "docstring": { "text": "An example 4.x function with only one signature.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] } } ], "docstring": { "text": "An example 4.x function with only one signature.", "tags": [ { "tag_name": "param", "text": "The first parameter.", "types": [ "Integer" ], "name": "param1" }, { "tag_name": "return", "text": "Returns nothing.", "types": [ "Undef" ] } ] }, "source": "Puppet::Functions.create_function(:func4x_1) do\n # @param param1 The first parameter.\n # @return [Undef] Returns nothing.\n dispatch :foobarbaz do\n param 'Integer', :param1\n end\nend" } ] } puppet-strings-2.1.0/spec/fixtures/unit/markdown/000077500000000000000000000000001331446220200221175ustar00rootroot00000000000000puppet-strings-2.1.0/spec/fixtures/unit/markdown/output.md000066400000000000000000000143621331446220200240070ustar00rootroot00000000000000# Reference ## Table of Contents **Classes** _Public Classes_ * [`klass`](#klass): A simple class. _Private Classes_ * `noparams`: Overview for class noparams **Defined types** * [`klass::dt`](#klassdt): A simple defined type. **Resource types** * [`apt_key`](#apt_key): Example resource type using the new API. * [`database`](#database): An example database server type. **Functions** * [`func`](#func): A simple Puppet function. * [`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 An overview for a simple class. * **TODO** Do a thing * **Note** some note * **Since** 1.0.0 * **See also** www.puppet.com #### Examples ##### This is an example ```puppet class { 'klass': param1 => 1, param3 => 'foo', } ``` ##### This is another example ```puppet class { 'klass': param1 => 1, param3 => 'foo', } ``` #### Parameters The following parameters are available in the `klass` class. ##### `param1` Data type: `Integer` First param. Default value: 1 ##### `param2` Data type: `Any` Second param. Options: * **:opt1** `String`: something about opt1 * **:opt2** `Hash`: a hash of stuff Default value: `undef` ##### `param3` Data type: `String` Third param. Default value: 'hi' ## Defined types ### klass::dt An overview for a simple defined type. * **Since** 1.1.0 * **See also** www.puppet.com #### Examples ##### Here's an example of this type: ```puppet klass::dt { 'foo': param1 => 33, param4 => false, } ``` #### Parameters The following parameters are available in the `klass::dt` defined type. ##### `param1` Data type: `Integer` First param. Default value: 44 ##### `param2` Data type: `Any` Second param. Options: * **:opt1** `String`: something about opt1 * **:opt2** `Hash`: a hash of stuff ##### `param3` Data type: `String` Third param. Default value: 'hi' ##### `param4` Data type: `Boolean` Fourth param. Default value: `true` ## Resource types ### apt_key This type provides Puppet with the capabilities to manage GPG keys needed by apt to perform package validation. Apt has it's own GPG keyring that can be manipulated through the `apt-key` command. **Autorequires**: If Puppet is given the location of a key file which looks like an absolute path this type will autorequire that file. #### Examples ##### here's an example ```puppet apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': source => 'http://apt.puppetlabs.com/pubkey.gpg' } ``` #### Properties The following properties are available in the `apt_key` type. ##### `ensure` Data type: `Enum[present, absent]` Whether this apt key should be present or absent on the target system. ##### `created` Data type: `String` Date the key was created, in ISO format. #### Parameters The following parameters are available in the `apt_key` type. ##### `id` namevar Data type: `Variant[Pattern[/A(0x)?[0-9a-fA-F]{8}Z/], Pattern[/A(0x)?[0-9a-fA-F]{16}Z/], Pattern[/A(0x)?[0-9a-fA-F]{40}Z/]]` _*this data type contains a regex that may not be accurately reflected in generated documentation_ The ID of the key you want to manage. ### database An example database server type. #### Examples ##### here's an example ```puppet database { 'foo': address => 'qux.baz.bar', } ``` #### Properties The following properties are available in the `database` type. ##### `ensure` Valid values: present, absent, up, down Aliases: "up"=>"present", "down"=>"absent" What state the database should be in. Default value: up ##### `file` The database file to use. ##### `log_level` Valid values: debug, warn, error The log level to use. Default value: warn #### Parameters The following parameters are available in the `database` type. ##### `address` namevar The database server name. ##### `encryption_key` The encryption key to use. ##### `encrypt` Valid values: `true`, `false`, yes, no Whether or not to encrypt the database. Default value: `false` ## Functions ### func Type: Puppet Language A simple Puppet function. #### `func(Integer $param1, Any $param2, String $param3 = hi)` A simple Puppet function. Returns: `Undef` Returns nothing. Raises: * `SomeError` this is some error ##### `param1` Data type: `Integer` First param. ##### `param2` Data type: `Any` Second param. ##### `param3` Data type: `String` Third param. Options: * **:param3opt** `Array`: Something about this option ### func3x Type: Ruby 3.x API Documentation for an example 3.x function. #### `func3x(String $param1, Integer $param2)` Documentation for an example 3.x function. Returns: `Undef` ##### `param1` Data type: `String` The first parameter. ##### `param2` Data type: `Integer` The second parameter. ### func4x Type: Ruby 4.x API An example 4.x function. #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)` An overview for the first overload. Returns: `Undef` Returns nothing. ##### `param1` Data type: `Integer` The first parameter. ##### `param2` Data type: `Any` The second parameter. Options: * **:option** `String`: an option * **:option2** `String`: another option ##### `param3` Data type: `Optional[Array[String]]` The third parameter. #### `func4x(Boolean $param, Callable &$block)` An overview for the second overload. Returns: `String` Returns a string. ##### `param` Data type: `Boolean` The first parameter. ##### `&block` Data type: `Callable` The block parameter. ### func4x_1 Type: Ruby 4.x API An example 4.x function with only one signature. #### `func4x_1(Integer $param1)` An example 4.x function with only one signature. Returns: `Undef` Returns nothing. ##### `param1` 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 puppet-strings-2.1.0/spec/fixtures/unit/markdown/output_with_plan.md000066400000000000000000000150771331446220200260600ustar00rootroot00000000000000# Reference ## Table of Contents **Classes** _Public Classes_ * [`klass`](#klass): A simple class. _Private Classes_ * `noparams`: Overview for class noparams **Defined types** * [`klass::dt`](#klassdt): A simple defined type. **Resource types** * [`apt_key`](#apt_key): Example resource type using the new API. * [`database`](#database): An example database server type. **Functions** * [`func`](#func): A simple Puppet function. * [`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. **Plans** * [`plann`](#plann): A simple plan. ## Classes ### klass An overview for a simple class. * **TODO** Do a thing * **Note** some note * **Since** 1.0.0 * **See also** www.puppet.com #### Examples ##### This is an example ```puppet class { 'klass': param1 => 1, param3 => 'foo', } ``` ##### This is another example ```puppet class { 'klass': param1 => 1, param3 => 'foo', } ``` #### Parameters The following parameters are available in the `klass` class. ##### `param1` Data type: `Integer` First param. Default value: 1 ##### `param2` Data type: `Any` Second param. Options: * **:opt1** `String`: something about opt1 * **:opt2** `Hash`: a hash of stuff Default value: `undef` ##### `param3` Data type: `String` Third param. Default value: 'hi' ## Defined types ### klass::dt An overview for a simple defined type. * **Since** 1.1.0 * **See also** www.puppet.com #### Examples ##### Here's an example of this type: ```puppet klass::dt { 'foo': param1 => 33, param4 => false, } ``` #### Parameters The following parameters are available in the `klass::dt` defined type. ##### `param1` Data type: `Integer` First param. Default value: 44 ##### `param2` Data type: `Any` Second param. Options: * **:opt1** `String`: something about opt1 * **:opt2** `Hash`: a hash of stuff ##### `param3` Data type: `String` Third param. Default value: 'hi' ##### `param4` Data type: `Boolean` Fourth param. Default value: `true` ## Resource types ### apt_key This type provides Puppet with the capabilities to manage GPG keys needed by apt to perform package validation. Apt has it's own GPG keyring that can be manipulated through the `apt-key` command. **Autorequires**: If Puppet is given the location of a key file which looks like an absolute path this type will autorequire that file. #### Examples ##### here's an example ```puppet apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': source => 'http://apt.puppetlabs.com/pubkey.gpg' } ``` #### Properties The following properties are available in the `apt_key` type. ##### `ensure` Data type: `Enum[present, absent]` Whether this apt key should be present or absent on the target system. ##### `created` Data type: `String` Date the key was created, in ISO format. #### Parameters The following parameters are available in the `apt_key` type. ##### `id` namevar Data type: `Variant[Pattern[/A(0x)?[0-9a-fA-F]{8}Z/], Pattern[/A(0x)?[0-9a-fA-F]{16}Z/], Pattern[/A(0x)?[0-9a-fA-F]{40}Z/]]` _*this data type contains a regex that may not be accurately reflected in generated documentation_ The ID of the key you want to manage. ### database An example database server type. #### Examples ##### here's an example ```puppet database { 'foo': address => 'qux.baz.bar', } ``` #### Properties The following properties are available in the `database` type. ##### `ensure` Valid values: present, absent, up, down Aliases: "up"=>"present", "down"=>"absent" What state the database should be in. Default value: up ##### `file` The database file to use. ##### `log_level` Valid values: debug, warn, error The log level to use. Default value: warn #### Parameters The following parameters are available in the `database` type. ##### `address` namevar The database server name. ##### `encryption_key` The encryption key to use. ##### `encrypt` Valid values: `true`, `false`, yes, no Whether or not to encrypt the database. Default value: `false` ## Functions ### func Type: Puppet Language A simple Puppet function. #### `func(Integer $param1, Any $param2, String $param3 = hi)` A simple Puppet function. Returns: `Undef` Returns nothing. Raises: * `SomeError` this is some error ##### `param1` Data type: `Integer` First param. ##### `param2` Data type: `Any` Second param. ##### `param3` Data type: `String` Third param. Options: * **:param3opt** `Array`: Something about this option ### func3x Type: Ruby 3.x API Documentation for an example 3.x function. #### `func3x(String $param1, Integer $param2)` Documentation for an example 3.x function. Returns: `Undef` ##### `param1` Data type: `String` The first parameter. ##### `param2` Data type: `Integer` The second parameter. ### func4x Type: Ruby 4.x API An example 4.x function. #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)` An overview for the first overload. Returns: `Undef` Returns nothing. ##### `param1` Data type: `Integer` The first parameter. ##### `param2` Data type: `Any` The second parameter. Options: * **:option** `String`: an option * **:option2** `String`: another option ##### `param3` Data type: `Optional[Array[String]]` The third parameter. #### `func4x(Boolean $param, Callable &$block)` An overview for the second overload. Returns: `String` Returns a string. ##### `param` Data type: `Boolean` The first parameter. ##### `&block` Data type: `Callable` The block parameter. ### func4x_1 Type: Ruby 4.x API An example 4.x function with only one signature. #### `func4x_1(Integer $param1)` An example 4.x function with only one signature. Returns: `Undef` Returns nothing. ##### `param1` 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 ## Plans ### plann A simple plan. #### Parameters The following parameters are available in the `plann` plan. ##### `param1` Data type: `String` First param. ##### `param2` Data type: `Any` Second param. ##### `param3` Data type: `Integer` Third param. Default value: 1 puppet-strings-2.1.0/spec/spec_helper.rb000066400000000000000000000023211331446220200202610ustar00rootroot00000000000000if ENV['COVERAGE'] == 'yes' require 'simplecov' require 'simplecov-console' require 'codecov' SimpleCov.formatters = [ SimpleCov::Formatter::HTMLFormatter, SimpleCov::Formatter::Console, SimpleCov::Formatter::Codecov, ] SimpleCov.start do track_files 'lib/**/*.rb' add_filter '/spec' end end require 'mocha' require 'rspec' require 'puppet/version' require 'puppet-strings' require 'puppet-strings/markdown' require 'puppet-strings/markdown/base' require 'puppet-strings/yard' # Explicitly set up YARD once PuppetStrings::Yard.setup! # Enable testing of Puppet functions if running against 4.1+ TEST_PUPPET_FUNCTIONS = Puppet::Util::Package.versioncmp(Puppet.version, "4.1.0") >= 0 # Enable testing of Puppet language functions declared with return type if running against 4.8+ TEST_FUNCTION_RETURN_TYPE = Puppet::Util::Package.versioncmp(Puppet.version, "4.8.0") >= 0 # Enable testing of Plans if Puppet version is greater than 5.0.0 TEST_PUPPET_PLANS = Puppet::Util::Package.versioncmp(Puppet.version, "5.0.0") >= 0 RSpec.configure do |config| config.mock_with :mocha config.before(:each) do # Always clear the YARD registry before each example YARD::Registry.clear end end puppet-strings-2.1.0/spec/spec_helper_acceptance.rb000066400000000000000000000016261331446220200224360ustar00rootroot00000000000000require 'beaker-rspec/spec_helper' require 'beaker-rspec/helpers/serverspec' $LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__), 'acceptance/lib')) require 'util' unless ENV['RS_PROVISION'] == 'no' install_puppet end RSpec.configure do |c| # Readable test descriptions c.formatter = :documentation # Configure all nodes in nodeset c.before :suite do extend PuppetStrings::Acceptance::CommandUtils hosts.each do |host| scp_to(host, Dir.glob('puppet-strings*.gem').first, 'puppet-strings.gem') install_ca_certs(host) on host, "#{gem_command(host)} install yard" on host, "#{gem_command(host)} install rgen" on host, "#{gem_command(host)} install puppet-strings.gem" scp_to(host, Dir.glob('spec/fixtures/acceptance/modules/test/pkg/username-test*.gz').first, 'test.tar.gz') on host, puppet('module', 'install', 'test.tar.gz') end end end puppet-strings-2.1.0/spec/unit/000077500000000000000000000000001331446220200164245ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/000077500000000000000000000000001331446220200214305ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/json_spec.rb000066400000000000000000000143411331446220200237430ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/json' require 'tempfile' describe PuppetStrings::Json do before :each do # Populate the YARD registry with both Puppet and Ruby source YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) # A simple class. # @todo Do a thing # @note Some note # @param param1 First param. # @param param2 Second param. # @param param3 Third param. class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { } # A simple defined type. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. define dt(Integer $param1, $param2, String $param3 = hi) { } SOURCE YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) if TEST_PUPPET_PLANS # A simple plan. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. plan plann(String $param1, $param2, Integer $param3 = 1) { } SOURCE # Only include Puppet functions for 4.1+ YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) if TEST_PUPPET_FUNCTIONS # A simple function. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. # @return [Undef] Returns nothing. function func(Integer $param1, $param2, String $param3 = hi) { } SOURCE YARD::Parser::SourceParser.parse_string(<<-SOURCE, :json) { "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 YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby) Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC An example 3.x function. @param [String] first The first parameter. @param second The second parameter. @return [Undef] Returns nothing. DOC ) do |*args| end # An example 4.x function. Puppet::Functions.create_function(:func4x) do # The first overload. # @param param1 The first parameter. # @param param2 The second parameter. # @param param3 The third parameter. # @return Returns nothing. dispatch :foo do param 'Integer', :param1 param 'Any', :param2 optional_param 'Array[String]', :param3 return_type 'Undef' end # @param param The first parameter. # @param block The block parameter. # @return Returns a string. dispatch :other do param 'Boolean', :param block_param return_type 'String' end end # An example 4.x function with only one signature. Puppet::Functions.create_function(:func4x_1) do # @param param1 The first parameter. # @return [Undef] Returns nothing. dispatch :foobarbaz do param 'Integer', :param1 end end Puppet::Type.type(:database).provide :linux do desc 'An example provider on Linux.' confine kernel: 'Linux' confine osfamily: 'RedHat' defaultfor :kernel => 'Linux' defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7' has_feature :implements_some_feature has_feature :some_other_feature commands foo: '/usr/bin/foo' end Puppet::Type.newtype(:database) do desc 'An example database server resource type.' feature :encryption, 'The provider supports encryption.', methods: [:encrypt] ensurable do desc 'What state the database should be in.' defaultvalues aliasvalue(:up, :present) aliasvalue(:down, :absent) defaultto :up end newparam(:address) do isnamevar desc 'The database server name.' end newparam(:encryption_key, required_features: :encryption) do desc 'The encryption key to use.' end newparam(:encrypt, :parent => Puppet::Parameter::Boolean) do desc 'Whether or not to encrypt the database.' defaultto false end newproperty(:file) do desc 'The database file to use.' end newproperty(:log_level) do desc 'The log level to use.' newvalue(:debug) newvalue(:warn) newvalue(:error) defaultto 'warn' end end Puppet::ResourceApi.register_type( name: 'apt_key', docs: <<-EOS, @summary Example resource type using the new API. @raise SomeError This type provides Puppet with the capabilities to manage GPG keys needed by apt to perform package validation. Apt has it's own GPG keyring that can be manipulated through the `apt-key` command. @example here's an example apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': source => 'http://apt.puppetlabs.com/pubkey.gpg' } **Autorequires**: If Puppet is given the location of a key file which looks like an absolute path this type will autorequire that file. EOS attributes: { ensure: { type: 'Enum[present, absent]', desc: 'Whether this apt key should be present or absent on the target system.' }, id: { type: 'Variant[Pattern[/\A(0x)?[0-9a-fA-F]{8}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{16}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{40}\Z/]]', behaviour: :namevar, desc: 'The ID of the key you want to manage.', }, # ... created: { type: 'String', behaviour: :read_only, desc: 'Date the key was created, in ISO format.', }, }, autorequires: { file: '$source', # will evaluate to the value of the `source` attribute package: 'apt', }, ) SOURCE end let(:filename) do if TEST_PUPPET_PLANS 'output_with_plan.json' else TEST_PUPPET_FUNCTIONS ? 'output.json' : 'output_without_puppet_function.json' end end let(:baseline_path) { File.join(File.dirname(__FILE__), "../../fixtures/unit/json/#{filename}") } let(:baseline) { File.read(baseline_path) } describe 'rendering JSON to a file' do it 'should output the expected JSON content' do Tempfile.open('json') do |file| PuppetStrings::Json.render(file.path) expect(File.read(file.path)).to eq(baseline) end end end describe 'rendering JSON to stdout' do it 'should output the expected JSON content' do expect{ PuppetStrings::Json.render(nil) }.to output(baseline).to_stdout end end end puppet-strings-2.1.0/spec/unit/puppet-strings/markdown/000077500000000000000000000000001331446220200232525ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/markdown/base_spec.rb000066400000000000000000000065561331446220200255370ustar00rootroot00000000000000require 'spec_helper' describe PuppetStrings::Markdown::Base do context 'basic class' do before :each do YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) # An overview # @api private # @summary A simple class. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { } SOURCE end let(:reg) { YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)[0] } let(:component) { PuppetStrings::Markdown::Base.new(reg, 'class') } describe '#name' do it 'returns the expected name' do expect(component.name).to eq 'klass' end end [ 'examples', 'see', 'since', 'return_val', 'return_type',].each do |method| describe "##{method}" do it 'returns nil' do expect(component.method(method.to_sym).call).to be_nil end end end describe '#private?' do it do expect(component.private?).to be true end end describe '#params' do it 'returns the expected params' do expect(component.params.size).to eq 3 end end describe '#summary' do it 'returns the expected summary' do expect(component.summary).to eq 'A simple class.' end end describe '#toc_info' do let(:toc) { component.toc_info } it 'returns a hash' do expect(toc).to be_instance_of Hash end it 'prefers the summary for :desc' do expect(toc[:desc]).to eq 'A simple class.' end end end context 'less basic class' do before :each do YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) # An overview # It's a longer overview # Ya know? # @example A simple example. # class { 'klass::yeah': # param1 => 1, # } # @param param1 First param. # @param param2 Second param. # @param param3 Third param. class klass::yeah( Integer $param1, $param2, String $param3 = hi ) inherits foo::bar { } SOURCE end let(:reg) { YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)[0] } let(:component) { PuppetStrings::Markdown::Base.new(reg, 'class') } describe '#name' do it 'returns the expected name' do expect(component.name).to eq 'klass::yeah' end end ['summary', 'see', 'since', 'return_val', 'return_type'].each do |method| describe "##{method}" do it 'returns nil' do expect(component.method(method.to_sym).call).to be_nil end end end describe '#examples' do it 'should return one example' do expect(component.examples.size).to eq 1 end end describe '#params' do it 'returns the expected params' do expect(component.params.size).to eq 3 end end describe '#private?' do it do expect(component.private?).to be false end end describe '#toc_info' do let(:toc) { component.toc_info } it 'returns a hash' do expect(toc).to be_instance_of Hash end it 'uses overview for :desc in absence of summary' do expect(toc[:desc]).to eq 'An overview It\'s a longer overview Ya know?' end end describe '#link' do it 'returns a valid link' do expect(component.link).to eq 'klassyeah' end end end end puppet-strings-2.1.0/spec/unit/puppet-strings/markdown_spec.rb000066400000000000000000000166061331446220200246220ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/markdown' require 'puppet-strings/markdown/table_of_contents' require 'tempfile' describe PuppetStrings::Markdown do before :each do # Populate the YARD registry with both Puppet and Ruby source YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) # An overview for a simple class. # @summary A simple class. # @todo Do a thing # @note some note # @since 1.0.0 # @see www.puppet.com # @example This is an example # class { 'klass': # param1 => 1, # param3 => 'foo', # } # @example This is another example # class { 'klass': # param1 => 1, # param3 => 'foo', # } # @raise SomeError # @param param1 First param. # @param param2 Second param. # @option param2 [String] :opt1 something about opt1 # @option param2 [Hash] :opt2 a hash of stuff # @param param3 Third param. # class klass ( Integer $param1 = 1, $param2 = undef, String $param3 = 'hi' ) inherits foo::bar { } # Overview for class noparams # @api private class noparams () {} # An overview for a simple defined type. # @summary A simple defined type. # @since 1.1.0 # @see www.puppet.com # @example Here's an example of this type: # klass::dt { 'foo': # param1 => 33, # param4 => false, # } # @return shouldn't return squat # @raise SomeError # @param param1 First param. # @param param2 Second param. # @option param2 [String] :opt1 something about opt1 # @option param2 [Hash] :opt2 a hash of stuff # @param param3 Third param. # @param param4 Fourth param. define klass::dt ( Integer $param1 = 44, $param2, String $param3 = 'hi', Boolean $param4 = true ) { } SOURCE YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) if TEST_PUPPET_PLANS # A simple plan. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. plan plann(String $param1, $param2, Integer $param3 = 1) { } SOURCE YARD::Parser::SourceParser.parse_string(<<-SOURCE, :json) { "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 YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) # A simple Puppet function. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. # @option param3 [Array] :param3opt Something about this option # @raise SomeError this is some error # @return [Undef] Returns nothing. function func(Integer $param1, $param2, String $param3 = hi) { } SOURCE YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby) # An example 4.x function. Puppet::Functions.create_function(:func4x) do # An overview for the first overload. # @raise SomeError this is some error # @param param1 The first parameter. # @param param2 The second parameter. # @option param2 [String] :option an option # @option param2 [String] :option2 another option # @param param3 The third parameter. # @return Returns nothing. dispatch :foo do param 'Integer', :param1 param 'Any', :param2 optional_param 'Array[String]', :param3 return_type 'Undef' end # An overview for the second overload. # @param param The first parameter. # @param block The block parameter. # @return Returns a string. dispatch :other do param 'Boolean', :param block_param return_type 'String' end end # An example 4.x function with only one signature. Puppet::Functions.create_function(:func4x_1) do # @param param1 The first parameter. # @return [Undef] Returns nothing. dispatch :foobarbaz do param 'Integer', :param1 end end # An example 3.x function Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC Documentation for an example 3.x function. @param param1 [String] The first parameter. @param param2 [Integer] The second parameter. @return [Undef] @example Calling the function. func3x('hi', 10) DOC ) do |*args| #... end Puppet::Type.type(:database).provide :linux do desc 'An example provider on Linux.' confine kernel: 'Linux' confine osfamily: 'RedHat' defaultfor :kernel => 'Linux' defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7' has_feature :implements_some_feature has_feature :some_other_feature commands foo: '/usr/bin/foo' end Puppet::Type.newtype(:database) do desc <<-DESC An example database server type. @option opts :foo bar @raise SomeError @example here's an example database { 'foo': address => 'qux.baz.bar', } DESC feature :encryption, 'The provider supports encryption.', methods: [:encrypt] ensurable do desc 'What state the database should be in.' defaultvalues aliasvalue(:up, :present) aliasvalue(:down, :absent) defaultto :up end newparam(:address) do isnamevar desc 'The database server name.' end newparam(:encryption_key, required_features: :encryption) do desc 'The encryption key to use.' end newparam(:encrypt, :parent => Puppet::Parameter::Boolean) do desc 'Whether or not to encrypt the database.' defaultto false end newproperty(:file) do desc 'The database file to use.' end newproperty(:log_level) do desc 'The log level to use.' newvalue(:debug) newvalue(:warn) newvalue(:error) defaultto 'warn' end end Puppet::ResourceApi.register_type( name: 'apt_key', docs: <<-EOS, @summary Example resource type using the new API. @raise SomeError This type provides Puppet with the capabilities to manage GPG keys needed by apt to perform package validation. Apt has it's own GPG keyring that can be manipulated through the `apt-key` command. @example here's an example apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': source => 'http://apt.puppetlabs.com/pubkey.gpg' } **Autorequires**: If Puppet is given the location of a key file which looks like an absolute path this type will autorequire that file. EOS attributes: { ensure: { type: 'Enum[present, absent]', desc: 'Whether this apt key should be present or absent on the target system.' }, id: { type: 'Variant[Pattern[/\A(0x)?[0-9a-fA-F]{8}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{16}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{40}\Z/]]', behaviour: :namevar, desc: 'The ID of the key you want to manage.', }, # ... created: { type: 'String', behaviour: :read_only, desc: 'Date the key was created, in ISO format.', }, }, autorequires: { file: '$source', # will evaluate to the value of the `source` attribute package: 'apt', }, ) SOURCE end let(:filename) do if TEST_PUPPET_PLANS 'output_with_plan.md' else 'output.md' end end let(:baseline_path) { File.join(File.dirname(__FILE__), "../../fixtures/unit/markdown/#{filename}") } let(:baseline) { File.read(baseline_path) } describe 'rendering markdown to a file' do it 'should output the expected markdown content' do Tempfile.open('md') do |file| PuppetStrings::Markdown.render(file.path) expect(File.read(file.path)).to eq(baseline) end end end end puppet-strings-2.1.0/spec/unit/puppet-strings/yard/000077500000000000000000000000001331446220200223675ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/yard/code_objects/000077500000000000000000000000001331446220200250125ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/yard/code_objects/task_spec.rb000066400000000000000000000056341331446220200273230ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard/code_objects/task' require 'puppet-strings/yard/parsers/json/task_statement' describe PuppetStrings::Yard::CodeObjects::Task 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) } let(:statement) { PuppetStrings::Yard::Parsers::JSON::TaskStatement.new(json, source, "test.json") } subject { PuppetStrings::Yard::CodeObjects::Task.new(statement) } describe '#type' do it 'returns the correct type' do expect(subject.type).to eq(:puppet_task) end end describe '#source' do it 'returns the source' do expect(subject.source).to eq(source) end end describe '#to_hash' do let(:expected) do { :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 it 'returns the correct hash' do expect(subject.to_hash).to eq(expected) end end end puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/000077500000000000000000000000001331446220200241675ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/json/000077500000000000000000000000001331446220200251405ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/json/task_handler_spec.rb000066400000000000000000000056531331446220200311470ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard' describe PuppetStrings::Yard::Handlers::JSON::TaskHandler do subject { YARD::Parser::SourceParser.parse_string(source, :json) YARD::Registry.all(:puppet_task) } describe 'parsing source without a task definition' do let(:source) { 'notice hi' } it 'no defined types should be in the registry' do expect(subject.empty?).to eq(true) end end describe 'parsing source with a syntax error' do let(:source) { <<-SOURCE { "input_method": "stdin", "parameters": "database": { "description": "Database to connect to", "type": "Optional[String[1]]" } } } SOURCE } it 'should log an error' do expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\):/).to_stdout_from_any_process expect(subject.empty?).to eq(true) end end describe 'parsing a defined type with a missing docstring' do let(:source) { <<-SOURCE { "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 } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: Missing a description for Puppet Task \(stdin\)/).to_stdout_from_any_process end end describe 'parsing a defined type with a docstring' 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 } it 'should register a task object' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Task) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Tasks.instance) end end describe 'parsing a Task with a missing parameter description' do let(:source) { <<-SOURCE { "description": "Allows you to backup your database to local file.", "input_method": "stdin", "parameters": { "database": { "type": "Optional[String[1]]" } } } SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: Missing description for param 'database' in Puppet Task \(stdin\)/).to_stdout_from_any_process end end end puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/puppet/000077500000000000000000000000001331446220200255045ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb000066400000000000000000000152031331446220200316460ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard' describe PuppetStrings::Yard::Handlers::Puppet::ClassHandler do subject { YARD::Parser::SourceParser.parse_string(source, :puppet) YARD::Registry.all(:puppet_class) } describe 'parsing source without a class definition' do let(:source) { 'notice hi' } it 'no classes should be in the registry' do expect(subject.empty?).to eq(true) end end describe 'parsing source with a syntax error' do let(:source) { 'class foo{' } it 'should log an error' do expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of (file|input)/).to_stdout_from_any_process expect(subject.empty?).to eq(true) end end describe 'parsing a class with a missing docstring' do let(:source) { 'class foo{}' } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet class 'foo' at \(stdin\):1\./).to_stdout_from_any_process end end describe 'parsing a class with a docstring' do let(:source) { <<-SOURCE # A simple foo class. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { file { '/tmp/foo': ensure => present } } SOURCE } it 'should register a class object' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Class) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Classes.instance) expect(object.name).to eq(:foo) expect(object.statement).not_to eq(nil) expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', 'hi']]) expect(object.docstring).to eq('A simple foo class.') expect(object.docstring.tags.size).to eq(4) tags = object.docstring.tags(:param) expect(tags.size).to eq(3) expect(tags[0].name).to eq('param1') expect(tags[0].text).to eq('First param.') expect(tags[0].types).to eq(['Integer']) expect(tags[1].name).to eq('param2') expect(tags[1].text).to eq('Second param.') expect(tags[1].types).to eq(['Any']) expect(tags[2].name).to eq('param3') expect(tags[2].text).to eq('Third param.') expect(tags[2].types).to eq(['String']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a class with a missing parameter' do let(:source) { <<-SOURCE # A simple foo class. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. # @param param4 missing! class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { file { '/tmp/foo': ensure => present } } SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param4' has no matching parameter at \(stdin\):6\./).to_stdout_from_any_process end end describe 'parsing a class with a missing @param tag' do let(:source) { <<-SOURCE # A simple foo class. # @param param1 First param. # @param param2 Second param. class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { file { '/tmp/foo': ensure => present } } SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: Missing @param tag for parameter 'param3' near \(stdin\):4\./).to_stdout_from_any_process end end describe 'parsing a class with a typed parameter that also has a @param tag type which matches' do let(:source) { <<-SOURCE # A simple foo class. # @param [Integer] param1 First param. # @param param2 Second param. # @param param3 Third param. class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { file { '/tmp/foo': ensure => present } } SOURCE } it 'should respect the type that was documented' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) tags = subject.first.tags(:param) expect(tags.size).to eq(3) expect(tags[0].types).to eq(['Integer']) end end describe 'parsing a class with a typed parameter that also has a @param tag type which does not match' do let(:source) { <<-SOURCE # A simple foo class. # @param [Boolean] param1 First param. # @param param2 Second param. # @param param3 Third param. class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { file { '/tmp/foo': ensure => present } } SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: The type of the @param tag for parameter 'param1' does not match the parameter type specification near \(stdin\):5: ignoring in favor of parameter type information./).to_stdout_from_any_process end end describe 'parsing a class with a untyped parameter that also has a @param tag type' do let(:source) { <<-SOURCE # A simple foo class. # @param param1 First param. # @param [Boolean] param2 Second param. # @param param3 Third param. class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { file { '/tmp/foo': ensure => present } } SOURCE } it 'should respect the type that was documented' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) tags = subject.first.tags(:param) expect(tags.size).to eq(3) expect(tags[1].types).to eq(['Boolean']) end end describe 'parsing a class with a summary' do context 'when the summary has fewer than 140 characters' do let(:source) { <<-SOURCE # A simple foo class. # @summary A short summary. class foo() { file { '/tmp/foo': ensure => present } } SOURCE } it 'should parse the summary' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) summary = subject.first.tags(:summary) expect(summary.first.text).to eq('A short summary.') end end context 'when the summary has more than 140 characters' do let(:source) { <<-SOURCE # A simple foo class. # @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!! class foo() { file { '/tmp/foo': ensure => present } } SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_class 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process end end end end puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb000066400000000000000000000164131331446220200332040ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard' describe PuppetStrings::Yard::Handlers::Puppet::DefinedTypeHandler do subject { YARD::Parser::SourceParser.parse_string(source, :puppet) YARD::Registry.all(:puppet_defined_type) } describe 'parsing source without a defined type definition' do let(:source) { 'notice hi' } it 'no defined types should be in the registry' do expect(subject.empty?).to eq(true) end end describe 'parsing source with a syntax error' do let(:source) { 'define foo{' } it 'should log an error' do expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of (file|input)/).to_stdout_from_any_process expect(subject.empty?).to eq(true) end end describe 'parsing a defined type with a missing docstring' do let(:source) { 'define foo{}' } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet defined type 'foo' at \(stdin\):1\./).to_stdout_from_any_process end end describe 'parsing a defined type with a docstring' do let(:source) { <<-SOURCE # A simple foo defined type. # @param name The type name. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. define foo(Integer $param1, $param2, String $param3 = hi) { file { '/tmp/foo': ensure => present } } SOURCE } it 'does not output a warning for title/name' do expect{ subject }.not_to output(/\[warn\].*(name|title).*/).to_stdout_from_any_process end it 'should register a defined type object' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DefinedType) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DefinedTypes.instance) expect(object.name).to eq(:foo) expect(object.statement).not_to eq(nil) expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', 'hi']]) expect(object.docstring).to eq('A simple foo defined type.') expect(object.docstring.tags.size).to eq(5) tags = object.docstring.tags(:param) expect(tags.size).to eq(4) expect(tags[0].name).to eq('name') expect(tags[0].text).to eq('The type name.') expect(tags[0].types).to eq(nil) expect(tags[1].name).to eq('param1') expect(tags[1].text).to eq('First param.') expect(tags[1].types).to eq(['Integer']) expect(tags[2].name).to eq('param2') expect(tags[2].text).to eq('Second param.') expect(tags[2].types).to eq(['Any']) expect(tags[3].name).to eq('param3') expect(tags[3].text).to eq('Third param.') expect(tags[3].types).to eq(['String']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a defined type with a missing parameter' do let(:source) { <<-SOURCE # A simple foo defined type. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. # @param param4 missing! define foo(Integer $param1, $param2, String $param3 = hi) { file { '/tmp/foo': ensure => present } } SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param4' has no matching parameter at \(stdin\):6\./).to_stdout_from_any_process end end describe 'parsing a defined type with a missing @param tag' do let(:source) { <<-SOURCE # A simple foo defined type. # @param param1 First param. # @param param2 Second param. define foo(Integer $param1, $param2, String $param3 = hi) { file { '/tmp/foo': ensure => present } } SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: Missing @param tag for parameter 'param3' near \(stdin\):4\./).to_stdout_from_any_process end end describe 'parsing a defined type with a typed parameter that also has a @param tag type which matches' do let(:source) { <<-SOURCE # A simple foo defined type. # @param [Integer] param1 First param. # @param param2 Second param. # @param param3 Third param. define foo(Integer $param1, $param2, String $param3 = hi) { file { '/tmp/foo': ensure => present } } SOURCE } it 'should respect the type that was documented' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) tags = subject.first.tags(:param) expect(tags.size).to eq(3) expect(tags[0].types).to eq(['Integer']) end end describe 'parsing a defined type with a typed parameter that also has a @param tag type which does not match' do let(:source) { <<-SOURCE # A simple foo defined type. # @param [Boolean] param1 First param. # @param param2 Second param. # @param param3 Third param. define foo(Integer $param1, $param2, String $param3 = hi) { file { '/tmp/foo': ensure => present } } SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: The type of the @param tag for parameter 'param1' does not match the parameter type specification near \(stdin\):5: ignoring in favor of parameter type information./).to_stdout_from_any_process end end describe 'parsing a defined type with a untyped parameter that also has a @param tag type' do let(:source) { <<-SOURCE # A simple foo defined type. # @param param1 First param. # @param [Boolean] param2 Second param. # @param param3 Third param. define foo(Integer $param1, $param2, String $param3 = hi) { file { '/tmp/foo': ensure => present } } SOURCE } it 'should respect the type that was documented' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) tags = subject.first.tags(:param) expect(tags.size).to eq(3) expect(tags[1].types).to eq(['Boolean']) end end describe 'parsing a defined type with a summary' do context 'when the summary has fewer than 140 characters' do let(:source) { <<-SOURCE # A simple foo defined type. # @summary A short summary. # @param param1 First param. # @param [Boolean] param2 Second param. # @param param3 Third param. define foo(Integer $param1, $param2, String $param3 = hi) { file { '/tmp/foo': ensure => present } } SOURCE } it 'should parse the summary' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) summary = subject.first.tags(:summary) expect(summary.first.text).to eq('A short summary.') end end context 'when the summary has more than 140 characters' do let(:source) { <<-SOURCE # A simple foo defined type. # @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!! # @param param1 First param. # @param [Boolean] param2 Second param. # @param param3 Third param. define foo(Integer $param1, $param2, String $param3 = hi) { file { '/tmp/foo': ensure => present } } SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_defined_type 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process end end end end puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb000066400000000000000000000246751331446220200324030ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard' # Limit this spec to Puppet 4.1+ (when functions in Puppet were implemented) describe PuppetStrings::Yard::Handlers::Puppet::FunctionHandler, if: TEST_PUPPET_FUNCTIONS do subject { YARD::Parser::SourceParser.parse_string(source, :puppet) YARD::Registry.all(:puppet_function) } describe 'parsing source without a function definition' do let(:source) { 'notice hi' } it 'no functions should be in the registry' do expect(subject.empty?).to eq(true) end end describe 'parsing source with a syntax error' do let(:source) { 'function foo{' } it 'should log an error' do expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of/).to_stdout_from_any_process expect(subject.empty?).to eq(true) end end describe 'parsing a function with a missing docstring' do let(:source) { 'function foo{}' } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet function 'foo' at \(stdin\):1\./).to_stdout_from_any_process end end describe 'parsing a function with a docstring' do let(:source) { <<-SOURCE # A simple foo function. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. # @return [Undef] Returns nothing. function foo(Integer $param1, $param2, String $param3 = hi) { notice 'hello world' undef } SOURCE } it 'should register a function object' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::PUPPET)) expect(object.name).to eq(:foo) expect(object.signature).to eq('foo(Integer $param1, Any $param2, String $param3 = hi)') expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', 'hi']]) expect(object.docstring).to eq('A simple foo function.') expect(object.docstring.tags.size).to eq(5) tags = object.docstring.tags(:param) expect(tags.size).to eq(3) expect(tags[0].name).to eq('param1') expect(tags[0].text).to eq('First param.') expect(tags[0].types).to eq(['Integer']) expect(tags[1].name).to eq('param2') expect(tags[1].text).to eq('Second param.') expect(tags[1].types).to eq(['Any']) expect(tags[2].name).to eq('param3') expect(tags[2].text).to eq('Third param.') expect(tags[2].types).to eq(['String']) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].tag_name).to eq('return') expect(tags[0].text).to eq('Returns nothing.') expect(tags[0].types).to eq(['Undef']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a function with a missing parameter' do let(:source) { <<-SOURCE # A simple foo function. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. # @param param4 missing! # @return [Undef] Returns nothing. function foo(Integer $param1, $param2, String $param3 = hi) { notice 'hello world' } SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param4' has no matching parameter at \(stdin\):7\./).to_stdout_from_any_process end end describe 'parsing a function with a missing @param tag' do let(:source) { <<-SOURCE # A simple foo function. # @param param1 First param. # @param param2 Second param. # @return [Undef] Returns nothing. function foo(Integer $param1, $param2, String $param3 = hi) { notice 'hello world' } SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: Missing @param tag for parameter 'param3' near \(stdin\):5\./).to_stdout_from_any_process end end describe 'parsing a function with a typed parameter that also has a @param tag type which matches' do let(:source) { <<-SOURCE # A simple foo function. # @param [Integer] param1 First param. # @param param2 Second param. # @param param3 Third param. # @return [Undef] Returns nothing. function foo(Integer $param1, $param2, String $param3 = hi) { notice 'hello world' } SOURCE } it 'should respect the type that was documented' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) tags = subject.first.tags(:param) expect(tags.size).to eq(3) expect(tags[0].types).to eq(['Integer']) end end describe 'parsing a function with a typed parameter that also has a @param tag type which does not match' do let(:source) { <<-SOURCE # A simple foo function. # @param [Boolean] param1 First param. # @param param2 Second param. # @param param3 Third param. # @return [Undef] Returns nothing. function foo(Integer $param1, $param2, String $param3 = hi) { notice 'hello world' } SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: The type of the @param tag for parameter 'param1' does not match the parameter type specification near \(stdin\):6: ignoring in favor of parameter type information./).to_stdout_from_any_process end end describe 'parsing a function with a untyped parameter that also has a @param tag type' do let(:source) { <<-SOURCE # A simple foo function. # @param param1 First param. # @param [Boolean] param2 Second param. # @param param3 Third param. # @return [Undef] Returns nothing. function foo(Integer $param1, $param2, String $param3 = hi) { notice 'hello world' } SOURCE } it 'should respect the type that was documented' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) tags = subject.first.tags(:param) expect(tags.size).to eq(3) expect(tags[1].types).to eq(['Boolean']) end end describe 'parsing a function with a missing @return tag' do let(:source) { <<-SOURCE # A simple foo function. # @param param1 First param. # @param param2 Second param. # @param param3 Third param. function foo(Integer $param1, $param2, String $param3 = hi) { notice 'hello world' } SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):5\./).to_stdout_from_any_process end end describe 'parsing a function with a missing @return tag and return type specified in the function definition', if: TEST_FUNCTION_RETURN_TYPE do let(:source) { <<-SOURCE # A simple foo function. function foo() >> String { notice 'hello world' } SOURCE } it 'should register a function object with the correct return type' do expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):2\./).to_stdout_from_any_process expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].tag_name).to eq('return') expect(tags[0].text).to eq('') expect(tags[0].types).to eq(['String']) end end describe 'parsing a function with a non-conflicting return tag and type in function definition', if: TEST_FUNCTION_RETURN_TYPE do let(:source) { <<-SOURCE # A simple foo function # @return [String] Hi there function foo() >> String { notice 'hi there' } SOURCE } it 'should not output a warning if return types match' do expect{ subject }.not_to output(/Documented return type does not match return type in function definition/).to_stdout_from_any_process end end describe 'parsing a function with a conflicting return tag and type in function definition', if: TEST_FUNCTION_RETURN_TYPE do let(:source) { <<-SOURCE # A simple foo function. # @return [Integer] this is a lie. function foo() >> Struct[{'a' => Integer[1, 10]}] { notice 'hello world' } SOURCE } it 'should prefer the return type from the function definition' do expect{ subject }.to output(/\[warn\]: Documented return type does not match return type in function definition near \(stdin\):3\./).to_stdout_from_any_process expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].tag_name).to eq('return') expect(tags[0].text).to eq('this is a lie.') expect(tags[0].types).to eq(["Struct[{'a' => Integer[1, 10]}]"]) end end describe 'parsing a function without a return tag or return type in the function definition' do let(:source) { <<-SOURCE # A simple foo function. function foo() { notice 'hello world' } SOURCE } it 'should add a return tag with a default type value of Any' do expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):2\./).to_stdout_from_any_process expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].tag_name).to eq('return') expect(tags[0].text).to eq('') expect(tags[0].types).to eq(['Any']) end end describe 'parsing a function with a summary' do context 'when the summary has fewer than 140 characters' do let(:source) { <<-SOURCE # A simple foo function. # @summary A short summary. # @return [String] foo function foo() { notice 'hello world' } SOURCE } it 'should parse the summary' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) summary = subject.first.tags(:summary) expect(summary.first.text).to eq('A short summary.') end end context 'when the summary has more than 140 characters' do let(:source) { <<-SOURCE # A simple foo function. # @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!! function foo() { notice 'hello world' } SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_function 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process end end end end puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/ruby/000077500000000000000000000000001331446220200251505ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb000066400000000000000000000647461331446220200320520ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard' describe PuppetStrings::Yard::Handlers::Ruby::FunctionHandler do subject { YARD::Parser::SourceParser.parse_string(source, :ruby) YARD::Registry.all(:puppet_function) } describe 'parsing source without a function definition' do let(:source) { 'puts "hi"' } it 'no functions should be in the registry' do expect(subject.empty?).to eq(true) end end describe 'parsing 3.x API functions' do describe 'parsing a function with a missing docstring' do let(:source) { <<-SOURCE Puppet::Parser::Functions.newfunction(:foo) do |*args| end SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet function 'foo' at \(stdin\):1\./).to_stdout_from_any_process end end describe 'parsing a function with a doc parameter' do let(:source) { <<-SOURCE Puppet::Parser::Functions.newfunction(:foo, doc: <<-DOC An example 3.x function. @param [String] first The first parameter. @param second The second parameter. @return [Undef] Returns nothing. DOC ) do |*args| end SOURCE } it 'should register a function object' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_3X)) expect(object.name).to eq(:foo) expect(object.signature).to eq('foo(String $first, Any $second)') expect(object.parameters).to eq([['first', nil], ['second', nil]]) expect(object.docstring).to eq('An example 3.x function.') expect(object.docstring.tags.size).to eq(4) tags = object.docstring.tags(:param) expect(tags.size).to eq(2) expect(tags[0].name).to eq('first') expect(tags[0].text).to eq('The first parameter.') expect(tags[0].types).to eq(['String']) expect(tags[1].name).to eq('second') expect(tags[1].text).to eq('The second parameter.') expect(tags[1].types).to eq(['Any']) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].name).to be_nil expect(tags[0].text).to eq('Returns nothing.') expect(tags[0].types).to eq(['Undef']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a function with a doc parameter which has a newline between the namespace and the newfunction call' do let(:source) { <<-SOURCE module Puppet::Parser::Functions newfunction(:foo, doc: <<-DOC An example 3.x function. @param [String] first The first parameter. @param second The second parameter. @return [Undef] Returns nothing. DOC ) do |*args| end end SOURCE } it 'should register a function object' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_3X)) expect(object.name).to eq(:foo) expect(object.signature).to eq('foo(String $first, Any $second)') expect(object.parameters).to eq([['first', nil], ['second', nil]]) expect(object.docstring).to eq('An example 3.x function.') expect(object.docstring.tags.size).to eq(4) tags = object.docstring.tags(:param) expect(tags.size).to eq(2) expect(tags[0].name).to eq('first') expect(tags[0].text).to eq('The first parameter.') expect(tags[0].types).to eq(['String']) expect(tags[1].name).to eq('second') expect(tags[1].text).to eq('The second parameter.') expect(tags[1].types).to eq(['Any']) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].name).to be_nil expect(tags[0].text).to eq('Returns nothing.') expect(tags[0].types).to eq(['Undef']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a function with a missing @return tag' do let(:source) { <<-SOURCE Puppet::Parser::Functions.newfunction(:foo, doc: <<-DOC) do |*args| An example 3.x function. @param [String] first The first parameter. @param second The second parameter. DOC end SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):1/).to_stdout_from_any_process end end end describe 'parsing 4.x API functions' do describe 'parsing a function with a missing docstring' do let(:source) { <<-SOURCE Puppet::Functions.create_function(:foo) do end SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet function 'foo' at \(stdin\):1\./).to_stdout_from_any_process end end describe 'parsing a function with a simple docstring' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do end SOURCE } it 'should register a function object' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X)) expect(object.name).to eq(:foo) expect(object.signature).to eq('foo()') expect(object.parameters).to eq([]) expect(object.docstring).to eq('An example 4.x function.') expect(object.docstring.tags.size).to eq(1) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a function without any dispatches' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # @param [Integer] param1 The first parameter. # @param param2 The second parameter. # @param [String] param3 The third parameter. # @return [Undef] Returns nothing. def foo(param1, param2, param3 = nil) end end SOURCE } it 'should register a function object' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X)) expect(object.name).to eq(:foo) expect(object.signature).to eq('foo(Integer $param1, Any $param2, Optional[String] $param3 = undef)') expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', 'undef']]) expect(object.docstring).to eq('An example 4.x function.') expect(object.docstring.tags.size).to eq(5) tags = object.docstring.tags(:param) expect(tags.size).to eq(3) expect(tags[0].name).to eq('param1') expect(tags[0].text).to eq('The first parameter.') expect(tags[0].types).to eq(['Integer']) expect(tags[1].name).to eq('param2') expect(tags[1].text).to eq('The second parameter.') expect(tags[1].types).to eq(['Any']) expect(tags[2].name).to eq('param3') expect(tags[2].text).to eq('The third parameter.') expect(tags[2].types).to eq(['Optional[String]']) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].name).to be_nil expect(tags[0].text).to eq('Returns nothing.') expect(tags[0].types).to eq(['Undef']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a function with a single dispatch' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # @param param1 The first parameter. # @param param2 The second parameter. # @param param3 The third parameter. # @return [Undef] Returns nothing. dispatch :foo do param 'Integer', :param1 param 'Any', :param2 optional_param 'Array[String]', :param3 end def foo(param1, param2, param3 = nil) end end SOURCE } it 'should register a function object without any overload tags' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X)) expect(object.name).to eq(:foo) expect(object.signature).to eq('foo(Integer $param1, Any $param2, Optional[Array[String]] $param3)') expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', nil]]) expect(object.docstring).to eq('An example 4.x function.') expect(object.docstring.tags(:overload).empty?).to be_truthy expect(object.docstring.tags.size).to eq(5) tags = object.docstring.tags(:param) expect(tags.size).to eq(3) expect(tags[0].name).to eq('param1') expect(tags[0].text).to eq('The first parameter.') expect(tags[0].types).to eq(['Integer']) expect(tags[1].name).to eq('param2') expect(tags[1].text).to eq('The second parameter.') expect(tags[1].types).to eq(['Any']) expect(tags[2].name).to eq('param3') expect(tags[2].text).to eq('The third parameter.') expect(tags[2].types).to eq(['Optional[Array[String]]']) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].name).to be_nil expect(tags[0].text).to eq('Returns nothing.') expect(tags[0].types).to eq(['Undef']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a function using only return_type' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # @param param1 The first parameter. # @param param2 The second parameter. # @param param3 The third parameter. dispatch :foo do param 'Integer', :param1 param 'Any', :param2 optional_param 'Array[String]', :param3 return_type 'String' end def foo(param1, param2, param3 = nil) "Bar" end end SOURCE } it 'does not throw an error with no @return' do expect { subject }.not_to raise_error NoMethodError end it 'contains a return data type' do tags = subject.first.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].name).to be_nil expect(tags[0].types).to eq(['String']) end end describe 'parsing a function with various dispatch parameters.' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # @param param1 The first parameter. # @param param2 The second parameter. # @param param3 The third parameter. # @param param4 The fourth parameter. # @return [Undef] Returns nothing. dispatch :foo do param 'String', :param1 required_param 'Integer', :param2 optional_param 'Array', :param3 repeated_param 'String', :param4 end end SOURCE } it 'should register a function object with the expected parameters' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X)) expect(object.name).to eq(:foo) expect(object.signature).to eq('foo(String $param1, Integer $param2, Optional[Array] $param3, String *$param4)') expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', nil], ['*param4', nil]]) expect(object.docstring).to eq('An example 4.x function.') expect(object.docstring.tags(:overload).empty?).to be_truthy expect(object.docstring.tags.size).to eq(6) tags = object.docstring.tags(:param) expect(tags.size).to eq(4) expect(tags[0].name).to eq('param1') expect(tags[0].text).to eq('The first parameter.') expect(tags[0].types).to eq(['String']) expect(tags[1].name).to eq('param2') expect(tags[1].text).to eq('The second parameter.') expect(tags[1].types).to eq(['Integer']) expect(tags[2].name).to eq('param3') expect(tags[2].text).to eq('The third parameter.') expect(tags[2].types).to eq(['Optional[Array]']) expect(tags[3].name).to eq('*param4') expect(tags[3].text).to eq('The fourth parameter.') expect(tags[3].types).to eq(['String']) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].name).to be_nil expect(tags[0].text).to eq('Returns nothing.') expect(tags[0].types).to eq(['Undef']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a function with an optional repeated param.' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # @param param The first parameter. # @return [Undef] Returns nothing. dispatch :foo do optional_repeated_param 'String', :param end end SOURCE } it 'should register a function object with the expected parameters' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X)) expect(object.name).to eq(:foo) expect(object.signature).to eq('foo(Optional[String] *$param)') expect(object.parameters).to eq([['*param', nil]]) expect(object.docstring).to eq('An example 4.x function.') expect(object.docstring.tags(:overload).empty?).to be_truthy expect(object.docstring.tags.size).to eq(3) tags = object.docstring.tags(:param) expect(tags.size).to eq(1) expect(tags[0].name).to eq('*param') expect(tags[0].text).to eq('The first parameter.') expect(tags[0].types).to eq(['Optional[String]']) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].name).to be_nil expect(tags[0].text).to eq('Returns nothing.') expect(tags[0].types).to eq(['Undef']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a function with a block param with one parameter' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # @param a_block The block parameter. # @return [Undef] Returns nothing. dispatch :foo do block_param :a_block end end SOURCE } it 'should register a function object with the expected parameters' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X)) expect(object.name).to eq(:foo) expect(object.signature).to eq('foo(Callable &$a_block)') expect(object.parameters).to eq([['&a_block', nil]]) expect(object.docstring).to eq('An example 4.x function.') expect(object.docstring.tags(:overload).empty?).to be_truthy expect(object.docstring.tags.size).to eq(3) tags = object.docstring.tags(:param) expect(tags.size).to eq(1) expect(tags[0].name).to eq('&a_block') expect(tags[0].text).to eq('The block parameter.') expect(tags[0].types).to eq(['Callable']) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].name).to be_nil expect(tags[0].text).to eq('Returns nothing.') expect(tags[0].types).to eq(['Undef']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a function with a block param with two parameter' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # @param a_block The block parameter. # @return [Undef] Returns nothing. dispatch :foo do optional_block_param 'Callable[String]', :a_block end end SOURCE } it 'should register a function object with the expected parameters' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X)) expect(object.name).to eq(:foo) expect(object.signature).to eq('foo(Optional[Callable[String]] &$a_block)') expect(object.parameters).to eq([['&a_block', nil]]) expect(object.docstring).to eq('An example 4.x function.') expect(object.docstring.tags(:overload).empty?).to be_truthy expect(object.docstring.tags.size).to eq(3) tags = object.docstring.tags(:param) expect(tags.size).to eq(1) expect(tags[0].name).to eq('&a_block') expect(tags[0].text).to eq('The block parameter.') expect(tags[0].types).to eq(['Optional[Callable[String]]']) tags = object.docstring.tags(:return) expect(tags.size).to eq(1) expect(tags[0].name).to be_nil expect(tags[0].text).to eq('Returns nothing.') expect(tags[0].types).to eq(['Undef']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end end describe 'parsing a function with a multiple dispatches' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # The first overload. # @param param1 The first parameter. # @param param2 The second parameter. # @param param3 The third parameter. # @return [Undef] Returns nothing. dispatch :foo do param 'Integer', :param1 param 'Any', :param2 optional_param 'Array[String]', :param3 end # The second overload. # @param param The first parameter. # @param block The block parameter. # @return [String] Returns a string. dispatch :other do param 'Boolean', :param block_param end def foo(param1, param2, param3 = nil) end def other(b) 'lol' end end SOURCE } it 'should register a function object with overload tags' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X)) expect(object.name).to eq(:foo) expect(object.signature).to eq('') expect(object.parameters).to eq([]) expect(object.docstring).to eq('An example 4.x function.') expect(object.docstring.tags(:param).empty?).to be_truthy expect(object.docstring.tags(:return).empty?).to be_truthy expect(object.docstring.tags.size).to eq(3) overloads = object.docstring.tags(:overload) expect(overloads.size).to eq(2) expect(overloads[0]).to be_a(PuppetStrings::Yard::Tags::OverloadTag) expect(overloads[0].docstring).to eq('The first overload.') expect(overloads[0].signature).to eq('foo(Integer $param1, Any $param2, Optional[Array[String]] $param3)') expect(overloads[0].tags.size).to eq(4) tags = overloads[0].tags(:param) expect(tags.size).to eq(3) expect(tags[0].name).to eq('param1') expect(tags[0].text).to eq('The first parameter.') expect(tags[0].types).to eq(['Integer']) expect(tags[1].name).to eq('param2') expect(tags[1].text).to eq('The second parameter.') expect(tags[1].types).to eq(['Any']) expect(tags[2].name).to eq('param3') expect(tags[2].text).to eq('The third parameter.') expect(tags[2].types).to eq(['Optional[Array[String]]']) tags = overloads[0].tags(:return) expect(tags.size).to eq(1) expect(tags[0].name).to be_nil expect(tags[0].text).to eq('Returns nothing.') expect(tags[0].types).to eq(['Undef']) expect(overloads[1]).to be_a(PuppetStrings::Yard::Tags::OverloadTag) expect(overloads[1].docstring).to eq('The second overload.') expect(overloads[1].signature).to eq('foo(Boolean $param, Callable &$block)') expect(overloads[1].tags.size).to eq(3) tags = overloads[1].tags(:param) expect(tags.size).to eq(2) expect(tags[0].name).to eq('param') expect(tags[0].text).to eq('The first parameter.') expect(tags[0].types).to eq(['Boolean']) expect(tags[1].name).to eq('&block') expect(tags[1].text).to eq('The block parameter.') expect(tags[1].types).to eq(['Callable']) tags = overloads[1].tags(:return) expect(tags.size).to eq(1) expect(tags[0].name).to be_nil expect(tags[0].text).to eq('Returns a string.') expect(tags[0].types).to eq(['String']) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') end end describe 'parsing a function with a missing parameter' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # @param missing A missing parameter. # @return [Undef] Returns nothing. dispatch :foo do end end SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'missing' has no matching parameter at \(stdin\):5/).to_stdout_from_any_process end end describe 'parsing a function with a missing @param tag' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # @return [Undef] Returns nothing. dispatch :foo do param 'String', :param1 end end SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: Missing @param tag for parameter 'param1' near \(stdin\):5/).to_stdout_from_any_process end end describe 'parsing a function with a typed @param tag' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # @param [Integer] param1 The first parameter. # @return [Undef] Returns nothing. dispatch :foo do param 'String', :param1 end end SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param1' should not contain a type specification near \(stdin\):6: ignoring in favor of dispatch type information\./).to_stdout_from_any_process end end describe 'parsing a function with a typed @param tag' do let(:source) { <<-SOURCE # An example 4.x function. Puppet::Functions.create_function(:foo) do # @param param1 The first parameter. dispatch :foo do param 'String', :param1 end end SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):4/).to_stdout_from_any_process end end describe 'parsing a function with a root @param tag' do let(:source) { <<-SOURCE # An example 4.x function. # @param param Nope. Puppet::Functions.create_function(:foo) do # @return [Undef] dispatch :foo do end end SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: The docstring for Puppet 4.x function 'foo' contains @param tags near \(stdin\):3: parameter documentation should be made on the dispatch call\./).to_stdout_from_any_process end end describe 'parsing a function with a root @overload tag' do let(:source) { <<-SOURCE # An example 4.x function. # @overload foo Puppet::Functions.create_function(:foo) do # @return [Undef] dispatch :foo do end end SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: The docstring for Puppet 4.x function 'foo' contains @overload tags near \(stdin\):3: overload tags are automatically generated from the dispatch calls\./).to_stdout_from_any_process end end describe 'parsing a function with a root @return tag' do let(:source) { <<-SOURCE # An example 4.x function. # @return [Undef] foo Puppet::Functions.create_function(:foo) do # @return [Undef] dispatch :foo do end end SOURCE } it 'should output a warning' do expect{ subject }.to output(/\[warn\]: The docstring for Puppet 4.x function 'foo' contains @return tags near \(stdin\):3: return value documentation should be made on the dispatch call\./).to_stdout_from_any_process end end describe 'parsing a function with a summary' do context 'when the summary has fewer than 140 characters' do let(:source) { <<-SOURCE # An example 4.x function. # @summary A short summary. Puppet::Functions.create_function(:foo) do # @return [Undef] dispatch :foo do end end SOURCE } it 'should parse the summary' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) summary = subject.first.tags(:summary) expect(summary.first.text).to eq('A short summary.') end end context 'when the summary has more than 140 characters' do let(:source) { <<-SOURCE # An example 4.x function. # @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!! Puppet::Functions.create_function(:foo) do # @return [Undef] dispatch :foo do end end SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_function 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process end end end end puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb000066400000000000000000000106741331446220200320460ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard' describe PuppetStrings::Yard::Handlers::Ruby::ProviderHandler do subject { YARD::Parser::SourceParser.parse_string(source, :ruby) YARD::Registry.all(:puppet_provider) } describe 'parsing source without a provider definition' do let(:source) { 'puts "hi"' } it 'no providers should be in the registry' do expect(subject.empty?).to eq(true) end end describe 'parsing a provider with a missing description' do let(:source) { <<-SOURCE Puppet::Type.type(:custom).provide :linux do end SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: Missing a description for Puppet provider 'linux' \(resource type 'custom'\) at \(stdin\):1\./).to_stdout_from_any_process end end describe 'parsing a provider with an invalid docstring assignment' do let(:source) { <<-SOURCE Puppet::Type.type(:custom).provide :linux do @doc = 123 end SOURCE } it 'should log an error' do expect { subject }.to output(/Failed to parse docstring/).to_stdout_from_any_process end end describe 'parsing a provider with a valid docstring assignment' do let(:source) { <<-SOURCE Puppet::Type.type(:custom).provide :linux do @doc = 'An example provider on Linux.' end SOURCE } it 'should correctly detect the docstring' do expect(subject.size).to eq(1) object = subject.first expect(object.docstring).to eq('An example provider on Linux.') end end describe 'parsing a provider with a docstring which uses ruby `%Q` notation' do let(:source) { <<-'SOURCE' Puppet::Type.type(:custom).provide :linux do test = 'hello world!' desc %Q{This is a multi-line doc in %Q with #{test}} end SOURCE } it 'should strip the `%Q{}` and render the interpolation expression literally' do expect(subject.size).to eq(1) object = subject.first expect(object.docstring).to eq("This is a multi-line\ndoc in %Q with \#{test}") end end describe 'parsing a provider definition' do let(:source) { <<-SOURCE Puppet::Type.type(:custom).provide :linux do desc 'An example provider on Linux.' confine kernel: 'Linux' confine osfamily: 'RedHat' defaultfor :kernel => 'Linux' defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7' has_feature :implements_some_feature has_feature :some_other_feature commands foo: '/usr/bin/foo' end SOURCE } it 'should register a provider object' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Provider) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Providers.instance('custom')) expect(object.name).to eq(:linux) expect(object.type_name).to eq('custom') expect(object.docstring).to eq('An example provider on Linux.') expect(object.docstring.tags.size).to eq(1) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') expect(object.confines).to eq({ 'kernel' => 'Linux', 'osfamily' => 'RedHat'}) expect(object.defaults).to eq([[["kernel", "Linux"]], [["osfamily", "RedHat"], ["operatingsystemmajrelease", "7"]]]) expect(object.features).to eq(['implements_some_feature', 'some_other_feature']) expect(object.commands).to eq({'foo' => '/usr/bin/foo'}) end end describe 'parsing a provider with a summary' do context 'when the summary has fewer than 140 characters' do let(:source) { <<-SOURCE Puppet::Type.type(:custom).provide :linux do @doc = '@summary A short summary.' end SOURCE } it 'should parse the summary' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) summary = subject.first.tags(:summary) expect(summary.first.text).to eq('A short summary.') end end context 'when the summary has more than 140 characters' do let(:source) { <<-SOURCE Puppet::Type.type(:custom).provide :linux do @doc = '@summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!' end SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_provider 'linux' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process end end end end puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/ruby/rsapi_handler_spec.rb000066400000000000000000000176111331446220200313300ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard' describe PuppetStrings::Yard::Handlers::Ruby::RsapiHandler do subject { YARD::Parser::SourceParser.parse_string(source, :ruby) YARD::Registry.all(:puppet_type) } describe 'parsing source without a type definition' do let(:source) { 'puts "hi"' } it 'no types should be in the registry' do expect(subject.empty?).to eq(true) end end describe 'parsing a type with a missing description' do let(:source) { <<-SOURCE Puppet::ResourceApi.register_type( name: 'database' ) SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: Missing a description for Puppet resource type 'database' at \(stdin\):1\./).to_stdout_from_any_process end end describe 'parsing a type with a valid docstring assignment' do let(:source) { <<-SOURCE Puppet::ResourceApi.register_type( name: 'database', docs: 'An example database server resource type.', ) SOURCE } it 'should correctly detect the docstring' do expect(subject.size).to eq(1) object = subject.first expect(object.docstring).to eq('An example database server resource type.') end end describe 'parsing a type with a docstring which uses ruby `%Q` notation' do let(:source) { <<-'SOURCE' test = 'hello world!' Puppet::ResourceApi.register_type( name: 'database', docs: %Q{This is a multi-line doc in %Q with #{test}}, ) SOURCE } it 'should strip the `%Q{}` and render the interpolation expression literally' do expect(subject.size).to eq(1) object = subject.first expect(object.docstring).to eq("This is a multi-line\ndoc in %Q with \#{test}") end end describe 'parsing a type definition' do let(:source) { <<-SOURCE # @!puppet.type.param [value1, value2] dynamic_param Documentation for a dynamic parameter. # @!puppet.type.property [foo, bar] dynamic_prop Documentation for a dynamic property. Puppet::ResourceApi.register_type( name: 'database', docs: 'An example database server resource type.', features: ['remote-resource'], attributes: { ensure: { type: 'Enum[present, absent, up, down]', desc: 'What state the database should be in.', default: 'up', }, address: { type: 'String', desc: 'The database server name.', behaviour: :namevar, }, encrypt: { type: 'Boolean', desc: 'Whether or not to encrypt the database.', default: false, behaviour: :parameter, }, encryption_key: { type: 'Optional[String]', desc: 'The encryption key to use.', behaviour: :parameter, }, backup: { type: 'Enum[daily, monthly, never]', desc: 'How often to backup the database.', default: 'never', behaviour: :parameter, }, file: { type: 'String', desc: 'The database file to use.', }, log_level: { type: 'Enum[debug, warn, error]', desc: 'The log level to use.', default: 'warn', }, }, ) SOURCE } it 'should register a type object' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Type) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Types.instance) expect(object.name).to eq(:database) expect(object.docstring).to eq('An example database server resource type.') expect(object.docstring.tags.size).to eq(1) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') expect(object.properties.map(&:name)).to eq(['dynamic_prop', 'ensure', 'file', 'log_level']) expect(object.properties.size).to eq(4) expect(object.properties[0].name).to eq('dynamic_prop') expect(object.properties[0].docstring).to eq('Documentation for a dynamic property.') expect(object.properties[0].isnamevar).to eq(false) expect(object.properties[0].values).to eq(%w(foo bar)) expect(object.properties[1].name).to eq('ensure') expect(object.properties[1].docstring).to eq('What state the database should be in.') expect(object.properties[1].isnamevar).to eq(false) expect(object.properties[1].default).to eq('up') expect(object.properties[1].data_type).to eq('Enum[present, absent, up, down]') expect(object.properties[1].aliases).to eq({}) expect(object.properties[2].name).to eq('file') expect(object.properties[2].docstring).to eq('The database file to use.') expect(object.properties[2].isnamevar).to eq(false) expect(object.properties[2].default).to be_nil expect(object.properties[2].data_type).to eq('String') expect(object.properties[2].aliases).to eq({}) expect(object.properties[3].name).to eq('log_level') expect(object.properties[3].docstring).to eq('The log level to use.') expect(object.properties[3].isnamevar).to eq(false) expect(object.properties[3].default).to eq('warn') expect(object.properties[3].data_type).to eq('Enum[debug, warn, error]') expect(object.properties[3].aliases).to eq({}) expect(object.parameters.size).to eq(5) expect(object.parameters[0].name).to eq('dynamic_param') expect(object.parameters[0].docstring).to eq('Documentation for a dynamic parameter.') expect(object.parameters[0].isnamevar).to eq(false) expect(object.parameters[0].values).to eq(%w(value1 value2)) expect(object.parameters[1].name).to eq('address') expect(object.parameters[1].docstring).to eq('The database server name.') expect(object.parameters[1].isnamevar).to eq(true) expect(object.parameters[1].default).to be_nil expect(object.parameters[1].data_type).to eq('String') expect(object.parameters[1].aliases).to eq({}) expect(object.parameters[2].name).to eq('encrypt') expect(object.parameters[2].docstring).to eq('Whether or not to encrypt the database.') expect(object.parameters[2].isnamevar).to eq(false) expect(object.parameters[2].default).to eq(false) expect(object.parameters[2].data_type).to eq("Boolean") expect(object.parameters[2].aliases).to eq({}) expect(object.parameters[3].name).to eq('encryption_key') expect(object.parameters[3].docstring).to eq('The encryption key to use.') expect(object.parameters[3].isnamevar).to eq(false) expect(object.parameters[3].default).to be_nil expect(object.parameters[3].data_type).to eq("Optional[String]") expect(object.parameters[3].aliases).to eq({}) expect(object.parameters[4].name).to eq('backup') expect(object.parameters[4].docstring).to eq('How often to backup the database.') expect(object.parameters[4].isnamevar).to eq(false) expect(object.parameters[4].default).to eq('never') expect(object.parameters[4].data_type).to eq("Enum[daily, monthly, never]") end end describe 'parsing a type with a summary' do context 'when the summary has fewer than 140 characters' do let(:source) { <<-SOURCE Puppet::ResourceApi.register_type( name: 'database', docs: '@summary A short summary.', ) SOURCE } it 'should parse the summary' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) summary = subject.first.tags(:summary) expect(summary.first.text).to eq('A short summary.') end end context 'when the summary has more than 140 characters' do let(:source) { <<-SOURCE Puppet::ResourceApi.register_type( name: 'database', docs: '@summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!', ) SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_type 'database' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process end end end end puppet-strings-2.1.0/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb000066400000000000000000000231541331446220200311720ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard' describe PuppetStrings::Yard::Handlers::Ruby::TypeHandler do subject { YARD::Parser::SourceParser.parse_string(source, :ruby) YARD::Registry.all(:puppet_type) } describe 'parsing source without a type definition' do let(:source) { 'puts "hi"' } it 'no types should be in the registry' do expect(subject.empty?).to eq(true) end end describe 'parsing a type with a missing description' do let(:source) { <<-SOURCE Puppet::Type.newtype(:database) do end SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: Missing a description for Puppet resource type 'database' at \(stdin\):1\./).to_stdout_from_any_process end end describe 'parsing a type with an invalid docstring assignment' do let(:source) { <<-SOURCE Puppet::Type.newtype(:database) do @doc = 123 end SOURCE } it 'should log an error' do expect { subject }.to output(/Failed to parse docstring/).to_stdout_from_any_process end end describe 'parsing a type with a valid docstring assignment' do let(:source) { <<-SOURCE Puppet::Type.newtype(:database) do @doc = 'An example database server resource type.' end SOURCE } it 'should correctly detect the docstring' do expect(subject.size).to eq(1) object = subject.first expect(object.docstring).to eq('An example database server resource type.') end end describe 'parsing a type with a docstring which uses ruby `%Q` notation' do let(:source) { <<-'SOURCE' Puppet::Type.newtype(:database) do test = 'hello world!' desc %Q{This is a multi-line doc in %Q with #{test}} end SOURCE } it 'should strip the `%Q{}` and render the interpolation expression literally' do expect(subject.size).to eq(1) object = subject.first expect(object.docstring).to eq("This is a multi-line\ndoc in %Q with \#{test}") end end describe 'parsing a type definition' do let(:source) { <<-SOURCE # @!puppet.type.param [value1, value2] dynamic_param Documentation for a dynamic parameter. # @!puppet.type.property [foo, bar] dynamic_prop Documentation for a dynamic property. Puppet::Type.newtype(:database) do desc 'An example database server resource type.' feature :encryption, 'The provider supports encryption.', methods: [:encrypt] feature :magic, 'The feature docstring should have whitespace and newlines stripped out.' ensurable do desc 'What state the database should be in.' defaultvalues aliasvalue(:up, :present) aliasvalue(:down, :absent) defaultto :up end newparam(:address) do isnamevar desc 'The database server name.' end newparam(:encryption_key, required_features: :encryption) do desc 'The encryption key to use.' end newparam(:encrypt, :parent => Puppet::Parameter::Boolean) do desc 'Whether or not to encrypt the database.' defaultto false end newparam(:backup) do desc 'How often to backup the database.' defaultto :never newvalues(:daily, :monthly, :never) end newproperty(:file) do desc 'The database file to use.' end newproperty(:log_level) do desc 'The log level to use.' newvalue(:debug) newvalue(:warn) newvalue(:error) defaultto 'warn' end end SOURCE } it 'should register a type object' do expect(subject.size).to eq(1) object = subject.first expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Type) expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Types.instance) expect(object.name).to eq(:database) expect(object.docstring).to eq('An example database server resource type.') expect(object.docstring.tags.size).to eq(1) tags = object.docstring.tags(:api) expect(tags.size).to eq(1) expect(tags[0].text).to eq('public') expect(object.properties.size).to eq(4) expect(object.properties[0].name).to eq('dynamic_prop') expect(object.properties[0].docstring).to eq('Documentation for a dynamic property.') expect(object.properties[0].isnamevar).to eq(false) expect(object.properties[0].values).to eq(%w(foo bar)) expect(object.properties[1].name).to eq('ensure') expect(object.properties[1].docstring).to eq('What state the database should be in.') expect(object.properties[1].isnamevar).to eq(false) expect(object.properties[1].default).to eq('up') expect(object.properties[1].values).to eq(%w(present absent up down)) expect(object.properties[1].aliases).to eq({ 'down' => 'absent', 'up' => 'present' }) expect(object.properties[2].name).to eq('file') expect(object.properties[2].docstring).to eq('The database file to use.') expect(object.properties[2].isnamevar).to eq(false) expect(object.properties[2].default).to be_nil expect(object.properties[2].values).to eq([]) expect(object.properties[2].aliases).to eq({}) expect(object.properties[3].name).to eq('log_level') expect(object.properties[3].docstring).to eq('The log level to use.') expect(object.properties[3].isnamevar).to eq(false) expect(object.properties[3].default).to eq('warn') expect(object.properties[3].values).to eq(%w(debug warn error)) expect(object.properties[3].aliases).to eq({}) expect(object.parameters.size).to eq(5) expect(object.parameters[0].name).to eq('dynamic_param') expect(object.parameters[0].docstring).to eq('Documentation for a dynamic parameter.') expect(object.parameters[0].isnamevar).to eq(false) expect(object.parameters[0].values).to eq(%w(value1 value2)) expect(object.parameters[1].name).to eq('address') expect(object.parameters[1].docstring).to eq('The database server name.') expect(object.parameters[1].isnamevar).to eq(true) expect(object.parameters[1].default).to be_nil expect(object.parameters[1].values).to eq([]) expect(object.parameters[1].aliases).to eq({}) expect(object.parameters[2].name).to eq('encryption_key') expect(object.parameters[2].docstring).to eq('The encryption key to use.') expect(object.parameters[2].isnamevar).to eq(false) expect(object.parameters[2].default).to be_nil expect(object.parameters[2].values).to eq([]) expect(object.parameters[2].aliases).to eq({}) expect(object.parameters[3].name).to eq('encrypt') expect(object.parameters[3].docstring).to eq('Whether or not to encrypt the database.') expect(object.parameters[3].isnamevar).to eq(false) expect(object.parameters[3].default).to eq('false') expect(object.parameters[3].values).to eq(%w(true false yes no)) expect(object.parameters[3].aliases).to eq({}) expect(object.parameters[4].name).to eq('backup') expect(object.parameters[4].docstring).to eq('How often to backup the database.') expect(object.parameters[4].isnamevar).to eq(false) expect(object.parameters[4].default).to eq('never') expect(object.parameters[4].values).to eq(%w(daily monthly never)) expect(object.features.size).to eq(2) expect(object.features[0].name).to eq('encryption') expect(object.features[0].docstring).to eq('The provider supports encryption.') expect(object.features[1].name).to eq('magic') expect(object.features[1].docstring).to eq('The feature docstring should have whitespace and newlines stripped out.') end end describe 'parsing an ensurable type with default ensure values' do let(:source) { <<-SOURCE Puppet::Type.newtype(:database) do desc 'An example database server resource type.' ensurable end SOURCE } it 'should register a type object with default ensure values' do expect(subject.size).to eq(1) object = subject.first expect(object.properties[0].name).to eq('ensure') expect(object.properties[0].docstring).to eq('The basic property that the resource should be in.') expect(object.properties[0].default).to eq('present') expect(object.properties[0].values).to eq(%w(present absent)) end end describe 'parsing a type with a parameter with the name of "name"' do let(:source) { <<-SOURCE Puppet::Type.newtype(:database) do desc 'An example database server resource type.' newparam(:name) do desc 'The database server name.' end end SOURCE } it 'should register a type object with the "name" parameter as the namevar' do expect(subject.size).to eq(1) object = subject.first expect(object.parameters.size).to eq(1) expect(object.parameters[0].name).to eq('name') expect(object.parameters[0].isnamevar).to eq(true) end end describe 'parsing a type with a summary' do context 'when the summary has fewer than 140 characters' do let(:source) { <<-SOURCE Puppet::Type.newtype(:database) do @doc = '@summary A short summary.' end SOURCE } it 'should parse the summary' do expect{ subject }.to output('').to_stdout_from_any_process expect(subject.size).to eq(1) summary = subject.first.tags(:summary) expect(summary.first.text).to eq('A short summary.') end end context 'when the summary has more than 140 characters' do let(:source) { <<-SOURCE Puppet::Type.newtype(:database) do @doc = '@summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!' end SOURCE } it 'should log a warning' do expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_type 'database' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process end end end end puppet-strings-2.1.0/spec/unit/puppet-strings/yard/parsers/000077500000000000000000000000001331446220200240465ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/yard/parsers/json/000077500000000000000000000000001331446220200250175ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/yard/parsers/json/parser_spec.rb000066400000000000000000000034241331446220200276550ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard' describe PuppetStrings::Yard::Parsers::JSON::Parser do subject { PuppetStrings::Yard::Parsers::JSON::Parser.new(source, file) } let(:file) { 'test.json' } describe 'initialization of the parser' do let(:source) { 'notice hi' } it 'should store the original source' do expect(subject.source).to eq(source) end it 'should store the original file name' do expect(subject.file).to eq(file) end it 'should have no relevant statements' do subject.parse expect(subject.enumerator.empty?).to be_truthy end end describe 'parsing invalid JSON' do let(:source) { < 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 puppet-strings-2.1.0/spec/unit/puppet-strings/yard/parsers/puppet/000077500000000000000000000000001331446220200253635ustar00rootroot00000000000000puppet-strings-2.1.0/spec/unit/puppet-strings/yard/parsers/puppet/parser_spec.rb000066400000000000000000000163401331446220200302220ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard' describe PuppetStrings::Yard::Parsers::Puppet::Parser do subject { PuppetStrings::Yard::Parsers::Puppet::Parser.new(source, file) } let(:file) { 'test.pp' } describe 'initialization of the parser' do let(:source) { 'notice hi' } it 'should store the original source' do expect(subject.source).to eq(source) end it 'should store the original file name' do expect(subject.file).to eq(file) end it 'should have no relevant statements' do subject.parse expect(subject.enumerator.empty?).to be_truthy end end describe 'parsing invalid Puppet source code' do let(:source) { < present } } SOURCE } it 'should only return the class statement' do subject.parse expect(subject.enumerator.size).to eq(1) statement = subject.enumerator.first expect(statement).to be_a(PuppetStrings::Yard::Parsers::Puppet::ClassStatement) expect(statement.source).to eq("class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {\n file { '/tmp/foo':\n ensure => present\n }\n}") expect(statement.file).to eq(file) expect(statement.line).to eq(6) expect(statement.docstring).to eq('A simple foo class.') expect(statement.name).to eq('foo') expect(statement.parent_class).to eq('foo::bar') expect(statement.parameters.size).to eq(3) expect(statement.parameters[0].name).to eq('param1') expect(statement.parameters[0].type).to eq('Integer') expect(statement.parameters[0].value).to be_nil expect(statement.parameters[1].name).to eq('param2') expect(statement.parameters[1].type).to be_nil expect(statement.parameters[1].value).to be_nil expect(statement.parameters[2].name).to eq('param3') expect(statement.parameters[2].type).to eq('String') expect(statement.parameters[2].value).to eq('hi') end end describe 'parsing nested class definitions' do let(:source) { < present } } SOURCE } it 'should parse the defined type statement' do subject.parse expect(subject.enumerator.size).to eq(1) statement = subject.enumerator.first expect(statement).to be_a(PuppetStrings::Yard::Parsers::Puppet::DefinedTypeStatement) expect(statement.name).to eq('foo') expect(statement.source).to eq("define foo(Integer $param1, $param2, String $param3 = hi) {\n file { '/tmp/foo':\n ensure => present\n }\n}") expect(statement.file).to eq(file) expect(statement.line).to eq(6) expect(statement.docstring).to eq('A simple foo defined type.') expect(statement.parameters.size).to eq(3) expect(statement.parameters[0].name).to eq('param1') expect(statement.parameters[0].type).to eq('Integer') expect(statement.parameters[0].value).to be_nil expect(statement.parameters[1].name).to eq('param2') expect(statement.parameters[1].type).to be_nil expect(statement.parameters[1].value).to be_nil expect(statement.parameters[2].name).to eq('param3') expect(statement.parameters[2].type).to eq('String') expect(statement.parameters[2].value).to eq('hi') end end describe 'parsing puppet functions', if: TEST_PUPPET_FUNCTIONS do let(:source) { <> String { notice world } SOURCE } it 'should parse the puppet function statement' do subject.parse expect(subject.enumerator.size).to eq(1) statement = subject.enumerator.first expect(statement).to be_a(PuppetStrings::Yard::Parsers::Puppet::FunctionStatement) expect(statement.type).to eq('String') end end describe 'parsing puppet functions with complex return types in defintion', if: TEST_FUNCTION_RETURN_TYPE do let(:source) { <> Struct[{'a' => Integer[1, 10]}] { notice world } SOURCE } it 'should parse the puppet function statement' do subject.parse expect(subject.enumerator.size).to eq(1) statement = subject.enumerator.first expect(statement).to be_a(PuppetStrings::Yard::Parsers::Puppet::FunctionStatement) expect(statement.type).to eq("Struct\[{'a' => Integer[1, 10]}\]") end end end puppet-strings-2.1.0/spec/unit/puppet-strings/yard/util_spec.rb000066400000000000000000000030271331446220200247050ustar00rootroot00000000000000require 'spec_helper' require 'puppet-strings/yard' describe PuppetStrings::Yard::Util do subject {PuppetStrings::Yard::Util} describe 'scrub_string' do it 'should remove `%Q` and its brackets from a string ' do str = "%Q{this is a test string}" expect(subject.scrub_string(str)).to eq('this is a test string') end it 'should remove `%q` and its brackets from a string' do str = "%q{this is a test string}" expect(subject.scrub_string(str)).to eq('this is a test string') end it 'should not affect newlines when %Q notation is used' do str = <<-STR %Q{this is a test string} STR expect(subject.scrub_string(str)).to eq("this is\na test string") end it 'should not affect a string which does not use %Q notation' do str = "this is a test string" expect(subject.scrub_string(str)).to eq('this is a test string') end end describe 'github_to_yard_links' do it 'converts a link correctly' do str = '' expect(subject.github_to_yard_links(str)).to eq('') end it 'leaves other links with hashes alone' do str = '' expect(subject.github_to_yard_links(str)).to eq(str) end it 'leaves plain text alone' do str = ' module-description' expect(subject.github_to_yard_links(str)).to eq(' module-description') end end end