Document memory_sizes OpenJDK configuration

Glyn Normington · Glyn Normington · commit 6526fee97908 · 2013-07-01T11:36:03.000+01:00
Document the memory_sizes configuration section of config/openjdk.yml.

Add missing documentation of repository_root for both OpenJDK and
Tomcat configuration files.

Improve the repository documentation.

Add an empty memory_sizes section to config/openjdk.yml to make it
easier for users to configure memory sizes.

[#52618651]
diff --git a/config/openjdk.yml b/config/openjdk.yml
@@ -17,6 +17,7 @@
 ---
 repository_root: "http://download.pivotal.io.s3.amazonaws.com/openjdk/lucid/x86_64"
 version: 1.7.0_+
+memory_sizes:
 memory_heuristics:
   heap: 0.75
   permgen: 0.1
diff --git a/docs/container-tomcat.md b/docs/container-tomcat.md
@@ -21,12 +21,13 @@ The container can be configured by modifying the [`config/tomcat.yml`][tomcat_ym
 
 | Name | Description
 | ---- | -----------
-| `version` | The version of Tomcat to use.  .  Candidate versions can be found in [this listing][tomcat_index_yml].
+| `repository_root` | The URL of the Tomcat repository index ([details][util_repositories]).
+| `version` | The version of Tomcat to use. Candidate versions can be found in [this listing][tomcat_index_yml].
 
 [tomcat_index_yml]: http://download.pivotal.io.s3.amazonaws.com/tomcat/lucid/x86_64/index.yml
 
 
 ## Supporting Functionality
-Additional supporting functionality can be found in the [`java-buildpack-support][java_buildpack_support] Git repository.
+Additional supporting functionality can be found in the [`java-buildpack-support`][java_buildpack_support] Git repository.
 
 [java_buildpack_support]: https://github.com/cloudfoundry/java-buildpack-support
diff --git a/docs/jre-openjdk.md b/docs/jre-openjdk.md
@@ -23,13 +23,16 @@ The JRE can be configured by modifying the [`config/openjdk.yml`][openjdk_yml] f
 
 | Name | Description
 | ---- | -----------
+| `repository_root` | The URL of the OpenJDK repository index ([details][util_repositories]).
 | `version` | The version of Java runtime to use.  Candidate versions can be found in [this listing][openjdk_index_yml].
+| `memory_sizes` | Optional memory sizes, described below under "Memory".
+| `memory_heuristics` | Default memory size proportions, described below under "Default Memory Sizes".
 
 [openjdk_index_yml]: http://download.pivotal.io.s3.amazonaws.com/openjdk/lucid/x86_64/index.yml
 
 ### Memory
 
-The following properties may be specified in [`config/openjdk.yml`][openjdk_yml].
+The following optional properties may be specified in the `memory_sizes` mapping.
 
 | Name | Description
 | ---- | -----------
@@ -38,10 +41,10 @@ The following properties may be specified in [`config/openjdk.yml`][openjdk_yml]
 | `permgen` | The Java maximum PermGen size to use. This is applicable to versions of OpenJDK earlier than 1.8. For example, a value of `128m` will result in the java command line option `-XX:MaxPermSize=128m`. Values containing whitespace are rejected with an error, but all others values appear without modification on the java command line appended to `-XX:MaxPermSize=`.
 | `stack` | The Java stack size to use. For example, a value of `256k` will result in the java command line option `-Xss256k`. Values containing whitespace are rejected with an error, but all others values appear without modification on the java command line appended to `-Xss`.
 
-#### Default Memory Sizes
+### Default Memory Sizes
 
 If some memory sizes are not specified using the above properties, default values are provided. For maximum heap, Metaspace, or PermGen size, the default value is based on a proportion of the total memory specified when the application was pushed. For stack size, the default value is one megabyte.
 
-If any memory sizes are specified which are not equal to the default value, the proportionate defaults are adjusted accordingly. The default stack size is never adjusted from the default value.
+If a memory size is specified which are not equal to the default value, the defaults are adjusted proportionately, except that the default stack size is never adjusted.
 
-The default memory size proportions are configured in the `memory_heuristics` section of [`config/openjdk.yml`][openjdk_yml]. Each memory size is given a weighting between `0` and `1` corresponding to a proportion of the total memory specified when the application was pushed. The weightings should add up to `1`.
+The default memory size proportions are configured in the `memory_heuristics` mapping of [`config/openjdk.yml`][openjdk_yml]. Each memory size is given a weighting between `0` and `1` corresponding to a proportion of the total memory specified when the application was pushed. The weightings should add up to `1`.
diff --git a/docs/util-repositories.md b/docs/util-repositories.md
@@ -2,12 +2,13 @@
 Many components need to have access to multiple versions of binaries.  The buildpack provides a `Repository` abstraction to encapsulate version resolution and download URI creation.
 
 ## Repository Structure
-The repository is an HTTP-accessible collection of files.  The repository root must contain an `index.yml` file ([example][example_index_yml]) that is a mapping of concrete versions to URIs.
-
+The repository is an HTTP-accessible collection of files.  The repository root must contain an `index.yml` file ([example][example_index_yml]) that is a mapping of concrete versions to absolute URIs consisting of a series of lines of the form:
 ```yaml
 <version>: <URI>
 ```
 
+The collection of files may be stored alongside the index file or elsewhere.
+
 An example filesystem might look like:
 
 ```
