From 2c67f9e87567f15c4041e0caa47154b9105fb0f3 Mon Sep 17 00:00:00 2001
From: Krzysztof Wilczynski <krzysztof.wilczynski@linux.com>
Date: Wed, 19 Oct 2016 16:23:02 +0100
Subject: [PATCH] Re-factor documentation for the aws_ecs_task_definition
 resource.

This commits changes the documentation of the aws_ecs_task_definition
resource to ensure that the `container_definitions` attribute consumes
a valid JSON document containing a list of valid container definitions,
rather than that the attribute itself is a list, etc.

Signed-off-by: Krzysztof Wilczynski <krzysztof.wilczynski@linux.com>
---
 .../aws/r/ecs_task_definition.html.markdown   | 56 +++++++++++++------
 1 file changed, 38 insertions(+), 18 deletions(-)

diff --git a/website/source/docs/providers/aws/r/ecs_task_definition.html.markdown b/website/source/docs/providers/aws/r/ecs_task_definition.html.markdown
index de68c01de2..2edc5924b4 100644
--- a/website/source/docs/providers/aws/r/ecs_task_definition.html.markdown
+++ b/website/source/docs/providers/aws/r/ecs_task_definition.html.markdown
@@ -13,28 +13,29 @@ Provides an ECS task definition to be used in `aws_ecs_service`.
 ## Example Usage
 
 ```
-resource "aws_ecs_task_definition" "jenkins" {
-  family = "jenkins"
-  container_definitions = "${file("task-definitions/jenkins.json")}"
+resource "aws_ecs_task_definition" "service" {
+  family = "service"
+  container_definitions = "${file("task-definitions/service.json")}"
 
   volume {
-    name = "jenkins-home"
-    host_path = "/ecs/jenkins-home"
+    name = "service-storage"
+    host_path = "/ecs/service-storage"
   }
 }
 ```
 
-### task-definitions/jenkins.json
-
-The below would be passed into the `container_definitions` attribute. This is a small subset of the available parameters, see the [AWS docs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html) for a full list.
+The referenced `task-definitions/service.json` file contains a valid JSON document,
+which is show below, and its content is going to be passed directly into the
+`container_definitions` attribute as a string. Please note that this example
+contains only a small subset of the available parameters.
 
 ```
 [
   {
-    "name": "jenkins",
-    "image": "jenkins",
+    "name": "first",
+    "image": "service-first",
     "cpu": 10,
-    "memory": 500,
+    "memory": 512,
     "essential": true,
     "portMappings": [
       {
@@ -42,6 +43,19 @@ The below would be passed into the `container_definitions` attribute. This is a
         "hostPort": 80
       }
     ]
+  },
+  {
+    "name": "second",
+    "image": "service-second",
+    "cpu": 10,
+    "memory": 256,
+    "essential": true,
+    "portMappings": [
+      {
+        "containerPort": 443,
+        "hostPort": 443
+      }
+    ]
   }
 ]
 ```
@@ -50,21 +64,27 @@ The below would be passed into the `container_definitions` attribute. This is a
 
 The following arguments are supported:
 
-* `family` - (Required) The family, unique name for your task definition.
-* `container_definitions` - (Required) A list of container definitions in JSON format. See [AWS docs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-task-definition.html) for syntax. Note, you only need the containerDefinitions array, not the parent hash including the family and volumes keys.
+* `family` - (Required) An unique name for your task definition.
+* `container_definitions` - (Required) A list of valid [container definitions]
+(http://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDefinition.html) provided as a
+single valid JSON document. Please note that you should only provide values that are part of the container
+definition document. For a detailed description of what parameters are available, see the [Task Definition Parameters]
+(https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html) section from the
+official [Developer Guide](https://docs.aws.amazon.com/AmazonECS/latest/developerguide).
 * `task_role_arn` - (Optional) The ARN of IAM role that allows your Amazon ECS container task to make calls to other AWS services.
 * `network_mode` - (Optional) The Docker networking mode to use for the containers in the task. The valid values are `none`, `bridge`, and `host`.
-* `volume` - (Optional) A volume block. Volumes documented below.
+* `volume` - (Optional) A volume block. See below for details about what arguments are supported.
 
-Volumes support the following:
+Volume block supports the following arguments:
 
-* `name` - (Required) The name of the volume. This name is referenced in the `sourceVolume` parameter of container definition `mountPoints`.
+* `name` - (Required) The name of the volume. This name is referenced in the `sourceVolume`
+parameter of container definition in the `mountPoints` section.
 * `host_path` - (Required) The path on the host container instance that is presented to the container.
 
 ## Attributes Reference
 
 The following attributes are exported:
 
-* `arn` - Full ARN of the task definition (including both `family` & `revision`)
-* `family` - The family of the task definition.
+* `arn` - Full ARN of the Task Definition (including both `family` and `revision`).
+* `family` - The family of the Task Definition.
 * `revision` - The revision of the task in a particular family.