Jira (PDOC-225) Data in Modules?
Title: Message Title
Henrik Lindberg commented on PDOC-225
Re: Data in Modules?
R.I.Pienaar Since the information after the bracketed type for a param is completely ignored by yard itself, you can put anything there. What Strings could do is to have a convention that for example a hash in puppet language notation inside parentheses following the bracket would be displayed a certain way. That would be kind of like additional meta tags (but those are lot harder to introduce). Something like:
@param foo [Hash] (lookup_options => { merge => 'deep' }) foo is a param for foo details...
You would have to do some static declaration like that as the information can not be obtained statically from hiera because the effective lookup_options may depend on values at runtime. Since that is the case, maybe it is just as good to spell it out in the text in free form - so if code does something fancy you can just say so?
@param foo [Hash] (* deep merge) foo is a param for foo details
@param bar [Hash] (* deep merge if bar_deep is true) bar is a param for bar details
Add Comment
Jira (PDOC-225) Data in Modules?
Title: Message Title R.I.Pienaar commented on PDOC-225 Re: Data in Modules? I have no ideas on how to do this with yard but details of the module supplied lookup options (merge strategies) would be amazing. Add Comment This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93) -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-bugs+unsubscr...@googlegroups.com. To post to this group, send email to puppet-bugs@googlegroups.com. Visit this group at https://groups.google.com/group/puppet-bugs. For more options, visit https://groups.google.com/d/optout.
Jira (PDOC-225) Data in Modules?
Title: Message Title
Henrik Lindberg commented on PDOC-225
Re: Data in Modules?
The yard syntax for parameter default could perhaps be used for this. The module author knows a parameter has a default value in hiera data in the module and could note that with some notation - yard does not have semantics for default for @param tags, but for @option it is suggested to place a default value in parentheses. We could use the same for @param. The convention could be () or say (module data) where the first documents a literal value for example (42), and the second that there will be a lookup and that the value is in the module's data (if possible user could also state what the default in module data is - if it always resolves to the same value - if so use something like (module data 42). Could also use (*) or somesuch to indicate "default in module data", but you have to know the notation to understand that.
# @param port [Integer] (*) the port to use
class myclass(Integer $port) { }
Nothing of the above requires any changes to code, only that a convention is established.
Add Comment
This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93)
Jira (PDOC-225) Data in Modules?
Title: Message Title Eric Putnam created an issue Puppet Strings / PDOC-225 Data in Modules? Issue Type: Task Assignee: Unassigned Created: 2018/03/02 1:41 PM Priority: Normal Reporter: Eric Putnam Would like to see documentation created for types, providers, facts and the hiera levels when using data in modules. - Garrett Honeycutt I agree with this but so much of data in modules is dependent on compile time material that it would be impossible to do anything except for defaults (which should be done). However, we do need some way to indicate that a parameter is in module data instead of 'required' that doesn't require keeping a manual mapping (because automation is good, right?) - Trevor Vaughn Add Comment
