{"action":"created","comment":{"url":"https://api.github.com/repos/aws/aws-cli/pulls/comments/38051147","id":38051147,"diff_hunk":"@@ -369,118 +377,116 @@ class ParamShorthandDocGen(object):\n         'list-structure(scalars)': '_list_key_value_parse',\n         'list-structure(list-scalar, scalar)': '_list_scalar_list_parse',\n     }\n+    _DONT_DOC = object()\n+    _MAX_STACK = 3\n \n \n-    def supports_shorthand(self, cli_argument):\n+    def supports_shorthand(self, argument_model):\n         \"\"\"Checks if a CLI argument supports shorthand syntax.\"\"\"\n-        if cli_argument.argument_model is not None:\n-            structure = detect_shape_structure(cli_argument.argument_model)\n-            return structure in self.SHORTHAND_SHAPES\n+        if argument_model is not None:\n+            return _is_complex_shape(argument_model)\n         return False\n \n-    def generate_shorthand_example(self, cli_argument):\n+    def generate_shorthand_example(self, cli_name, argument_model):\n         \"\"\"Generate documentation for a CLI argument.\n \n         :type cli_argument: awscli.arguments.BaseCLIArgument\n         :param cli_argument: The CLI argument which to generate\n             documentation for.\n+\n+        :return: Returns either a string or ``None``.  If a string\n+            is returned, it is the generated shorthand example.\n+            If a value of ``None`` is returned then this indicates\n+            that no shorthand syntax is available for the provided\n+            ``argument_model``.\n+\n         \"\"\"\n-        structure = detect_shape_structure(cli_argument.argument_model)\n-        parse_method_name = self.SHORTHAND_SHAPES.get(structure)\n-        doc_method_name = '_docs%s' % parse_method_name\n-        method = getattr(self, doc_method_name)\n-        doc_string = method(cli_argument)\n-        return doc_string\n-\n-    def _docs_list_scalar_parse(self, cli_argument):\n-        cli_name = cli_argument.cli_name\n-        structure_members = cli_argument.argument_model.member.members\n-        # We know based on the SHORTHAND_SHAPES that this is a\n-        # structure with a single member, so we can safely say:\n-        member_name = list(structure_members.keys())[0]\n-        return '%s %s1 %s2 %s3' % (cli_name, member_name,\n-                                   member_name, member_name)\n-\n-    def _docs_key_value_parse(self, cli_argument):\n-        cli_name = cli_argument.cli_name\n-        model = cli_argument.argument_model\n-        s = '%s ' % cli_name\n-        if model.type_name == 'structure':\n-            members_dict = model.members\n-            member_names = list(members_dict.keys())\n-            s += ','.join(['%s=value' % name for name in member_names])\n-        elif model.type_name == 'map':\n-            s += 'key_name=string,key_name2=string'\n-            if self._has_enum_values(model.key):\n-                enum_values = self._get_enum_values(model.key)\n-                s += '\\nWhere valid key names are:\\n'\n-                for value in enum_values:\n-                    s += '  %s\\n' % value\n-        return s\n-\n-    def _docs_list_key_value_parse(self, cli_argument):\n-        s = \"Key value pairs, with multiple values separated by a space.\\n\"\n-        s += '%s ' % cli_argument.cli_name\n-        members = cli_argument.argument_model.member.members\n-        pair = ','.join(['%s=%s' % (member_name, shape.type_name)\n-                         for member_name, shape in members.items()])\n-        pair += ' %s' % pair\n-        s += pair\n-        return s\n-\n-    def _docs_list_scalar_list_parse(self, cli_argument):\n-        s = ('Key value pairs, where values are separated by commas, '\n-             'and multiple pairs are separated by spaces.\\n')\n-        s += '%s ' % cli_argument.cli_name\n-        pair = self._generate_struct_list_scalar_docs(\n-            cli_argument.argument_model.member.members)\n-        pair += ' %s' % pair\n-        s += pair\n-        return s\n-\n-    def _docs_struct_scalar_list_parse(self, cli_argument):\n-        s = ('Key value pairs, where values are separated by commas.\\n')\n-        s += '%s ' % cli_argument.cli_name\n-        s += self._generate_struct_list_scalar_docs(\n-            cli_argument.argument_model.members)\n-        return s\n-\n-    def _generate_struct_list_scalar_docs(self, members_dict):\n-        scalar_params = list(self._get_scalar_params(members_dict))\n-        list_params = list(self._get_list_params(members_dict))\n-        pair = ''\n-        for member_name, param in scalar_params:\n-            pair += '%s=%s1,' % (member_name, param.type_name)\n-        for member_name, param in list_params[:-1]:\n-            param_type = param.member.type_name\n-            pair += '%s=%s1,%s2,' % (member_name, param_type, param_type)\n-        member_name, last_param = list_params[-1]\n-        param_type = last_param.member.type_name\n-        pair += '%s=%s1,%s2' % (member_name, param_type, param_type)\n-        return pair\n-\n-    def _get_scalar_params(self, members_dict):\n-        for key, value in members_dict.items():\n-            if value.type_name in SCALAR_TYPES:\n-                yield (key, value)\n-\n-    def _get_list_params(self, members_dict):\n-        for key, value in members_dict.items():\n-            if value.type_name == 'list':\n-                yield (key, value)\n-\n-    def _has_enum_values(self, model):\n-        return 'enum' in model.metadata\n-\n-    def _get_enum_values(self, model):\n-        return model.metadata['enum']\n-\n-    def _docs_special_key_value_parse(self, cli_argument):\n-        members = cli_argument.argument_model.members\n-        if len(members) == 1 and 'Value' in members:\n-            # Returning None will indicate that we don't have\n-            # any examples to generate, and the entire examples section\n-            # should be skipped for this arg.\n+        docstring = self._handle_special_cases(cli_name, argument_model)\n+        if docstring is self._DONT_DOC:\n             return None\n+        elif docstring:\n+            return docstring\n+\n+        # Otherwise we fall back to the normal docgen for shorthand\n+        # syntax.\n+        stack = []\n+        try:\n+            if argument_model.type_name == 'list':\n+                argument_model = argument_model.member\n+                return self._shorthand_docs(argument_model, stack) + ' ...'\n+            else:\n+                return self._shorthand_docs(argument_model, stack)\n+        except TooComplexError:\n+            return ''\n+\n+    def _handle_special_cases(self, cli_name, model):\n+        if model.type_name == 'list' and \\\n+                model.member.type_name == 'structure' and \\\n+                len(model.member.members) == 1:\n+            member_name = list(model.member.members)[0]\n+            return '%s %s1 %s2 %s3' % (cli_name, member_name,\n+                                       member_name, member_name)\n+        elif model.type_name == 'structure' and \\\n+                len(model.members) == 1 and \\\n+                'Value' in model.members and \\\n+                model.members['Value'].type_name == 'string':\n+            return self._DONT_DOC","path":"awscli/argprocess.py","position":199,"original_position":199,"commit_id":"74d302e730ae6061977381ec151fd7583d8201a6","original_commit_id":"74d302e730ae6061977381ec151fd7583d8201a6","user":{"login":"kyleknap","id":4605355,"avatar_url":"https://avatars.githubusercontent.com/u/4605355?v=3","gravatar_id":"","url":"https://api.github.com/users/kyleknap","html_url":"https://github.com/kyleknap","followers_url":"https://api.github.com/users/kyleknap/followers","following_url":"https://api.github.com/users/kyleknap/following{/other_user}","gists_url":"https://api.github.com/users/kyleknap/gists{/gist_id}","starred_url":"https://api.github.com/users/kyleknap/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kyleknap/subscriptions","organizations_url":"https://api.github.com/users/kyleknap/orgs","repos_url":"https://api.github.com/users/kyleknap/repos","events_url":"https://api.github.com/users/kyleknap/events{/privacy}","received_events_url":"https://api.github.com/users/kyleknap/received_events","type":"User","site_admin":false},"body":"Do we have a tests for both of these special cases?","created_at":"2015-08-27T00:19:43Z","updated_at":"2015-08-27T00:19:43Z","html_url":"https://github.com/aws/aws-cli/pull/1467#discussion_r38051147","pull_request_url":"https://api.github.com/repos/aws/aws-cli/pulls/1467","_links":{"self":{"href":"https://api.github.com/repos/aws/aws-cli/pulls/comments/38051147"},"html":{"href":"https://github.com/aws/aws-cli/pull/1467#discussion_r38051147"},"pull_request":{"href":"https://api.github.com/repos/aws/aws-cli/pulls/1467"}}},"pull_request":{"url":"https://api.github.com/repos/aws/aws-cli/pulls/1467","id":43350783,"html_url":"https://github.com/aws/aws-cli/pull/1467","diff_url":"https://github.com/aws/aws-cli/pull/1467.diff","patch_url":"https://github.com/aws/aws-cli/pull/1467.patch","issue_url":"https://api.github.com/repos/aws/aws-cli/issues/1467","number":1467,"state":"open","locked":false,"title":"Switch shorthand doc gen over to new approach.","user":{"login":"jamesls","id":368057,"avatar_url":"https://avatars.githubusercontent.com/u/368057?v=3","gravatar_id":"","url":"https://api.github.com/users/jamesls","html_url":"https://github.com/jamesls","followers_url":"https://api.github.com/users/jamesls/followers","following_url":"https://api.github.com/users/jamesls/following{/other_user}","gists_url":"https://api.github.com/users/jamesls/gists{/gist_id}","starred_url":"https://api.github.com/users/jamesls/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jamesls/subscriptions","organizations_url":"https://api.github.com/users/jamesls/orgs","repos_url":"https://api.github.com/users/jamesls/repos","events_url":"https://api.github.com/users/jamesls/events{/privacy}","received_events_url":"https://api.github.com/users/jamesls/received_events","type":"User","site_admin":false},"body":"This PR updates the shorthand documenter to work with the latest changes to the shorthand code (https://github.com/aws/aws-cli/pull/1461).  Specifically:\r\n\r\n* It does not use a hardcoded list of \"shapes\" like the previous approach did.\r\n* It documents the newly supported syntax (nested dictionaries)\r\n\r\nIt also changes some small things in the way docs are generated:\r\n\r\n* The `--argname` is removed in the shorthand example.  This is to make the shorthand syntax consistent with the JSON example syntax.\r\n* The type names are added instead of generic `values`.  Before we'd have `Key=value,Foo=value`.   Now we'll have `Key=string,Foo=float`.\r\n* The single sentence description has been removed.  It's not possible to automatically generate these.\r\n\r\nAnd finally, there's a few areas of improvement I think we'll need to make in the future:\r\n\r\n* Right now, shorthand examples are only generated for code of a stack depth of 3 or less.  This is because sufficiently complicated structures are not readable in shorthand syntax.  We'd need to come up with a way to break these across multiple lines.\r\n* Recursive shapes are documented as `(... recursive ...)`, which is how JSON params are documented.  This might be an area for improvement.\r\n\r\ncc @kyleknap @mtdowling @rayluo ","created_at":"2015-08-25T23:58:06Z","updated_at":"2015-08-27T00:19:43Z","closed_at":null,"merged_at":null,"merge_commit_sha":"9cdf37516e134a612a4fa1b7849443332ac2e112","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/aws/aws-cli/pulls/1467/commits","review_comments_url":"https://api.github.com/repos/aws/aws-cli/pulls/1467/comments","review_comment_url":"https://api.github.com/repos/aws/aws-cli/pulls/comments{/number}","comments_url":"https://api.github.com/repos/aws/aws-cli/issues/1467/comments","statuses_url":"https://api.github.com/repos/aws/aws-cli/statuses/74d302e730ae6061977381ec151fd7583d8201a6","head":{"label":"jamesls:shorthand-docs","ref":"shorthand-docs","sha":"74d302e730ae6061977381ec151fd7583d8201a6","user":{"login":"jamesls","id":368057,"avatar_url":"https://avatars.githubusercontent.com/u/368057?v=3","gravatar_id":"","url":"https://api.github.com/users/jamesls","html_url":"https://github.com/jamesls","followers_url":"https://api.github.com/users/jamesls/followers","following_url":"https://api.github.com/users/jamesls/following{/other_user}","gists_url":"https://api.github.com/users/jamesls/gists{/gist_id}","starred_url":"https://api.github.com/users/jamesls/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jamesls/subscriptions","organizations_url":"https://api.github.com/users/jamesls/orgs","repos_url":"https://api.github.com/users/jamesls/repos","events_url":"https://api.github.com/users/jamesls/events{/privacy}","received_events_url":"https://api.github.com/users/jamesls/received_events","type":"User","site_admin":false},"repo":{"id":8471236,"name":"aws-cli","full_name":"jamesls/aws-cli","owner":{"login":"jamesls","id":368057,"avatar_url":"https://avatars.githubusercontent.com/u/368057?v=3","gravatar_id":"","url":"https://api.github.com/users/jamesls","html_url":"https://github.com/jamesls","followers_url":"https://api.github.com/users/jamesls/followers","following_url":"https://api.github.com/users/jamesls/following{/other_user}","gists_url":"https://api.github.com/users/jamesls/gists{/gist_id}","starred_url":"https://api.github.com/users/jamesls/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jamesls/subscriptions","organizations_url":"https://api.github.com/users/jamesls/orgs","repos_url":"https://api.github.com/users/jamesls/repos","events_url":"https://api.github.com/users/jamesls/events{/privacy}","received_events_url":"https://api.github.com/users/jamesls/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/jamesls/aws-cli","description":"Universal Command Line Interface for Amazon Web Services","fork":true,"url":"https://api.github.com/repos/jamesls/aws-cli","forks_url":"https://api.github.com/repos/jamesls/aws-cli/forks","keys_url":"https://api.github.com/repos/jamesls/aws-cli/keys{/key_id}","collaborators_url":"https://api.github.com/repos/jamesls/aws-cli/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/jamesls/aws-cli/teams","hooks_url":"https://api.github.com/repos/jamesls/aws-cli/hooks","issue_events_url":"https://api.github.com/repos/jamesls/aws-cli/issues/events{/number}","events_url":"https://api.github.com/repos/jamesls/aws-cli/events","assignees_url":"https://api.github.com/repos/jamesls/aws-cli/assignees{/user}","branches_url":"https://api.github.com/repos/jamesls/aws-cli/branches{/branch}","tags_url":"https://api.github.com/repos/jamesls/aws-cli/tags","blobs_url":"https://api.github.com/repos/jamesls/aws-cli/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/jamesls/aws-cli/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/jamesls/aws-cli/git/refs{/sha}","trees_url":"https://api.github.com/repos/jamesls/aws-cli/git/trees{/sha}","statuses_url":"https://api.github.com/repos/jamesls/aws-cli/statuses/{sha}","languages_url":"https://api.github.com/repos/jamesls/aws-cli/languages","stargazers_url":"https://api.github.com/repos/jamesls/aws-cli/stargazers","contributors_url":"https://api.github.com/repos/jamesls/aws-cli/contributors","subscribers_url":"https://api.github.com/repos/jamesls/aws-cli/subscribers","subscription_url":"https://api.github.com/repos/jamesls/aws-cli/subscription","commits_url":"https://api.github.com/repos/jamesls/aws-cli/commits{/sha}","git_commits_url":"https://api.github.com/repos/jamesls/aws-cli/git/commits{/sha}","comments_url":"https://api.github.com/repos/jamesls/aws-cli/comments{/number}","issue_comment_url":"https://api.github.com/repos/jamesls/aws-cli/issues/comments{/number}","contents_url":"https://api.github.com/repos/jamesls/aws-cli/contents/{+path}","compare_url":"https://api.github.com/repos/jamesls/aws-cli/compare/{base}...{head}","merges_url":"https://api.github.com/repos/jamesls/aws-cli/merges","archive_url":"https://api.github.com/repos/jamesls/aws-cli/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/jamesls/aws-cli/downloads","issues_url":"https://api.github.com/repos/jamesls/aws-cli/issues{/number}","pulls_url":"https://api.github.com/repos/jamesls/aws-cli/pulls{/number}","milestones_url":"https://api.github.com/repos/jamesls/aws-cli/milestones{/number}","notifications_url":"https://api.github.com/repos/jamesls/aws-cli/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/jamesls/aws-cli/labels{/name}","releases_url":"https://api.github.com/repos/jamesls/aws-cli/releases{/id}","created_at":"2013-02-28T03:36:51Z","updated_at":"2015-02-18T21:17:08Z","pushed_at":"2015-08-25T23:08:18Z","git_url":"git://github.com/jamesls/aws-cli.git","ssh_url":"git@github.com:jamesls/aws-cli.git","clone_url":"https://github.com/jamesls/aws-cli.git","svn_url":"https://github.com/jamesls/aws-cli","homepage":null,"size":8555,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"develop"}},"base":{"label":"aws:develop","ref":"develop","sha":"375b8460d5660477dd96c020bf349f02faeccaaf","user":{"login":"aws","id":2232217,"avatar_url":"https://avatars.githubusercontent.com/u/2232217?v=3","gravatar_id":"","url":"https://api.github.com/users/aws","html_url":"https://github.com/aws","followers_url":"https://api.github.com/users/aws/followers","following_url":"https://api.github.com/users/aws/following{/other_user}","gists_url":"https://api.github.com/users/aws/gists{/gist_id}","starred_url":"https://api.github.com/users/aws/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aws/subscriptions","organizations_url":"https://api.github.com/users/aws/orgs","repos_url":"https://api.github.com/users/aws/repos","events_url":"https://api.github.com/users/aws/events{/privacy}","received_events_url":"https://api.github.com/users/aws/received_events","type":"Organization","site_admin":false},"repo":{"id":6780767,"name":"aws-cli","full_name":"aws/aws-cli","owner":{"login":"aws","id":2232217,"avatar_url":"https://avatars.githubusercontent.com/u/2232217?v=3","gravatar_id":"","url":"https://api.github.com/users/aws","html_url":"https://github.com/aws","followers_url":"https://api.github.com/users/aws/followers","following_url":"https://api.github.com/users/aws/following{/other_user}","gists_url":"https://api.github.com/users/aws/gists{/gist_id}","starred_url":"https://api.github.com/users/aws/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aws/subscriptions","organizations_url":"https://api.github.com/users/aws/orgs","repos_url":"https://api.github.com/users/aws/repos","events_url":"https://api.github.com/users/aws/events{/privacy}","received_events_url":"https://api.github.com/users/aws/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/aws/aws-cli","description":"Universal Command Line Interface for Amazon Web Services","fork":false,"url":"https://api.github.com/repos/aws/aws-cli","forks_url":"https://api.github.com/repos/aws/aws-cli/forks","keys_url":"https://api.github.com/repos/aws/aws-cli/keys{/key_id}","collaborators_url":"https://api.github.com/repos/aws/aws-cli/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/aws/aws-cli/teams","hooks_url":"https://api.github.com/repos/aws/aws-cli/hooks","issue_events_url":"https://api.github.com/repos/aws/aws-cli/issues/events{/number}","events_url":"https://api.github.com/repos/aws/aws-cli/events","assignees_url":"https://api.github.com/repos/aws/aws-cli/assignees{/user}","branches_url":"https://api.github.com/repos/aws/aws-cli/branches{/branch}","tags_url":"https://api.github.com/repos/aws/aws-cli/tags","blobs_url":"https://api.github.com/repos/aws/aws-cli/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/aws/aws-cli/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/aws/aws-cli/git/refs{/sha}","trees_url":"https://api.github.com/repos/aws/aws-cli/git/trees{/sha}","statuses_url":"https://api.github.com/repos/aws/aws-cli/statuses/{sha}","languages_url":"https://api.github.com/repos/aws/aws-cli/languages","stargazers_url":"https://api.github.com/repos/aws/aws-cli/stargazers","contributors_url":"https://api.github.com/repos/aws/aws-cli/contributors","subscribers_url":"https://api.github.com/repos/aws/aws-cli/subscribers","subscription_url":"https://api.github.com/repos/aws/aws-cli/subscription","commits_url":"https://api.github.com/repos/aws/aws-cli/commits{/sha}","git_commits_url":"https://api.github.com/repos/aws/aws-cli/git/commits{/sha}","comments_url":"https://api.github.com/repos/aws/aws-cli/comments{/number}","issue_comment_url":"https://api.github.com/repos/aws/aws-cli/issues/comments{/number}","contents_url":"https://api.github.com/repos/aws/aws-cli/contents/{+path}","compare_url":"https://api.github.com/repos/aws/aws-cli/compare/{base}...{head}","merges_url":"https://api.github.com/repos/aws/aws-cli/merges","archive_url":"https://api.github.com/repos/aws/aws-cli/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/aws/aws-cli/downloads","issues_url":"https://api.github.com/repos/aws/aws-cli/issues{/number}","pulls_url":"https://api.github.com/repos/aws/aws-cli/pulls{/number}","milestones_url":"https://api.github.com/repos/aws/aws-cli/milestones{/number}","notifications_url":"https://api.github.com/repos/aws/aws-cli/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/aws/aws-cli/labels{/name}","releases_url":"https://api.github.com/repos/aws/aws-cli/releases{/id}","created_at":"2012-11-20T16:07:36Z","updated_at":"2015-08-26T17:37:27Z","pushed_at":"2015-08-26T21:52:13Z","git_url":"git://github.com/aws/aws-cli.git","ssh_url":"git@github.com:aws/aws-cli.git","clone_url":"https://github.com/aws/aws-cli.git","svn_url":"https://github.com/aws/aws-cli","homepage":null,"size":18410,"stargazers_count":3043,"watchers_count":3043,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":413,"mirror_url":null,"open_issues_count":171,"forks":413,"open_issues":171,"watchers":3043,"default_branch":"develop"}},"_links":{"self":{"href":"https://api.github.com/repos/aws/aws-cli/pulls/1467"},"html":{"href":"https://github.com/aws/aws-cli/pull/1467"},"issue":{"href":"https://api.github.com/repos/aws/aws-cli/issues/1467"},"comments":{"href":"https://api.github.com/repos/aws/aws-cli/issues/1467/comments"},"review_comments":{"href":"https://api.github.com/repos/aws/aws-cli/pulls/1467/comments"},"review_comment":{"href":"https://api.github.com/repos/aws/aws-cli/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/aws/aws-cli/pulls/1467/commits"},"statuses":{"href":"https://api.github.com/repos/aws/aws-cli/statuses/74d302e730ae6061977381ec151fd7583d8201a6"}}}}