Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Eric Thompson updated an issue Puppet Strings / PDOC-125 JSON: Splitting function signatures into two places is awkward Change By: Eric Thompson QA Risk Assessment Reason: covered well by rspec acceptance tests in PR 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Eric Thompson updated an issue Puppet Strings / PDOC-125 JSON: Splitting function signatures into two places is awkward Change By: Eric Thompson QA Status: Reviewed 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Eric Thompson updated an issue Puppet Strings / PDOC-125 JSON: Splitting function signatures into two places is awkward Change By: Eric Thompson QA Risk Assessment: Medium 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title William Hopper assigned an issue to qa Puppet Strings / PDOC-125 JSON: Splitting function signatures into two places is awkward Change By: William Hopper Status: Ready for Merge Test Assignee: qa 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title William Hopper updated an issue Puppet Strings / PDOC-125 JSON: Splitting function signatures into two places is awkward Change By: William Hopper Release Notes Summary: This commit adds a new top-level key to the JSON schema for functions: signatures. This key holds all function signature data, and in the case of 4.x functions with multiple dispatches, each overload is present along with each of their parameters and other tags. Release Notes: New Feature 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Craig Gomes updated an issue Puppet Strings / PDOC-125 JSON: Splitting function signatures into two places is awkward Change By: Craig Gomes Sprint: PDS 2016-11-02 , PDS 2016-11-16 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Nicholas Fagerlund commented on PDOC-125 Re: JSON: Splitting function signatures into two places is awkward William Hopper Yeah, this is pretty much exactly what I was hoping for! 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title William Hopper updated an issue Puppet Strings / PDOC-125 JSON: Splitting function signatures into two places is awkward Change By: William Hopper Sprint: PDS 2016-11-02 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title William Hopper assigned an issue to William Hopper Puppet Strings / PDOC-125 JSON: Splitting function signatures into two places is awkward Change By: William Hopper Assignee: William Hopper 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title William Hopper updated an issue Puppet Strings / PDOC-125 JSON: Splitting function signatures into two places is awkward Change By: William Hopper Story Points: 3 Team: Puppet Developer Support 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Jesse Scott commented on PDOC-125 Re: JSON: Splitting function signatures into two places is awkward That sounds reasonable to me. Having one place to look for signatures (that is always a list, even if it only has one item) sounds a lot better than a conditional. 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title William Hopper updated an issue Puppet Strings / PDOC-125 JSON: Splitting function signatures into two places is awkward Change By: William Hopper Fix Version/s: PDOC 1.0.0 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Lindsey Smith commented on PDOC-125 Re: JSON: Splitting function signatures into two places is awkward Jesse Scott can evaluate from the Forge perspective 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Nicholas Fagerlund commented on PDOC-125 Re: JSON: Splitting function signatures into two places is awkward Okay, taking that into account, here's my full proposal: We leave the format of the "overload"/signature objects mostly alone — they continue to be objects that can have their own docstring text, tags, etc. However, we remove the "tag_name":"overload" part... (...and possibly the "name" part, since it never seems to contain any new information?...) ...and we move them from the docstring.tags array to a new top-level array in the function object. The key name should be either "signatures" (existing, well-known term of art) or "dispatches" (after the name of the method used to establish a signature in the Ruby 4x function API). I prefer "signatures." If there is only one signature for a function, we combine the signature and any "tag_name":"param" objects from the docstring.tags array to create a new signature object, which we place in the top-level "signatures" array. This unifies the behavior of single and multiple dispatch, which was my original request for this ticket. We no longer use the top-level "signature" (non-plural) key or free-floating "param" objects in the tags array. Param descriptions are always associated with a particular function dispatch. Does that match what we already do to validate @param tags? Or am I forgetting something weird? How does this sound? I'd also like to get input from the Forge team since I think they're the next people going to be using this... who's the right one to ask for that? Add Comment
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
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 `::`.\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( , [], [], [] )`\n* `lookup( [], )`\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. `` (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\nfirst key, it will try again with the subsequent ones, only resorting to a\ndefault value if none of
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Lindsey Smith commented on PDOC-125 Re: JSON: Splitting function signatures into two places is awkward I don't feel like I have a basis for making a recommendation and am willing to accept the consensus choice. 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title
Nicholas Fagerlund commented on PDOC-125
Re: JSON: Splitting function signatures into two places is awkward
I think our options are:
As a top-level key ("signatures" maybe) in the function object.
As a key ("signatures") in the "docstring" object.
As an object in the "docstring.tags" object ("tag_name":"signatures", "signatures":, or something like that).
As a group of "overload" objects in the docstring.tags object (i.e. we just move the existing top-level "signature" key to an overload object).
I dislike options 3 and 4, but can easily live with them if there's a good argument for going that way. I think 1 and 2 are basically equivalent.
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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Lindsey Smith commented on PDOC-125 Re: JSON: Splitting function signatures into two places is awkward In the interest of getting to a decision, it sounds like we're comfortable with changing the behavior from YARD. If that's true and I understand correctly, the remaining question is where we want the signature(s) to be nested within the JSON? 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Peter Huene commented on PDOC-125 Re: JSON: Splitting function signatures into two places is awkward I'm completely fine with having a better structure that isn't tied closely to YARD, but I'd still argue that an overload's signature belongs with the overload's data (doc text, tags, etc.) because most of the time you want this displayed as a single entity in a list of overloads. 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Henrik Lindberg commented on PDOC-125 Re: JSON: Splitting function signatures into two places is awkward Agree with Nicholas Fagerlund here. Think this format should try to be free of yard concerns. Who knows what we will be using years from now. 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Nicholas Fagerlund commented on PDOC-125 Re: JSON: Splitting function signatures into two places is awkward Sure. But given that this JSON will be used by the Forge, possibly the PE console, possibly a future CLI interface for reading bite-sized docs, etc., I think it's worth treating it like a designed interface, don't you? 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Peter Huene commented on PDOC-125 Re: JSON: Splitting function signatures into two places is awkward This is funky because this is how YARD represents the data. That is to say the intention of this schema was to enable any users familiar with YARD to consume the data for their uses and not solely as a mechanism for which Puppet's doc team can generate documentation. Function objects only have a single signature, which is omitted when the function has overloads because the overload tags themselves store their signature representation. Perhaps this is not the best way of representing it, but it's consistent with how YARD does it. 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
Title: Message Title Nicholas Fagerlund commented on PDOC-125 Re: JSON: Splitting function signatures into two places is awkward My preferred interface would be a top-level signatures tag that is always an array. 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.
Jira (PDOC-125) JSON: Splitting function signatures into two places is awkward
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..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":
