aws · keetonian · Sep 25, 2018 · Jun 28, 2018 · Jun 29, 2018 · Jun 29, 2018
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -59,7 +59,7 @@ Here are some questions that you should answer in your plan:
 
 - **How do developers work around this problem today?**
 
-    Example: Manually click through every step on the website while refering to
+    Example: Manually click through every step on the website while referring to
     "How To" resources on the internet.
 
 - **Describe your proposed solution?**

diff --git a/HOWTO.md b/HOWTO.md
@@ -1,21 +1,21 @@
 # How to create serverless applications using AWS SAM
-AWS Serverless Application Model (AWS SAM) allows you to easily create and 
+The AWS Serverless Application Model (AWS SAM) allows you to easily create and 
 manage resources used in your serverless application using AWS CloudFormation. 
 You can define your serverless application as a SAM template - a JSON or YAML 
 configuration file that describes Lambda function, API endpoints and
-other resources in your application. Using nifty commands, you upload this 
-template to CloudFormation which creates all the individual resources and
+other resources in your application. Using a variety of [nifty commands](https://github.com/awslabs/aws-sam-cli#usage), you upload this 
+template to CloudFormation, which in turn creates all the individual resources and
 groups them into a *CloudFormation Stack* for ease of management. 
 When you update your SAM template, you will re-deploy the changes to 
 this stack. AWS CloudFormation will take care of updating the individual
 resources for you.
 
 
-The remainder of document explains how to write SAM templates and 
+The remainder of this document explains how to write SAM templates and 
 deploy them via AWS CloudFormation. 
 
 ## Writing SAM Template
-Checkout the [latest specification](versions/2016-10-31.md) for details on how to write a SAM template
+Check out the [latest specification](versions/2016-10-31.md) for details on how to write a SAM template
 
 ## Packing Artifacts
 Before you can deploy a SAM template, you should first upload your Lambda 
@@ -71,7 +71,7 @@ SAM template is deployed to AWS CloudFormation by [creating a changeset](http://
 using the SAM template followed by [executing the changeset](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-execute.html). 
 Think of a ChangeSet as a diff between your current stack template and the new template that you are deploying. After you create a ChangeSet, you have the opportunity to examine the diff before executing it. Both the AWS Console and AWS CLI provide commands to create and execute a changeset. 
 
-Alternatively, you can use `aws cloudformation deploy` CLI command to deploy the SAM template. Under-the-hood it creates and executes a changeset and waits until the deployment completes. It also prints debugging hints when the deployment fails. Run the following command to deploy the packaged template to a stack called `my-new-stack`:
+Alternatively, you can use `aws cloudformation deploy` CLI command to deploy the SAM template. Under the hood it creates and executes a changeset and waits until the deployment completes. It also prints debugging hints when the deployment fails. Run the following command to deploy the packaged template to a stack called `my-new-stack`:
 
 ```bash
 $ aws cloudformation deploy \
@@ -83,7 +83,7 @@ $ aws cloudformation deploy \
 Refer to the [documentation](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy/index.html) for more details.
 
 ## Using Intrinsic Functions
-CloudFormation provides handy functions you can use to generate values at runtime. These are called [Intrinsic Functions](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html). Since SAM is deployed using CloudFormation, you can use these intrinsic functions within SAM as well. Here are some examples:
+CloudFormation provides handy functions that you can use to generate values at runtime. These are called [Intrinsic Functions](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html). Since SAM is deployed using CloudFormation, you can use these intrinsic functions within SAM as well. Here are some examples:
 
 #### Dynamically set S3 location of Lambda function code zip
 ```YAML
@@ -136,7 +136,7 @@ Resources:
 
 ### Caveats:
 #### ImportValue is partially supported
-[`ImportValue`](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html) allows one stack to refer to value of properties from another stack. ImportValue is supported on most properties, except the very few that SAM needs to parse. Following properties are *not* supported:
+[`ImportValue`](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html) allows one stack to refer to the value of properties from another stack. ImportValue is supported on most properties, except the very few that SAM needs to parse. The following properties are *not* supported:
 
 - `RestApiId` of `AWS::Serverless::Function`
 - `Policies` of `AWS::Serverless::Function`

diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ The SAM specification and implementation are open sourced under the Apache 2.0 l
 
 
 ## Creating a serverless application using SAM
-To create a serverless application using SAM, first, you create a SAM template: a JSON or YAML configuration file that describes your Lambda functions, API endpoints and the other resources in your application. Then, you test, upload, and deploy your application using the [SAM Local CLI](https://github.com/awslabs/aws-sam-local). During deployment, SAM automatically translates your application’s specification into CloudFormation syntax, filling in default values for any unspecified properties and determining the appropriate mappings and invocation permissions to setup for any Lambda functions.
+To create a serverless application using SAM, first, you create a SAM template: a JSON or YAML configuration file that describes your Lambda functions, API endpoints and the other resources in your application. Then, you test, upload, and deploy your application using the [AWS SAM CLI](https://github.com/awslabs/aws-sam-cli). During deployment, SAM automatically translates your application’s specification into CloudFormation syntax, filling in default values for any unspecified properties and determining the appropriate mappings and invocation permissions to setup for any Lambda functions.
 
 [Read the How-To Guide](HOWTO.md) and see [examples](examples/) to learn how to define & deploy serverless applications using SAM.
 

diff --git a/bin/sam-translate.py b/bin/sam-translate.py
@@ -21,6 +21,8 @@
 from samtranslator.public.translator import ManagedPolicyLoader
 from samtranslator.translator.transform import transform
 from samtranslator.yaml_helper import yaml_parse
+from samtranslator.model.exceptions import InvalidDocumentException
+
 
 cli_options = docopt(__doc__)
 iam_client = boto3.client('iam')
@@ -42,15 +44,21 @@ def main():
     with open(input_file_path, 'r') as f:
         sam_template = yaml_parse(f)
 
-    cloud_formation_template = transform(
-        sam_template, {}, ManagedPolicyLoader(iam_client))
-    cloud_formation_template_prettified = json.dumps(
-        cloud_formation_template, indent=2)
-
-    with open(output_file_path, 'w') as f:
-        f.write(cloud_formation_template_prettified)
-
-    print('Wrote transformed CloudFormation template to: ' + output_file_path)
+    try:
+        cloud_formation_template = transform(
+            sam_template, {}, ManagedPolicyLoader(iam_client))
+        cloud_formation_template_prettified = json.dumps(
+            cloud_formation_template, indent=2)
+
+        with open(output_file_path, 'w') as f:
+            f.write(cloud_formation_template_prettified)
+
+        print('Wrote transformed CloudFormation template to: ' + output_file_path)
+    except InvalidDocumentException as e:
+        errorMessage = reduce(lambda message, error: message + ' ' + error.message, e.causes, e.message)
+        print(errorMessage)
+        errors = map(lambda cause: {'errorMessage': cause.message}, e.causes)
+        print(errors)
 
 
 if __name__ == '__main__':

diff --git a/docs/globals.rst b/docs/globals.rst
@@ -42,19 +42,19 @@ In the above example, both ``HelloWorldFunction`` and ``ThumbnailFunction`` will
 timeout and index.handler Handler. ``HelloWorldFunction`` adds MESSAGE environment variable in addition to the 
 inherited TABLE_NAME. ``ThumbnailFunction`` inherits all the Globals properties and adds an API Event source.
 
-Supported Resources
--------------------
-Properties of ``AWS::Serverless::Function`` and ``AWS::Serverless::Api`` are only supported in Globals section 
-presently. 
+Supported Resources and Properties
+----------------------------------
+Currently, the following resources and properties are being supported:
 
 .. code:: yaml
 
   Globals:
     Function:
-      # Some properties of AWS::Serverless::Function
+      # Properties of AWS::Serverless::Function
       Handler:
       Runtime:
-      CodeUri:
+      # Specifying CodeUri on Globals is not yet supported by 'CloudFormation package' https://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html
+      CodeUri: 
       DeadLetterQueue:
       Description:
       MemorySize:
@@ -68,7 +68,7 @@ presently.
       DeploymentPreference:
 
     Api:
-      # Some properties of AWS::Serverless::Api
+      # Properties of AWS::Serverless::Api
       # Also works with Implicit APIs
       Name:
       DefinitionUri:
@@ -81,6 +81,7 @@ presently.
       Cors:
 
     SimpleTable:
+      # Properties of AWS::Serverless::SimpleTable
       SSESpecification
 
 Implicit APIs
@@ -143,20 +144,19 @@ Runtime of ``MyFunction`` will be set to python3.6
 
 Maps are merged
 ~~~~~~~~~~~~~~~
-*Also called as dictionaries, or key/value pairs*
+*Maps are also known as dictionaries or collections of key/value pairs*
 
-Map value in the resource will be **merged** with the map value from Global. 
+Map entries in the resource will be **merged** with global map entries. In case of duplicates the resource entry will override the global entry.
 
 Example:
 
-Environment variables of ``MyFunction`` will be set to ``{ TABLE_NAME: "resource-table", "NEW_VAR": "hello" }``
-
 .. code:: yaml
 
   Globals:
     Function:
       Environment: 
         Variables:
+          STAGE: Production
           TABLE_NAME: global-table
 
   Resources:
@@ -168,16 +168,24 @@ Environment variables of ``MyFunction`` will be set to ``{ TABLE_NAME: "resource
             TABLE_NAME: resource-table
             NEW_VAR: hello
 
+In the above example the environment variables of ``MyFunction`` will be set to:
+
+.. code:: json
+
+  {
+    "STAGE": "Production", 
+    "TABLE_NAME": "resource-table", 
+    "NEW_VAR": "hello" 
+  }
+
 Lists are additive
 ~~~~~~~~~~~~~~~~~~~
-*Also called as arrays*
+*Lists are also known as arrays*
 
-List values in the resource will be **appended** with the map value from Global. 
+Global entries will be **prepended** to the list in the resource.
 
 Example:
 
-SecurityGroupIds of VpcConfig will be set to ``["sg-first", "sg-123", "sg-456"]``
-
 .. code:: yaml
 
   Globals:
@@ -195,3 +203,8 @@ SecurityGroupIds of VpcConfig will be set to ``["sg-first", "sg-123", "sg-456"]`
           SecurityGroupIds:
             - sg-first
 
+In the above example the Security Group Ids of ``MyFunction``'s VPC Config will be set to:
+
+.. code:: json
+
+  [ "sg-123", "sg-456", "sg-first" ]
diff --git a/docs/policy_templates.rst b/docs/policy_templates.rst
@@ -73,5 +73,5 @@ folder.
     Policies:
       - CloudWatchPutMetricPolicy: {}      
 
-.. _policy_templates.json: https://github.com/awslabs/serverless-application-model/blob/develop/docs/policy_templates_data/policy_templates.json
+.. _policy_templates.json: https://github.com/awslabs/serverless-application-model/blob/develop/samtranslator/policy_templates_data/policy_templates.json
 .. _all_policy_templates.yaml: https://github.com/awslabs/serverless-application-model/blob/develop/examples/2016-10-31/policy_templates/all_policy_templates.yaml