Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward

[Nicholas Fagerlund (JIRA)]

Title: Message Title

Nicholas Fagerlund commented on PDOC-125   Re: JSON: Splitting function signatures into two places is awkward Wait, I forgot something: Parameter descriptions are attached to signatures, and each signature can also have a description as well. This isn't widely used in the current code base, but here's an example: { "name": "lookup", "file": "/Users/nick/RubymineProjects/puppet-docs/vendor/puppet/lib/puppet/functions/lookup.rb", "line": 124, "type": "ruby4x", "docstring": { "text": "Uses the Puppet lookup system to retrieve a value for a given key. By default,\nthis returns the first value found (and fails compilation if no values are\navailable), but you can configure it to merge multiple values into one, fail\ngracefully, and more.\n\nWhen looking up a key, Puppet will search up to three tiers of data, in the\nfollowing order:\n\n1. Hiera.\n2. The current environment's data provider.\n3. The indicated module's data provider, if the key is of the form\n `<MODULE NAME>::<SOMETHING>`.\n\n#### Arguments\n\nYou must provide the name of a key to look up, and can optionally provide other\narguments. You can combine these arguments in the following ways:\n\n* `lookup( <NAME>, [<VALUE TYPE>], [<MERGE BEHAVIOR>], [<DEFAULT VALUE>] )`\n* `lookup( [<NAME>], <OPTIONS HASH> )`\n* `lookup( as above ) |$key| { # lambda returns a default value }`\n\nArguments in `[square brackets]` are optional.\n\nThe arguments accepted by `lookup` are as follows:\n\n1. `<NAME>` (string or array) --- The name of the key to look up.\n * This can also be an array of keys. If Puppet doesn't find anything for the\n first key, it will try again with the subsequent ones, only resorting to a\n default value if none of them succeed.\n2. `<VALUE TYPE>` (data type) --- A\n[data type](https://docs.puppetlabs.com/puppet/latest/reference/lang_data_type.html)\nthat must match the retrieved value; if not, the lookup (and catalog\ncompilation) will fail. Defaults to `Data` (accepts any normal value).\n3. `<MERGE BEHAVIOR>` (string or hash; see **\"Merge Behaviors\"** below) ---\nWhether (and how) to combine multiple values. If present, this overrides any\nmerge behavior specified in the data sources. Defaults to no value; Puppet will\nuse merge behavior from the data sources if present, and will otherwise do a\nfirst-found lookup.\n4. `<DEFAULT VALUE>` (any normal value) --- If present, `lookup` returns this\nwhen it can't find a normal value. Default values are never merged with found\nvalues. Like a normal value, the default must match the value type. Defaults to\nno value; if Puppet can't find a normal value, the lookup (and compilation) will\nfail.\n5. `<OPTIONS HASH>` (hash) --- Alternate way to set the arguments above, plus\nsome less-common extra options. If you pass an options hash, you can't combine\nit with any regular arguments (except `<NAME>`). An options hash can have the\nfollowing keys:\n * `'name'` --- Same as `<NAME>` (argument 1). You can pass this as an\n argument or in the hash, but not both.\n * `'value_type'` --- Same as `<VALUE TYPE>` (argument 2).\n * `'merge'` --- Same as `<MERGE BEHAVIOR>` (argument 3).\n * `'default_value'` --- Same as `<DEFAULT VALUE>` (argument 4).\n * `'default_values_hash'` (hash) --- A hash of lookup keys and default\n values. If Puppet can't find a normal value, it will check this hash for the\n requested key before giving up. You can combine this with `default_value` or\n a lambda, which will be used if the key isn't present in this hash. Defaults\n to an empty hash.\n * `'override'` (hash) --- A hash of lookup keys and override values. Puppet\n will check for the requested key in the overrides hash _first;_ if found, it\n returns that value as the _final_ value, ignoring merge behavior. Defaults\n to an empty hash.\n\nFinally, `lookup` can take a lambda, which must accept a single parameter.\nThis is yet another way to set a default value for the lookup; if no results are\nfound, Puppet will pass the requested key to the lambda and use its result as\nthe default value.\n\n#### Merge Behaviors\n\nPuppet lookup uses a hierarchy of data sources, and a given key might have\nvalues in multiple sources. By default, Puppet returns the first value it finds,\nbut it can also continue searching and merge all the values together.\n\n> **Note:** Data sources can use the special `lookup_options` metadata key to\nrequest a specific merge behavior for a key. The `lookup` function will use that\nrequested behavior unless you explicitly specify one.\n\nThe valid merge behaviors are:\n\n* `'first'` --- Returns the first value found, with no merging. Puppet lookup's\ndefault behavior.\n* `'unique'` (called \"array merge\" in classic Hiera) --- Combines any number of\narrays and scalar values to return a merged, flattened array with all duplicate\nvalues removed. The lookup will fail if any hash values are found.\n* `'hash'` --- Combines the keys and values of any number of hashes to return a\nmerged hash. If the same key exists in multiple source hashes, Puppet will use\nthe value from the highest-priority data source; it won't recursively merge the\nvalues.\n* `'deep'` --- Combines the keys and values of any number of hashes to return a\nmerged hash. If the same key exists in multiple source hashes, Puppet will\nrecursively merge hash or array values (with duplicate values removed from\narrays). For conflicting scalar values, the highest-priority value will win.\n* `{'strategy' => 'first|unique|hash'}` --- Same as the string versions of these\nmerge behaviors.\n* `{'strategy' => 'deep', <DEEP OPTION> => <VALUE>, ...}` --- Same as `'deep'`,\nbut can adjust the merge with additional options. The available options are:\n * `'knockout_prefix'` (string or undef) --- A string prefix to indicate a\n value should be _removed_ from the final result. Defaults to `undef`, which\n disables this feature.\n * `'sort_merged_arrays'` (boolean) --- Whether to sort all arrays that are\n merged together. Defaults to `false`.\n * `'merge_hash_arrays'` (boolean) --- Whether to merge hashes within arrays.\n Defaults to `false`.", "tags": [ { "tag_name": "example", "text": "\nlookup('ntp::service_name')", "name": "Look up a key and return the first value found" }, { "tag_name": "example", "text": "\nlookup('classes', Array[String], 'unique').include", "name": "Do a unique merge lookup of class names, then add all of those classes to the catalog (like `hiera_include`)" }, { "tag_name": "example", "text": "\nlookup( { 'name' => 'users',\n 'merge' => {\n 'strategy' => 'deep',\n 'knockout_prefix' => '--',\n },\n})", "name": "Do a deep hash merge lookup of user data, but let higher priority sources remove values by prefixing them with `--`" }, { "tag_name": "since", "text": "4.0.0" }, { "tag_name": "overload", "signature": "lookup(NameType $name, Optional[ValueType] $value_type, Optional[MergeType] $merge)", "name": "lookup" }, { "tag_name": "overload", "signature": "lookup(NameType $name, Optional[ValueType] $value_type, Optional[MergeType] $merge, DefaultValueType $default_value)", "name": "lookup" }, { "tag_name": "overload", "signature": "lookup(NameType $name, Optional[ValueType] $value_type, Optional[MergeType] $merge, BlockType &$block)", "name": "lookup" }, { "tag_name": "overload", "signature": "lookup(OptionsWithName $options_hash, Optional[BlockType] &$block)", "docstring": { "text": "Lookup without name. Name then becomes a required entry in the options hash", "tags": [ { "tag_name": "param", "text": "", "types": [ "OptionsWithName" ], "name": "options_hash" }, { "tag_name": "param", "text": "", "types": [ "Optional[BlockType]" ], "name": "&block" }, { "tag_name": "return", "text": "", "types": [ "Any" ] } ] }, "name": "lookup" }, { "tag_name": "overload", "signature": "lookup(Variant[String,Array[String]] $name, OptionsWithoutName $options_hash, Optional[BlockType] &$block)", "docstring": { "text": "Lookup using name and options hash.", "tags": [ { "tag_name": "param", "text": "", "types": [ "Variant[String,Array[String]]" ], "name": "name" }, { "tag_name": "param", "text": "", "types": [ "OptionsWithoutName" ], "name": "options_hash" }, { "tag_name": "param", "text": "", "types": [ "Optional[BlockType]" ], "name": "&block" }, { "tag_name": "return", "text": "", "types": [ "Any" ] } ] }, "name": "lookup" } ] }, "source": "Puppet::Functions.create_function(:lookup, Puppet::Functions::InternalFunction) do\n\n local_types do\n type 'NameType = Variant[String, Array[String]]'\n type 'ValueType = Type'\n type 'DefaultValueType = Any'\n type 'MergeType = Variant[String[1], Hash[String, Scalar]]'\n type 'BlockType = Callable[NameType]'\n type \"OptionsWithName = Struct[{\\\n name => NameType,\\\n value_type => Optional[ValueType],\\\n default_value => Optional[DefaultValueType],\\\n override => Optional[Hash[String,Any]],\\\n default_values_hash => Optional[Hash[String,Any]],\\\n merge => Optional[MergeType]\\\n }]\"\n type \"OptionsWithoutName = Struct[{\\\n value_type => Optional[ValueType],\\\n default_value => Optional[DefaultValueType],\\\n override => Optional[Hash[String,Any]],\\\n default_values_hash => Optional[Hash[String,Any]],\\\n merge => Optional[MergeType]\\\n }]\"\n\n end\n\n dispatch :lookup_1 do\n scope_param\n param 'NameType', :name\n optional_param 'ValueType', :value_type\n optional_param 'MergeType', :merge\n end\n\n dispatch :lookup_2 do\n scope_param\n param 'NameType', :name\n param 'Optional[ValueType]', :value_type\n param 'Optional[MergeType]', :merge\n param 'DefaultValueType', :default_value\n end\n\n dispatch :lookup_3 do\n scope_param\n param 'NameType', :name\n optional_param 'ValueType', :value_type\n optional_param 'MergeType', :merge\n required_block_param 'BlockType', :block\n end\n\n # Lookup without name. Name then becomes a required entry in the options hash\n dispatch :lookup_4 do\n scope_param\n param 'OptionsWithName', :options_hash\n optional_block_param 'BlockType', :block\n end\n\n # Lookup using name and options hash.\n dispatch :lookup_5 do\n scope_param\n param 'Variant[String,Array[String]]', :name\n param 'OptionsWithoutName', :options_hash\n optional_block_param 'BlockType', :block\n end\n\n def lookup_1(scope, name, value_type=nil, merge=nil)\n do_lookup(scope, name, value_type, nil, false, {}, {}, merge)\n end\n\n def lookup_2(scope, name, value_type, merge, default_value)\n do_lookup(scope, name, value_type, default_value, true, {}, {}, merge)\n end\n\n def lookup_3(scope, name, value_type=nil, merge=nil, &block)\n do_lookup(scope, name, value_type, nil, false, {}, {}, merge, &block)\n end\n\n def lookup_4(scope, options_hash, &block)\n do_lookup(scope, options_hash['name'], *hash_args(options_hash), &block)\n end\n\n def lookup_5(scope, name, options_hash, &block)\n do_lookup(scope, name, *hash_args(options_hash), &block)\n end\n\n def do_lookup(scope, name, value_type, default_value, has_default, override, default_values_hash, merge, &block)\n Puppet::Pops::Lookup.lookup(name, value_type, default_value, has_default, merge, Puppet::Pops::Lookup::Invocation.new(scope, override, default_values_hash), &block)\n end\n\n def hash_args(options_hash)\n [\n options_hash['value_type'],\n options_hash['default_value'],\n options_hash.include?('default_value'),\n options_hash['override'] || {},\n options_hash['default_values_hash'] || {},\n options_hash['merge']\n ]\n end\nend" } Note that the "tag_name":"overload" objects include a docstring key, which has both text and tags keys; tags is an array that contains several "tag_name":"param" objects. Add Comment   This message was sent by Atlassian JIRA (v6.4.14#64029-sha1:ae256fe) -- 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.