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

[Nicholas Fagerlund (JIRA)]

Title: Message Title

Nicholas Fagerlund created an issue   Puppet Strings / PDOC-125 JSON: Splitting function signatures into two places is awkward Issue Type: Bug Assignee: Unassigned Created: 2016/10/11 10:49 AM Priority: Normal Reporter: Nicholas Fagerlund If a function has only one possible signature, it goes in the top-level signature key. But if there are multiple signatures, signature is absent, and the signatures go in docstring.tags.<index of an "overload" tag>.signature. (That is, a key in any number of overload tags, which are located beside any other tags.) This isn't difficult to work around, but it's poor design. Conceptually, every function has a list of signatures, and that list frequently has just one item; it's weird that it moves to a completely different place if you add one more signature. Example of single signature: { "name": "alert", "file": "/Users/nick/RubymineProjects/puppet-docs/vendor/puppet/lib/puppet/functions/alert.rb", "line": 2, "type": "ruby4x", "signature": "alert(Any *$values)", "docstring": { "text": "Log a message on the server at level alert.", "tags": [ { "tag_name": "param", "text": "The values to log.", "types": [ "Any" ], "name": "*values" }, { "tag_name": "return", "text": "", "types": [ "Undef" ] } ] }, "source": "Puppet::Functions.create_function(:alert, Puppet::Functions::InternalFunction) do\n # @param values The values to log.\n # @return [Undef]\n dispatch :alert do\n scope_param\n repeated_param 'Any', :values\n return_type 'Undef'\n end\n\n def alert(scope, *values)\n Puppet::Util::Log.log_func(scope, :alert, values)\n end\nend" } Example of multiple signatures: { "name": "assert_type", "file": "/Users/nick/RubymineProjects/puppet-docs/vendor/puppet/lib/puppet/functions/assert_type.rb", "line": 53, "type": "ruby4x", "docstring": { "text": "Returns the given value if it is of the given\n[data type](https://docs.puppetlabs.com/puppet/latest/reference/lang_data.html), or\notherwise either raises an error or executes an optional two-parameter\n[lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html).\n\nThe function takes two mandatory arguments, in this order:\n\n1. The expected data type.\n2. A value to compare against the expected data type.\n\n~~~ puppet\n$raw_username = 'Amy Berry'\n\n# Assert that $raw_username is a non-empty string and assign it to $valid_username.\n$valid_username = assert_type(String[1], $raw_username)\n\n# $valid_username contains \"Amy Berry\".\n# If $raw_username was an empty string or a different data type, the Puppet run would\n# fail with an \"Expected type does not match actual\" error.\n~~~\n\nYou can use an optional lambda to provide enhanced feedback. The lambda takes two\nmandatory parameters, in this order:\n\n1. The expected data type as described in the function's first argument.\n2. The actual data type of the value.\n\n~~~ puppet\n$raw_username = 'Amy Berry'\n\n# Assert that $raw_username is a non-empty string and assign it to $valid_username.\n# If it isn't, output a warning describing the problem and use a default value.\n$valid_username = assert_type(String[1], $raw_username) |$expected, $actual| {\n warning( \"The username should be \\'${expected}\\', not \\'${actual}\\'. Using 'anonymous'.\" )\n 'anonymous'\n}\n\n# $valid_username contains \"Amy Berry\".\n# If $raw_username was an empty string, the Puppet run would set $valid_username to\n# \"anonymous\" and output a warning: \"The username should be 'String[1, default]', not\n# 'String[0, 0]'. Using 'anonymous'.\"\n~~~\n\nFor more information about data types, see the\n[documentation](https://docs.puppetlabs.com/puppet/latest/reference/lang_data.html).", "tags": [ { "tag_name": "example", "text": "", "name": "Using `assert_type`" }, { "tag_name": "example", "text": "", "name": "Using `assert_type` with a warning and default value" }, { "tag_name": "since", "text": "4.0.0" }, { "tag_name": "overload", "signature": "assert_type(Type $type, Any $value, Optional[Callable[Type, Type]] &$block)", "name": "assert_type" }, { "tag_name": "overload", "signature": "assert_type(String $type_string, Any $value, Optional[Callable[Type, Type]] &$block)", "name": "assert_type" } ] }, "source": "Puppet::Functions.create_function(:assert_type, Puppet::Functions::InternalFunction) do\n dispatch :assert_type do\n param 'Type', :type\n param 'Any', :value\n optional_block_param 'Callable[Type, Type]', :block\n end\n\n dispatch :assert_type_s do\n scope_param\n param 'String', :type_string\n param 'Any', :value\n optional_block_param 'Callable[Type, Type]', :block\n end\n\n # @param type [Type] the type the value must be an instance of\n # @param value [Object] the value to assert\n #\n def assert_type(type, value)\n unless Puppet::Pops::Types::TypeCalculator.instance?(type,value)\n inferred_type = Puppet::Pops::Types::TypeCalculator.infer_set(value)\n if block_given?\n # Give the inferred type to allow richer comparison in the given block (if generalized\n # information is lost).\n #\n value = yield(type, inferred_type)\n else\n raise Puppet::Pops::Types::TypeAssertionError.new(\n Puppet::Pops::Types::TypeMismatchDescriber.singleton.describe_mismatch('assert_type():', type, inferred_type),\n type, inferred_type)\n end\n end\n value\n end\n\n # @param scope [Puppet::Parser::Scope] scope used when obtaining loader for defined types\n # @param type_string [String] the type the value must be an instance of given in String form\n # @param value [Object] the value to assert\n #\n def assert_type_s(scope, type_string, value, &proc)\n t = Puppet::Pops::Types::TypeParser.singleton.parse(type_string, scope)\n block_given? ? assert_type(t, value, &proc) : assert_type(t, value)\n end\nend" } 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.