From 181824bbf05bbadf29f0a35ac81bf54f64aa7569 Mon Sep 17 00:00:00 2001
From: Alex Heneveld <alex.heneveld@cloudsoftcorp.com>
Date: Fri, 18 May 2012 21:36:22 +0100
Subject: [PATCH] javadoc to clarify options additivity

---
 .../java/org/jclouds/compute/domain/TemplateBuilder.java   | 6 ++++--
 .../java/org/jclouds/compute/options/TemplateOptions.java  | 7 ++++++-
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/compute/src/main/java/org/jclouds/compute/domain/TemplateBuilder.java b/compute/src/main/java/org/jclouds/compute/domain/TemplateBuilder.java
index 69251b70b7..853363645c 100644
--- a/compute/src/main/java/org/jclouds/compute/domain/TemplateBuilder.java
+++ b/compute/src/main/java/org/jclouds/compute/domain/TemplateBuilder.java
@@ -162,8 +162,10 @@ public interface TemplateBuilder {
    Template build();
 
    /**
-    * options such as inbound ports and run scripts.
+    * Sets options on the template (i.e. items which adorn a created node rather than restricting selection of the node).
+    * Note that this method typically replaces any options previously specified in the builder.
+    * Normal usage is to build up all options and pass them to the builder with a single call to this method.
     */
    TemplateBuilder options(TemplateOptions options);
 
-}
\ No newline at end of file
+}
diff --git a/compute/src/main/java/org/jclouds/compute/options/TemplateOptions.java b/compute/src/main/java/org/jclouds/compute/options/TemplateOptions.java
index b08828bd25..2ff19be5ca 100644
--- a/compute/src/main/java/org/jclouds/compute/options/TemplateOptions.java
+++ b/compute/src/main/java/org/jclouds/compute/options/TemplateOptions.java
@@ -43,7 +43,7 @@ import com.google.common.primitives.Ints;
  * operation. <h2>
  * Usage</h2> The recommended way to instantiate a TemplateOptions object is to
  * statically import TemplateOptions.* and invoke a static creation method
- * followed by an instance mutator (if needed):
+ * followed by any/all desired instance mutators.
  * <p/>
  * <code>
  * import static org.jclouds.compute.options.TemplateOptions.Builder.*;
@@ -52,6 +52,11 @@ import com.google.common.primitives.Ints;
  * templateBuilder.options(inboundPorts(22, 80, 8080, 443));
  * Set<? extends NodeMetadata> set = client.createNodesInGroup(tag, 2, templateBuilder.build());
  * <code>
+ * <p/>
+ * Note that options can only be assigned to a builder once, so if assigning e.g. inboundPorts and tags,
+ * that must be done in with mutators in a single call to options --
+ * <code>templateBuilder.options(inboundPorts(22, 80, 8080, 443).tags("I love it!"))</code>
+ * -- not as repeated calls to <code>options</code>.
  * 
  * @author Adrian Cole
  */