Don't duplicate enum params

The new docs look like:

  OPTIONS
         --stack-status-filter (list)
            Stack status to use as a filter. Specify one or  more  stack  status
            codes  to  list  only  stacks with the specified status codes. For a
            complete list of stack status codes, see the  StackStatus  parameter
            of the  Stack data type.

         Syntax:

            "string" "string" ...

            Where valid values are:
              CREATE_IN_PROGRESS
              CREATE_FAILED
              CREATE_COMPLETE
              ROLLBACK_IN_PROGRESS
              ROLLBACK_FAILED
              ROLLBACK_COMPLETE
              DELETE_IN_PROGRESS
              DELETE_FAILED
              DELETE_COMPLETE
              UPDATE_IN_PROGRESS
              UPDATE_COMPLETE_CLEANUP_IN_PROGRESS
              UPDATE_COMPLETE
              UPDATE_ROLLBACK_IN_PROGRESS
              UPDATE_ROLLBACK_FAILED
              UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS
              UPDATE_ROLLBACK_COMPLETE

Fixes #609.

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:

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."))