updates on documentation (cloudfoundry#544)

* updates on documentation

* update per comments

* update per comment

docs/Public_API.rst

@@ -1123,12 +1123,22 @@ A JSON payload is required to emit your own metrics with the metric value and th
 
         "name": "<CUSTOM METRIC NAME>",
 
-        "value": <CUSTOM METRIC VALUE>
+        "value": <CUSTOM METRIC VALUE>,
+
+        "unit": "<CUSTOM METRIC UNIT>"
 
       }]
 
   }
 
+* `<INSTANCE INDEX>` is the index of current application instance. You can fetch the index from environment variable `CF_INSTANCE_INDEX`
+
+* `<CUSTOM METRIC NAME>` is the name of the emit metric which must be equal to the metric name that you define in the policy. 
+
+* `<CUSTOM METRIC VALUE>` is value that you would like to submit. The `value` here must be a NUMBER.
+
+* `<CUSTOM METRIC UNIT>` is the unit of the metric, optional.
+
 Headers
 '''''''
     Basic authorization of autoscaler credential is required when submitting your own metrics to Autoscaler metric server.

docs/Readme.md

@@ -52,10 +52,9 @@ The following are the built-in metrics that you can use to scale your applicatio
 
 * **custom metric** 
 
-	Custom emtric is supported since [app-autoscaler v3.0.0 release][app-autoscaler-v3.0.0]. You can define your own metric name and emit your own metric to `App Autoscaler` to trigger further dynamic scaling. 
+	Custom emtric is supported since [app-autoscaler v3.0.0 release][app-autoscaler-v3.0.0]. You can define your own metric name and emit your own metric to `App Autoscaler` to trigger further dynamic scaling. Only alphabet letters, numbers and "_" are allowed for a valid metric name, and the maximum length of the metric name is limited up to 100 characters. 
 
 
-
 ####  Threshold and Adjustment
 
 `App AutoScaler` evaluates the aggregated metric values against the threshold defined in the dynamic scaling rules, and change the application instance count according to the adjustment setting.  
@@ -70,16 +69,17 @@ For example, if you want to scale out your application by adding 2 instances whe
 }
 ```
 
-####  Breach duration and Cooldown
+####  (Optional) Breach duration and Cooldown 
 
 `App AutoScaler` will not take scaling action until your application continues breaching the rule in a time duration defined in `breach_duration_secs`.  This setting controls how fast the autoscaling action could be triggered. 
 
 `cool_down_secs` defines the time duration to wait before the next scaling kicks in.  It helps to ensure that your application does not launch or terminate instances before your application becomes stable. This setting can be configured based on your instance warm-up time or other needs.
 
 *Note:*
 
-You can define multiple scaling-out and scaling-in rules. However, `App-AutoScaler` does not detect conflicts among them.  It is your responsibility to ensure the scaling rules do not conflict with each other to avoid fluctuation or other issues. 
+* You can define multiple scaling-out and scaling-in rules. However, `App-AutoScaler` does not detect conflicts among them.  It is your responsibility to ensure the scaling rules do not conflict with each other to avoid fluctuation or other issues. 
 
+* `breach_duration_secs` and `cool_down_secs` are both optional entries in scaling_rule definition.  The `App Autoscaler` provider will define the default value if you omit them from the policy.
 
 ###  Schedules
 
@@ -260,19 +260,29 @@ You need to emit  your own metric for scaling to the "URL" specified in credenti
 POST /v1/apps/:guid/metrics
 ```
 
+*Note:* `:guid` is the `app_id` of your application.  You can get it from the credential JSON file , or from the environment variable
+
 A JSON payload is required with above API to submit metric name, value and the correspondng instance index.
 ```
   {
     "instance_index": <INSTANCE INDEX>,
     "metrics": [
       {
         "name": "<CUSTOM METRIC NAME>",
-        "value": <CUSTOM METRIC VALUE>
+        "value": <CUSTOM METRIC VALUE>,
+        "unit": "<CUSTOM METRIC UNIT>",
       }
     ]
   }
 ```
 
+*Note:*
+
+* `<INSTANCE INDEX>` is the index of current application instance. You can fetch the index from environment variable `CF_INSTANCE_INDEX`
+* `<CUSTOM METRIC NAME>` is the name of the emit metric which must be equal to the metric name that you define in the policy. 
+* `<CUSTOM METRIC VALUE>` is value that you would like to submit. The `value` here must be a NUMBER.
+* `<CUSTOM METRIC UNIT>` is the unit of the metric, optional.
+
 Please refer to [Emit metric API Spec][emit-metric-api] for more information.