Repository: aws/aws-cli

Issue:
Docs for list of enum params needs to be improved
When a parameter is a list of strings and there is an enum associated with it, the example syntax that gets generated is confusing.

See [this](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-stacks.html) for an example.



Discussion:

Resolving patch:
diff --git a/awscli/clidocs.py b/awscli/clidocs.py
--- a/awscli/clidocs.py
+++ b/awscli/clidocs.py
@@ -268,9 +268,11 @@ def doc_description(self, help_command, **kwargs):
         doc.style.h2('Description')
         doc.include_doc_string(operation.documentation)
 
-    def _json_example_value_name(self, param):
+    def _json_example_value_name(self, param, include_enum_values=True):
+        # If include_enum_values is True, then the valid enum values
+        # are included as the sample JSON value.
         if param.type == 'string':
-            if hasattr(param, 'enum'):
+            if hasattr(param, 'enum') and include_enum_values:
                 choices = param.enum
                 return '|'.join(['"%s"' % c for c in choices])
             else:
@@ -370,8 +372,13 @@ def doc_option_example(self, arg_name, help_command, **kwargs):
             doc.style.new_paragraph()
             doc.write('Syntax')
             doc.style.start_codeblock()
-            example_type = self._json_example_value_name(param.members)
+            example_type = self._json_example_value_name(
+                param.members, include_enum_values=False)
             doc.write('%s %s ...' % (example_type, example_type))
+            if hasattr(param.members, 'enum'):
+                # If we have enum values, we can tell the user
+                # exactly what valid values they can provide.
+                self._write_valid_enums(doc, param.members.enum)
             doc.style.end_codeblock()
             doc.style.new_paragraph()
         elif argument.cli_type_name not in SCALAR_TYPES:
@@ -382,6 +389,13 @@ def doc_option_example(self, arg_name, help_command, **kwargs):
             doc.style.end_codeblock()
             doc.style.new_paragraph()
 
+    def _write_valid_enums(self, doc, enum_values):
+        doc.style.new_paragraph()
+        doc.write("Where valid values are:\n")
+        for value in enum_values:
+            doc.write("    %s\n" % value)
+        doc.write("\n")
+
     def _doc_member(self, doc, member_name, member):
         docs = member.get('documentation', '')
         if member_name:


Test patch:
diff --git a/tests/unit/docs/test_help_output.py b/tests/unit/docs/test_help_output.py
--- a/tests/unit/docs/test_help_output.py
+++ b/tests/unit/docs/test_help_output.py
@@ -272,3 +272,26 @@ def test_description_from_rst_file(self):
         self.assert_contains('metadata_service_timeout')
         self.assert_contains('metadata_service_num_attempts')
         self.assert_contains('aws_access_key_id')
+
+class TestEnumDocsArentDuplicated(BaseAWSHelpOutputTest):
+    def test_enum_docs_arent_duplicated(self):
+        # Test for: https://github.com/aws/aws-cli/issues/609
+        # What's happening is if you have a list param that has
+        # an enum, we document it as:
+        # a|b|c|d   a|b|c|d
+        # Except we show all of the possible enum params twice.
+        # Each enum param should only occur once.  The ideal documentation
+        # should be:
+        #
+        # string1 string2
+        #
+        # Where each value is one of:
+        #     value1
+        #     value2
+        self.driver.main(['cloudformation', 'list-stacks', 'help'])
+        # "CREATE_IN_PROGRESS" is a enum value, and should only
+        # appear once in the help output.
+        contents = self.renderer.rendered_contents
+        self.assertTrue(contents.count("CREATE_IN_PROGRESS") == 1,
+                        ("Enum param was only suppose to be appear once in "
+                         "rendered doc output."))