Clarify meaing of total available memory

Glyn Normington · Glyn Normington · commit 3b4c99da009b · 2013-11-18T11:31:47.000Z
Also note the effect of scaling an application.

[#60311680]
diff --git a/README.md b/README.md
@@ -10,6 +10,8 @@ To use this buildpack specify the URI of the repository when pushing an applicat
 
     cf push --buildpack https://github.com/cloudfoundry/java-buildpack
 
+The total amount of memory available is specified when the application is pushed. See [Memory](docs/jre-openjdk.md#Memory) for information on how this determines the memory available to a Java application.
+
 ## Configuration and Extension
 The buildpack supports configuration and extension through the use of Git repository forking.  The easiest way to accomplish this is to use [GitHub's forking functionality][] to create a copy of this repository.  Make the required configuration and extension changes in the copy of the repository.  Then specify the URL of the new repository when pushing Cloud Foundry applications.  If the modifications are generally applicable to the Cloud Foundry community, please submit a [pull request][] with the changes.
 
diff --git a/docs/jre-openjdk.md b/docs/jre-openjdk.md
@@ -20,11 +20,17 @@ The JRE can be configured by modifying the [`config/openjdk.yml`][] file.  The J
 | ---- | -----------
 | `repository_root` | The URL of the OpenJDK repository index ([details][repositories]).
 | `version` | The version of Java runtime to use.  Candidate versions can be found in the listings for [centos6][], [lucid][], [mountainlion][], and [precise][]. Note: version 1.8.0 and higher require the `memory_sizes` and `memory_heuristics` mappings to specify `metaspace` rather than `permgen`.
-| `memory_sizes` | Optional memory sizes, described below under "Memory".
-| `memory_heuristics` | Default memory size weightings, described below under "Default Memory Sizes".
+| `memory_sizes` | Optional memory sizes, described below under "Memory Sizes".
+| `memory_heuristics` | Default memory size weightings, described below under "Memory Weightings.
 
 ### Memory
 
+The total available memory is specified when an application is pushed. The Java buildpack uses this value to control the JRE's use of various regions of memory. The JRE memory settings can be influenced by configuring the `memory_sizes` and/or `memory_heuristics` mappings.
+
+Note: if the total available memory is scaled up or down, the Java buildpack does not re-calculate the JRE memory settings until the next time the appication is pushed.
+
+#### Memory Sizes
+
 The following optional properties may be specified in the `memory_sizes` mapping.
 
 | Name | Description
@@ -35,8 +41,6 @@ The following optional properties may be specified in the `memory_sizes` mapping
 | `stack` | The stack size to use. It may be a single value such as `2m` or a range of acceptable values such as `2m..4m`. It is used to calculate the value of the Java command line option `-Xss`.
 | `native` | The amount of memory to reserve for native memory allocation. It should normally be omitted or specified as a range with no upper bound such as `100m..`. It does not correspond to a switch on the Java command line.
 
-#### Memory Sizes and Ranges
-
 Memory sizes together with _memory weightings_ (described in the next section) are used to calculate the amount of memory for each memory type. The calculation is described later.
 
 Memory sizes consist of a non-negative integer followed by a unit (`k` for kilobytes, `m` for megabytes, `g` for gigabytes; the case is not significant). Only the memory size `0` may be specified without a unit.
