brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From drigod...@apache.org
Subject [5/9] brooklyn-server git commit: Improve config key descriptions
Date Fri, 15 Sep 2017 11:42:17 GMT
Improve config key descriptions

Also marks some most important config keys as ‘CatalogConfig’.

And fixes some deprecation warnings in ConfigKey declarations.


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-server/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-server/commit/3d62a1e1
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-server/tree/3d62a1e1
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-server/diff/3d62a1e1

Branch: refs/heads/master
Commit: 3d62a1e10bac478c3a7cb1610c54903b7ada83e0
Parents: 06c9f62
Author: Aled Sage <aled.sage@gmail.com>
Authored: Tue Sep 12 16:05:37 2017 +0100
Committer: Aled Sage <aled.sage@gmail.com>
Committed: Tue Sep 12 18:31:57 2017 +0100

----------------------------------------------------------------------
 .../brooklyn/core/entity/AbstractEntity.java    |   6 +-
 .../apache/brooklyn/core/entity/Attributes.java |  10 +-
 .../core/entity/BrooklynConfigKeys.java         | 110 ++++++++++++++-----
 .../enricher/stock/AbstractAggregator.java      |  37 +++++--
 .../enricher/stock/AbstractTransformer.java     |  22 ++--
 .../brooklyn/enricher/stock/Aggregator.java     |  15 ++-
 .../brooklyn/enricher/stock/Combiner.java       |  33 ++++--
 .../apache/brooklyn/enricher/stock/Joiner.java  |  17 ++-
 .../brooklyn/enricher/stock/MapAggregator.java  |  11 +-
 .../enricher/stock/PercentageEnricher.java      |   5 +-
 .../brooklyn/enricher/stock/Transformer.java    |  23 +++-
 .../brooklyn/enricher/stock/UpdatingMap.java    |  23 +++-
 .../YamlRollingTimeWindowMeanEnricher.java      |  13 ++-
 .../stock/YamlTimeWeightedDeltaEnricher.java    |   7 +-
 .../enricher/stock/reducer/Reducer.java         |  26 +++--
 .../brooklyn/entity/group/AbstractGroup.java    |   9 +-
 .../apache/brooklyn/entity/group/Cluster.java   |   2 +
 .../brooklyn/entity/group/DynamicCluster.java   |  21 +++-
 .../brooklyn/entity/group/DynamicFabric.java    |  12 +-
 .../brooklyn/entity/group/DynamicGroup.java     |   6 +-
 .../brooklyn/entity/stock/BasicStartable.java   |   6 +-
 .../brooklyn/entity/stock/DelegateEntity.java   |   7 +-
 .../policy/autoscaling/AutoScalerPolicy.java    |  21 +++-
 .../policy/ha/ConnectionFailureDetector.java    |  14 ++-
 .../policy/ha/ServiceFailureDetector.java       |  12 +-
 .../brooklyn/policy/ha/ServiceReplacer.java     |  20 +++-
 .../brooklyn/policy/ha/ServiceRestarter.java    |  16 ++-
 .../policy/ha/SshMachineFailureDetector.java    |   4 +-
 .../resources/EntityConfigResourceTest.java     |   2 +-
 .../apache/brooklyn/entity/java/UsesJava.java   |  10 +-
 .../apache/brooklyn/entity/java/UsesJmx.java    |  37 +++++--
 .../software/base/AbstractVanillaProcess.java   |  21 +++-
 .../entity/software/base/SoftwareProcess.java   |  37 ++++---
 .../software/base/SoftwareProcessImpl.java      |   1 -
 .../software/base/VanillaWindowsProcess.java    |  22 ++--
 35 files changed, 460 insertions(+), 178 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/core/entity/AbstractEntity.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/core/entity/AbstractEntity.java b/core/src/main/java/org/apache/brooklyn/core/entity/AbstractEntity.java
index 08b6591..9f9dc05 100644
--- a/core/src/main/java/org/apache/brooklyn/core/entity/AbstractEntity.java
+++ b/core/src/main/java/org/apache/brooklyn/core/entity/AbstractEntity.java
@@ -154,7 +154,11 @@ public abstract class AbstractEntity extends AbstractBrooklynObject implements E
     /**
      * The default name to use for this entity, if not explicitly overridden.
      */
-    public static final ConfigKey<String> DEFAULT_DISPLAY_NAME = BasicConfigKey.builder(String.class).name("defaultDisplayName").runtimeInheritance(BasicConfigInheritance.NEVER_INHERITED).build();
+    public static final ConfigKey<String> DEFAULT_DISPLAY_NAME = BasicConfigKey.builder(String.class)
+            .name("defaultDisplayName")
+            .description("Optional default display name to use (rather than auto-generating, if no name is explicitly supplied)")
+            .runtimeInheritance(BasicConfigInheritance.NEVER_INHERITED)
+            .build();
 
     public static final BasicNotificationSensor<Location> LOCATION_ADDED = new BasicNotificationSensor<Location>(
             Location.class, "entity.location.added", "Location dynamically added to entity");

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/core/entity/Attributes.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/core/entity/Attributes.java b/core/src/main/java/org/apache/brooklyn/core/entity/Attributes.java
index 02437ef..db2f07b 100644
--- a/core/src/main/java/org/apache/brooklyn/core/entity/Attributes.java
+++ b/core/src/main/java/org/apache/brooklyn/core/entity/Attributes.java
@@ -52,11 +52,15 @@ public interface Attributes {
 
     // TODO these should switch to being TemplatedStringAttributeSensorAndConfigKey
     BasicAttributeSensorAndConfigKey<String> DOWNLOAD_URL = new BasicAttributeSensorAndConfigKey<String>(
-            String.class, "download.url", "URL pattern for downloading the installer (will substitute things like ${version} automatically)");
+            String.class, 
+            "download.url", 
+            "URL pattern for downloading the installer (will substitute things like ${version} automatically)");
 
     @SuppressWarnings({ "unchecked", "rawtypes" })
     BasicAttributeSensorAndConfigKey<Map<String,String>> DOWNLOAD_ADDON_URLS = new BasicAttributeSensorAndConfigKey(
-            Map.class, "download.addon.urls", "URL patterns for downloading named add-ons (will substitute things like ${version} automatically)");
+            Map.class, 
+            "download.addon.urls", 
+            "URL patterns for downloading named add-ons (will substitute things like ${version} automatically)");
 
     /*
      * Port number attributes.
@@ -74,7 +78,7 @@ public interface Attributes {
             "http.port", "HTTP port", ImmutableList.of(8080,"18080+"));
     
     PortAttributeSensorAndConfigKey HTTPS_PORT = new PortAttributeSensorAndConfigKey(
-            "https.port", "HTTP port (with SSL/TLS)", ImmutableList.of(8443,"18443+"));
+            "https.port", "HTTPS port (with SSL/TLS)", ImmutableList.of(8443,"18443+"));
                     
     PortAttributeSensorAndConfigKey SSH_PORT = new PortAttributeSensorAndConfigKey("ssh.port", "SSH port", 22);
     PortAttributeSensorAndConfigKey SMTP_PORT = new PortAttributeSensorAndConfigKey("smtp.port", "SMTP port", 25);

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/core/entity/BrooklynConfigKeys.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/core/entity/BrooklynConfigKeys.java b/core/src/main/java/org/apache/brooklyn/core/entity/BrooklynConfigKeys.java
index e7b5e16..86ebbbf 100644
--- a/core/src/main/java/org/apache/brooklyn/core/entity/BrooklynConfigKeys.java
+++ b/core/src/main/java/org/apache/brooklyn/core/entity/BrooklynConfigKeys.java
@@ -18,7 +18,6 @@
  */
 package org.apache.brooklyn.core.entity;
 
-import static org.apache.brooklyn.core.config.ConfigKeys.newBooleanConfigKey;
 import static org.apache.brooklyn.core.config.ConfigKeys.newConfigKey;
 import static org.apache.brooklyn.core.config.ConfigKeys.newConfigKeyWithPrefix;
 import static org.apache.brooklyn.core.config.ConfigKeys.newStringConfigKey;
@@ -59,7 +58,9 @@ public class BrooklynConfigKeys {
             false);
 
     // TODO Rename to VERSION, instead of SUGGESTED_VERSION? And declare as BasicAttributeSensorAndConfigKey?
-    public static final ConfigKey<String> SUGGESTED_VERSION = newStringConfigKey("install.version", "Suggested version");
+    public static final ConfigKey<String> SUGGESTED_VERSION = newStringConfigKey(
+            "install.version", 
+            "The suggested version of the software to be installed");
 
     public static final ConfigKey<String> INSTALL_UNIQUE_LABEL = ConfigKeys.newStringConfigKey("install.unique_label",
             "Provides a label which uniquely identifies an installation, used in the computation of the install dir; " +
@@ -77,9 +78,12 @@ public class BrooklynConfigKeys {
      * If this key is set on a {@link Location} then all entities in that location will be treated in this way. This is useful
      * when the location is configured with a particular image containing installed and running services.
      *
-     * @see #ENTITY_RUNNING
+     * @see #SKIP_ENTITY_START_IF_RUNNING
      */
-    public static final ConfigKey<Boolean> SKIP_ENTITY_START = newBooleanConfigKey("entity.started", "Skip the startup process entirely, for running services");
+    public static final ConfigKey<Boolean> SKIP_ENTITY_START = ConfigKeys.builder(Boolean.class)
+            .name("entity.started") 
+            .description("Whether to skip the startup process entirely (useful for auto-running software, such as in containers)")
+            .build();
 
     /**
      * Set this configuration value to true to skip the entity startup process as with {@link #ENTITY_STARTED} if the process or
@@ -88,40 +92,46 @@ public class BrooklynConfigKeys {
      * <p>
      * If this key is set on a {@link Location} then all entities in that location will be treated in this way, again as with {@link #ENTITY_STARTED}.
      *
-     * @see #ENTITY_STARTED
+     * @see #SKIP_ENTITY_START
      */
-    public static final ConfigKey<Boolean> SKIP_ENTITY_START_IF_RUNNING = newBooleanConfigKey("entity.running", "Skip the startup process entirely, if service already running");
+    public static final ConfigKey<Boolean> SKIP_ENTITY_START_IF_RUNNING = ConfigKeys.builder(Boolean.class)
+            .name("entity.running") 
+            .description("Whether to skip the startup process entirely, but only if it already running")
+            .build();
 
     /**
-     * Set this configuration value to true if the entity installation, customization and launch process is to be skipped entirely.
+     * Set this configuration value to true if the entity installation is to be skipped entirely.
      * <p>
-     * This will skip the installation phase of the lifecycle, and move directl;y to customization and launching of the entity.
+     * This will skip the installation phase of the lifecycle, and move directly to customization and launching of the entity.
      */
-    public static final ConfigKey<Boolean> SKIP_ENTITY_INSTALLATION = newBooleanConfigKey("install.skip", "Skip the driver install commands entirely, for pre-installed software");
+    public static final ConfigKey<Boolean> SKIP_ENTITY_INSTALLATION = ConfigKeys.builder(Boolean.class)
+            .name("install.skip") 
+            .description("Whether to skip the install commands entirely (useful for pre-installed images)")
+            .build();
 
     // The implementation in AbstractSoftwareSshDriver runs this command as an SSH command 
     public static final ConfigKey<String> PRE_INSTALL_COMMAND = ConfigKeys.builder(String.class, "pre.install.command")
-            .description("Command to be run prior to the install method being called on the driver")
+            .description("Command to be run prior to the install phase")
             .runtimeInheritance(BasicConfigInheritance.NOT_REINHERITED)
             .build();
     public static final ConfigKey<String> POST_INSTALL_COMMAND = ConfigKeys.builder(String.class, "post.install.command")
-            .description("Command to be run after the install method being called on the driver")
+            .description("Command to be run after the install phase")
             .runtimeInheritance(BasicConfigInheritance.NOT_REINHERITED)
             .build();
     public static final ConfigKey<String> PRE_CUSTOMIZE_COMMAND = ConfigKeys.builder(String.class, "pre.customize.command")
-            .description("Command to be run prior to the customize method being called on the driver")
+            .description("Command to be run prior to the customize phase")
             .runtimeInheritance(BasicConfigInheritance.NOT_REINHERITED)
             .build();
     public static final ConfigKey<String> POST_CUSTOMIZE_COMMAND = ConfigKeys.builder(String.class, "post.customize.command")
-            .description("Command to be run after the customize method being called on the driver")
+            .description("Command to be run after the customize phase")
             .runtimeInheritance(BasicConfigInheritance.NOT_REINHERITED)
             .build();
     public static final ConfigKey<String> PRE_LAUNCH_COMMAND = ConfigKeys.builder(String.class, "pre.launch.command")
-            .description("Command to be run prior to the launch method being called on the driver")
+            .description("Command to be run prior to the launch phase")
             .runtimeInheritance(BasicConfigInheritance.NOT_REINHERITED)
             .build();
     public static final ConfigKey<String> POST_LAUNCH_COMMAND = ConfigKeys.builder(String.class, "post.launch.command")
-            .description("Command to be run after the launch method being called on the driver")
+            .description("Command to be run after the launch phase")
             .runtimeInheritance(BasicConfigInheritance.NOT_REINHERITED)
             .build();
 
@@ -133,7 +143,9 @@ public class BrooklynConfigKeys {
             .build();
 
     // TODO these dirs should also not be reinherited at runtime
-    public static final AttributeSensorAndConfigKey<String, String> INSTALL_DIR = new TemplatedStringAttributeSensorAndConfigKey("install.dir", "Directory for this software to be installed in",
+    public static final AttributeSensorAndConfigKey<String, String> INSTALL_DIR = new TemplatedStringAttributeSensorAndConfigKey(
+            "install.dir", 
+            "Directory in which this software will be installed (if downloading/unpacking artifacts explicitly); uses FreeMarker templating format",
             "${" +
             "config['"+ONBOX_BASE_DIR.getName()+"']!" +
             "config['"+BROOKLYN_DATA_DIR.getName()+"']!" +
@@ -151,7 +163,9 @@ public class BrooklynConfigKeys {
             "((config['install.version']??)?string('_'+(config['install.version']!'X'),''))" +
             ")}");
 
-    public static final AttributeSensorAndConfigKey<String, String> RUN_DIR = new TemplatedStringAttributeSensorAndConfigKey("run.dir", "Directory for this software to be run from",
+    public static final AttributeSensorAndConfigKey<String, String> RUN_DIR = new TemplatedStringAttributeSensorAndConfigKey(
+            "run.dir", 
+            "Directory from which this software to be run; uses FreeMarker templating format",
             "${" +
             "config['"+ONBOX_BASE_DIR.getName()+"']!" +
             "config['"+BROOKLYN_DATA_DIR.getName()+"']!" +
@@ -180,23 +194,59 @@ public class BrooklynConfigKeys {
      * component is up, but this entity does not care about the dependent component's actual config values.
      */
 
-    public static final ConfigKey<Boolean> PROVISION_LATCH = newBooleanConfigKey("provision.latch", "Latch for blocking location provision until ready");
-    public static final ConfigKey<Boolean> START_LATCH = newBooleanConfigKey("start.latch", "Latch for blocking start until ready");
+    public static final ConfigKey<Boolean> PROVISION_LATCH = ConfigKeys.builder(Boolean.class)
+            .name("provision.latch")
+            .description("Latch for blocking machine provisioning; if non-null will wait for this to resolve (normal use is with '$brooklyn:attributeWhenReady')")
+            .build();
+    public static final ConfigKey<Boolean> START_LATCH = ConfigKeys.builder(Boolean.class)
+            .name("start.latch")
+            .description("Latch for blocking start (done post-provisioning for software processes); if non-null will wait for this to resolve (normal use is with '$brooklyn:attributeWhenReady')")
+            .build();
 
     @Beta // on stop DSLs time out after a minute and unblock; may be easier to fix after https://github.com/apache/brooklyn-server/pull/390
-    public static final ConfigKey<Boolean> STOP_LATCH = newBooleanConfigKey("stop.latch", "Latch for blocking stop until a condition is met; will block for at most 1 minute and then time out");
+    public static final ConfigKey<Boolean> STOP_LATCH = ConfigKeys.builder(Boolean.class)
+            .name("stop.latch")
+            .description("Latch for blocking stop; if non-null will wait for at most 1 minute for this to resolve (normal use is with '$brooklyn:attributeWhenReady')")
+            .build();
 
-    public static final ConfigKey<Boolean> SETUP_LATCH = newBooleanConfigKey("setup.latch", "Latch for blocking setup until ready");
-    public static final ConfigKey<Boolean> PRE_INSTALL_RESOURCES_LATCH = newBooleanConfigKey("resources.preInstall.latch", "Latch for blocking pre-install resources until ready");
-    public static final ConfigKey<Boolean> INSTALL_RESOURCES_LATCH = newBooleanConfigKey("resources.install.latch", "Latch for blocking install resources until ready");
-    public static final ConfigKey<Boolean> INSTALL_LATCH = newBooleanConfigKey("install.latch", "Latch for blocking install until ready");
-    public static final ConfigKey<Boolean> RUNTIME_RESOURCES_LATCH = newBooleanConfigKey("resources.runtime.latch", "Latch for blocking runtime resources until ready");
-    public static final ConfigKey<Boolean> CUSTOMIZE_LATCH = newBooleanConfigKey("customize.latch", "Latch for blocking customize until ready");
-    public static final ConfigKey<Boolean> CUSTOMIZE_RESOURCES_LATCH = newBooleanConfigKey("resources.customize.latch", "Latch for blocking customize resources until ready");
-    public static final ConfigKey<Boolean> LAUNCH_LATCH = newBooleanConfigKey("launch.latch", "Latch for blocking launch until ready");
+    public static final ConfigKey<Boolean> SETUP_LATCH = ConfigKeys.builder(Boolean.class)
+            .name("setup.latch")
+            .description("Latch for blocking setup; if non-null will wait for this to resolve (normal use is with '$brooklyn:attributeWhenReady')")
+            .build();
+    
+    public static final ConfigKey<Boolean> PRE_INSTALL_RESOURCES_LATCH = ConfigKeys.builder(Boolean.class)
+            .name("resources.preInstall.latch")
+            .description("Latch for blocking files being copied before the pre-install; if non-null will wait for this to resolve (normal use is with '$brooklyn:attributeWhenReady')")
+            .build();
+    public static final ConfigKey<Boolean> INSTALL_RESOURCES_LATCH = ConfigKeys.builder(Boolean.class)
+            .name("resources.install.latch")
+            .description("Latch for blocking files being copied before the install; if non-null will wait for this to resolve (normal use is with '$brooklyn:attributeWhenReady')")
+            .build();
+    public static final ConfigKey<Boolean> INSTALL_LATCH = ConfigKeys.builder(Boolean.class)
+            .name("install.latch")
+            .description("Latch for blocking install; if non-null will wait for this to resolve (normal use is with '$brooklyn:attributeWhenReady')")
+            .build();
+    public static final ConfigKey<Boolean> CUSTOMIZE_RESOURCES_LATCH = ConfigKeys.builder(Boolean.class)
+            .name("resources.customize.latch")
+            .description("Latch for blocking files being copied before customize; if non-null will wait for this to resolve (normal use is with '$brooklyn:attributeWhenReady')")
+            .build();
+    public static final ConfigKey<Boolean> CUSTOMIZE_LATCH = ConfigKeys.builder(Boolean.class)
+            .name("customize.latch")
+            .description("Latch for blocking customize; if non-null will wait for this to resolve (normal use is with '$brooklyn:attributeWhenReady')")
+            .build();
+    public static final ConfigKey<Boolean> RUNTIME_RESOURCES_LATCH = ConfigKeys.builder(Boolean.class)
+            .name("resources.runtime.latch")
+            .description("Latch for blocking files being copied before the launch; if non-null will wait for this to resolve (normal use is with '$brooklyn:attributeWhenReady')")
+            .build();
+    public static final ConfigKey<Boolean> LAUNCH_LATCH = ConfigKeys.builder(Boolean.class)
+            .name("launch.latch")
+            .description("Latch for blocking luanch; if non-null will wait for this to resolve (normal use is with '$brooklyn:attributeWhenReady')")
+            .build();
 
     public static final ConfigKey<Duration> START_TIMEOUT = newConfigKey(
-            "start.timeout", "Time to wait for process and for SERVICE_UP before failing (in seconds, default 2m)", Duration.seconds(120));
+            "start.timeout", 
+            "Time to wait, after launching, for SERVICE_UP before failing (default to '2m')", 
+            Duration.seconds(120));
 
     /* selected properties from SshTool for external public access (e.g. putting on entities) */
 
@@ -241,7 +291,7 @@ public class BrooklynConfigKeys {
     public static final ConfigKey<Boolean> SSH_CONFIG_NO_DELETE_SCRIPT = newConfigKeyWithPrefix(BROOKLYN_SSH_CONFIG_KEY_PREFIX, ShellTool.PROP_NO_DELETE_SCRIPT);
 
     public static final MapConfigKey<Object> PROVISIONING_PROPERTIES = new MapConfigKey.Builder<Object>(Object.class, "provisioning.properties")
-            .description("Custom properties to be passed in when provisioning a new machine")
+            .description("Custom properties to be passed in to the location when provisioning a new machine")
             .defaultValue(ImmutableMap.<String, Object>of())
             .typeInheritance(BasicConfigInheritance.DEEP_MERGE)
             .runtimeInheritance(BasicConfigInheritance.NOT_REINHERITED_ELSE_DEEP_MERGE)

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/AbstractAggregator.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/AbstractAggregator.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/AbstractAggregator.java
index 92363e6..8e296ab 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/AbstractAggregator.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/AbstractAggregator.java
@@ -50,18 +50,26 @@ public abstract class AbstractAggregator<T,U> extends AbstractEnricher implement
 
     private static final Logger LOG = LoggerFactory.getLogger(AbstractAggregator.class);
 
-    public static final ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(Entity.class,
-            "enricher.producer", "The entity whose children/members will be aggregated");
+    public static final ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(
+            Entity.class,
+            "enricher.producer", 
+            "The entity whose children/members will be aggregated");
 
-    public static final ConfigKey<Sensor<?>> TARGET_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {},
-            "enricher.targetSensor");
+    public static final ConfigKey<Sensor<?>> TARGET_SENSOR = ConfigKeys.newConfigKey(
+            new TypeToken<Sensor<?>>() {},
+            "enricher.targetSensor",
+            "The sensor that will be set on the associated entity, with the target value");
 
     // FIXME this is not just for "members" i think -Alex
-    public static final ConfigKey<?> DEFAULT_MEMBER_VALUE = ConfigKeys.newConfigKey(Object.class,
-            "enricher.defaultMemberValue");
+    public static final ConfigKey<?> DEFAULT_MEMBER_VALUE = ConfigKeys.newConfigKey(
+            Object.class,
+            "enricher.defaultMemberValue",
+            "The value to use for a new producer if its source sensor is null");
 
-    public static final ConfigKey<Set<? extends Entity>> FROM_HARDCODED_PRODUCERS = ConfigKeys.newConfigKey(new TypeToken<Set<? extends Entity>>() {},
-            "enricher.aggregating.fromHardcodedProducers");
+    public static final ConfigKey<Set<? extends Entity>> FROM_HARDCODED_PRODUCERS = ConfigKeys.newConfigKey(
+            new TypeToken<Set<? extends Entity>>() {},
+            "enricher.aggregating.fromHardcodedProducers",
+            "The producers to be aggregated (this an alternative way of configuring it, rather than using members or children)");
 
     public static final ConfigKey<Boolean> FROM_MEMBERS = ConfigKeys.newBooleanConfigKey(
             "enricher.aggregating.fromMembers",
@@ -72,11 +80,16 @@ public abstract class AbstractAggregator<T,U> extends AbstractEnricher implement
             "enricher.aggregating.fromChildren",
             "Whether this enricher looks at children; this is the default for non-Group producers");
 
-    public static final ConfigKey<Predicate<? super Entity>> ENTITY_FILTER = ConfigKeys.newConfigKey(new TypeToken<Predicate<? super Entity>>() {},
-            "enricher.aggregating.entityFilter");
+    public static final ConfigKey<Predicate<? super Entity>> ENTITY_FILTER = ConfigKeys.newConfigKey(
+            new TypeToken<Predicate<? super Entity>>() {},
+            "enricher.aggregating.entityFilter",
+            "A filter of the possible producers");
 
-    public static final ConfigKey<Predicate<?>> VALUE_FILTER = ConfigKeys.newConfigKey(new TypeToken<Predicate<?>>() {},
-            "enricher.aggregating.valueFilter");
+    public static final ConfigKey<Predicate<?>> VALUE_FILTER = ConfigKeys.newConfigKey(
+            new TypeToken<Predicate<?>>() {},
+            "enricher.aggregating.valueFilter",
+            "A filter of the possible producers, based on their sensor value");
+    
     public static final ConfigKey<Boolean> EXCLUDE_BLANK = ConfigKeys.newBooleanConfigKey(
             "enricher.aggregator.excludeBlank",
             "Whether explicit nulls or blank strings should be excluded (default false); " +

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/AbstractTransformer.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/AbstractTransformer.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/AbstractTransformer.java
index 35138af..a53c297 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/AbstractTransformer.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/AbstractTransformer.java
@@ -45,14 +45,20 @@ public abstract class AbstractTransformer<T,U> extends AbstractEnricher implemen
 
     private static final Logger LOG = LoggerFactory.getLogger(AbstractTransformer.class);
 
-    public static final ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(Entity.class,
-            "enricher.producer");
-
-    public static final ConfigKey<Sensor<?>> SOURCE_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {},
-            "enricher.sourceSensor");
-
-    public static final ConfigKey<Sensor<?>> TARGET_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {},
-            "enricher.targetSensor");
+    public static final ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(
+            Entity.class,
+            "enricher.producer",
+            "The entity with the trigger sensor (defaults to the enricher's entity)");
+
+    public static final ConfigKey<Sensor<?>> SOURCE_SENSOR = ConfigKeys.newConfigKey(
+            new TypeToken<Sensor<?>>() {},
+            "enricher.sourceSensor",
+            "The sensor whose change triggers re-evaluation of the target value");
+
+    public static final ConfigKey<Sensor<?>> TARGET_SENSOR = ConfigKeys.newConfigKey(
+            new TypeToken<Sensor<?>>() {},
+            "enricher.targetSensor",
+            "The sensor that will be set on the associated entity, with the target value");
     
     public static final ConfigKey<List<? extends Sensor<?>>> TRIGGER_SENSORS = ConfigKeys.newConfigKey(
             new TypeToken<List<? extends Sensor<?>>>() {}, 

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/Aggregator.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/Aggregator.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/Aggregator.java
index f1a85fa..4f6c481 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/Aggregator.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/Aggregator.java
@@ -54,7 +54,8 @@ public class Aggregator<T,U> extends AbstractAggregator<T,U> implements SensorEv
     private static final Logger LOG = LoggerFactory.getLogger(Aggregator.class);
 
     public static final ConfigKey<Sensor<?>> SOURCE_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {},
-            "enricher.sourceSensor");
+            "enricher.sourceSensor",
+            "The sensor whose change triggers re-evaluation of the target value");
     
     @SetFromFlag("transformation")
     public static final ConfigKey<Object> TRANSFORMATION_UNTYPED = ConfigKeys.newConfigKey(Object.class,
@@ -65,18 +66,22 @@ public class Aggregator<T,U> extends AbstractAggregator<T,U> implements SensorEv
                     "'list' (the default, putting any collection of items into a list), " +
                     "or 'first' (the first value, or null if empty)");
 
-    public static final ConfigKey<Function<? super Collection<?>, ?>> TRANSFORMATION = ConfigKeys.newConfigKey(new TypeToken<Function<? super Collection<?>, ?>>() {},
-            "enricher.transformation");
+    public static final ConfigKey<Function<? super Collection<?>, ?>> TRANSFORMATION = ConfigKeys.newConfigKey(
+            new TypeToken<Function<? super Collection<?>, ?>>() {},
+            "enricher.transformation",
+            "A function to be executed to evaluate the target sensor");
     
     /**
      * @see QuorumChecks
      */
     public static final ConfigKey<String> QUORUM_CHECK_TYPE = ConfigKeys.newStringConfigKey(
-            "quorum.check.type", "The requirement to be considered quorate -- possible values: " +
+            "quorum.check.type", 
+            "The requirement to be considered quorate (used with transformation of type 'isQuorate') -- possible values: " +
                     "'all', 'allAndAtLeastOne', 'atLeastOne', 'atLeastOneUnlessEmpty', 'alwaysHealthy'", "allAndAtLeastOne");
 
     public static final ConfigKey<Integer> QUORUM_TOTAL_SIZE = ConfigKeys.newIntegerConfigKey(
-            "quorum.total.size", "The total size to consider when determining if quorate", 1);
+            "quorum.total.size", 
+            "The total size to consider when determining if quorate (used iwth transformation of type 'isQuorate')", 1);
 
     protected Sensor<T> sourceSensor;
     protected Function<? super Collection<T>, ? extends U> transformation;

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/Combiner.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/Combiner.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/Combiner.java
index 961e16a..f0ff358 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/Combiner.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/Combiner.java
@@ -55,15 +55,30 @@ public class Combiner<T,U> extends AbstractEnricher implements SensorEventListen
 
     private static final Logger LOG = LoggerFactory.getLogger(Combiner.class);
 
-    public static ConfigKey<Function<?, ?>> TRANSFORMATION = ConfigKeys.newConfigKey(new TypeToken<Function<?, ?>>() {}, "enricher.transformation");
-
-    public static ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(Entity.class, "enricher.producer");
-
-    public static ConfigKey<Set<Sensor<?>>> SOURCE_SENSORS = ConfigKeys.newConfigKey(new TypeToken<Set<Sensor<?>>>() {}, "enricher.sourceSensors");
-
-    public static ConfigKey<Sensor<?>> TARGET_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {}, "enricher.targetSensor");
-
-    public static final ConfigKey<Predicate<?>> VALUE_FILTER = ConfigKeys.newConfigKey(new TypeToken<Predicate<?>>() {}, "enricher.aggregating.valueFilter");
+    public static ConfigKey<Function<?, ?>> TRANSFORMATION = ConfigKeys.newConfigKey(
+            new TypeToken<Function<?, ?>>() {}, 
+            "enricher.transformation",
+            "The function to be applied, to combine the sensor values");
+
+    public static ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(
+            Entity.class, 
+            "enricher.producer",
+            "The entity that has the source sensors (defaults to the entity that the enricher is attached to)");
+
+    public static ConfigKey<Set<Sensor<?>>> SOURCE_SENSORS = ConfigKeys.newConfigKey(
+            new TypeToken<Set<Sensor<?>>>() {}, 
+            "enricher.sourceSensors",
+            "The source sensors to be combined");
+
+    public static ConfigKey<Sensor<?>> TARGET_SENSOR = ConfigKeys.newConfigKey(
+            new TypeToken<Sensor<?>>() {}, 
+            "enricher.targetSensor",
+            "The sensor that will be set on the associated entity, with the target value");
+
+    public static final ConfigKey<Predicate<?>> VALUE_FILTER = ConfigKeys.newConfigKey(
+            new TypeToken<Predicate<?>>() {}, 
+            "enricher.aggregating.valueFilter",
+            "A filter of the source sensors to include, based on their sensor values");
 
     protected Function<? super Collection<T>, ? extends U> transformation;
     protected Entity producer;

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/Joiner.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/Joiner.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/Joiner.java
index 51f599e..a456105 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/Joiner.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/Joiner.java
@@ -47,31 +47,42 @@ public class Joiner<T> extends AbstractEnricher implements SensorEventListener<T
     private static final Logger LOG = LoggerFactory.getLogger(Joiner.class);
 
     public static final ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(Entity.class,
-            "enricher.producer");
+            "enricher.producer",
+            "The entity that has the source sensors (defaults to the entity that the enricher is attached to)");
+    
     public static final ConfigKey<Sensor<?>> SOURCE_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {},
-            "enricher.sourceSensor");
+            "enricher.sourceSensor",
+            "The sensor (expected to be of type Map or Iterable) whose change triggers re-evaluation of the target value");
+    
     public static final ConfigKey<Sensor<?>> TARGET_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {},
-            "enricher.targetSensor");
+            "enricher.targetSensor",
+            "The sensor that will be set on the associated entity, with the target value");
+
     @SetFromFlag("separator")
     public static final ConfigKey<String> SEPARATOR = ConfigKeys.newStringConfigKey(
             "enricher.joiner.separator",
             "Separator string to insert between each argument", ",");
+    
     @SetFromFlag("keyValueSeparator")
     public static final ConfigKey<String> KEY_VALUE_SEPARATOR = ConfigKeys.newStringConfigKey(
             "enricher.joiner.keyValueSeparator",
             "Separator string to insert between each key-value pair", "=");
+    
     @SetFromFlag("joinMapEntries")
     public static final ConfigKey<Boolean> JOIN_MAP_ENTRIES = ConfigKeys.newBooleanConfigKey(
             "enricher.joiner.joinMapEntries",
             "Whether to add map entries as key-value pairs or just use the value, defaulting to false", false);
+    
     @SetFromFlag("quote")
     public static final ConfigKey<Boolean> QUOTE = ConfigKeys.newBooleanConfigKey(
             "enricher.joiner.quote",
             "Whether to bash-escape each parameter and wrap in double-quotes, defaulting to true", true);
+    
     @SetFromFlag("minimum")
     public static final ConfigKey<Integer> MINIMUM = ConfigKeys.newIntegerConfigKey(
             "enricher.joiner.minimum",
             "Minimum number of elements to join; if fewer than this, sets null; default 0 (no minimum)");
+    
     @SetFromFlag("maximum")
     public static final ConfigKey<Integer> MAXIMUM = ConfigKeys.newIntegerConfigKey(
             "enricher.joiner.maximum",

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/MapAggregator.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/MapAggregator.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/MapAggregator.java
index 8266f3b..a504f33 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/MapAggregator.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/MapAggregator.java
@@ -40,8 +40,15 @@ import org.apache.brooklyn.util.collections.MutableMap;
 @SuppressWarnings("serial")
 public class MapAggregator<U> extends AbstractMultipleSensorAggregator<U> {
 
-    public static final ConfigKey<Sensor<?>> KEY_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {}, "enricher.keySensor");
-    public static final ConfigKey<Sensor<?>> VALUE_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {}, "enricher.valueSensor");
+    public static final ConfigKey<Sensor<?>> KEY_SENSOR = ConfigKeys.newConfigKey(
+            new TypeToken<Sensor<?>>() {}, 
+            "enricher.keySensor",
+            "The sensor to use for the key in the map entry");
+    
+    public static final ConfigKey<Sensor<?>> VALUE_SENSOR = ConfigKeys.newConfigKey(
+            new TypeToken<Sensor<?>>() {}, 
+            "enricher.valueSensor",
+            "The sensor to use for the value in the map entry");
 
     private Sensor<?> keySensor;
     private Sensor<?> valueSensor;

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/PercentageEnricher.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/PercentageEnricher.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/PercentageEnricher.java
index f0ddb8e..b031b1c 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/PercentageEnricher.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/PercentageEnricher.java
@@ -69,7 +69,10 @@ public class PercentageEnricher extends AbstractEnricher implements SensorEventL
             "enricher.targetSensor",
             "The sensor on which to emit the ratio");
 
-    public static final ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(Entity.class, "enricher.producer");
+    public static final ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(
+            Entity.class, 
+            "enricher.producer",
+            "The entity with the trigger sensor (defaults to the enricher's entity)");
 
     protected AttributeSensor<? extends Number> sourceCurrentSensor;
     protected AttributeSensor<? extends Number> sourceTotalSensor;

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/Transformer.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/Transformer.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/Transformer.java
index ffd1fb6..ec10b97 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/Transformer.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/Transformer.java
@@ -21,6 +21,7 @@ package org.apache.brooklyn.enricher.stock;
 import static com.google.common.base.Preconditions.checkArgument;
 
 import org.apache.brooklyn.api.catalog.Catalog;
+import org.apache.brooklyn.api.catalog.CatalogConfig;
 import org.apache.brooklyn.api.sensor.Sensor;
 import org.apache.brooklyn.api.sensor.SensorEvent;
 import org.apache.brooklyn.config.ConfigKey;
@@ -42,12 +43,22 @@ public class Transformer<T,U> extends AbstractTransformer<T,U> {
     private static final Logger LOG = LoggerFactory.getLogger(Transformer.class);
 
     // exactly one of these should be supplied to set a value
-    public static final ConfigKey<Object> TARGET_VALUE = ConfigKeys.newConfigKey(Object.class,
-            "enricher.targetValue");
-    public static final ConfigKey<Function<?, ?>> TRANSFORMATION_FROM_VALUE = ConfigKeys.newConfigKey(new TypeToken<Function<?, ?>>() {},
-            "enricher.transformation");
-    public static final ConfigKey<Function<?, ?>> TRANSFORMATION_FROM_EVENT = ConfigKeys.newConfigKey(new TypeToken<Function<?, ?>>() {},
-            "enricher.transformation.fromevent");
+    @CatalogConfig(label = "Target value")
+    public static final ConfigKey<Object> TARGET_VALUE = ConfigKeys.newConfigKey(
+            Object.class,
+            "enricher.targetValue",
+            "The value for the target sensor. This can use the Brooklyn DSL, which will be "
+                    + "re-evaluated each time the trigger sensor(s) change");
+
+    public static final ConfigKey<Function<?, ?>> TRANSFORMATION_FROM_VALUE = ConfigKeys.newConfigKey(
+            new TypeToken<Function<?, ?>>() {},
+            "enricher.transformation",
+            "A function for computing the target sensor's new value (will be passed the trigger sensor's value each time)");
+
+    public static final ConfigKey<Function<?, ?>> TRANSFORMATION_FROM_EVENT = ConfigKeys.newConfigKey(
+            new TypeToken<Function<?, ?>>() {},
+            "enricher.transformation.fromevent",
+            "A function for computing the target sensor's new value (will be passed the trigger sensor's change-event each time)");
 
     public Transformer() { }
     

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/UpdatingMap.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/UpdatingMap.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/UpdatingMap.java
index acd4dbd..68a1ce6 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/UpdatingMap.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/UpdatingMap.java
@@ -66,22 +66,33 @@ public class UpdatingMap<S,TKey,TVal> extends AbstractEnricher implements Sensor
     private static final Logger LOG = LoggerFactory.getLogger(UpdatingMap.class);
 
     public static final ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(Entity.class,
-            "enricher.producer");
+            "enricher.producer",
+            "The entity with the trigger sensor (defaults to the enricher's entity)");
 
     @SetFromFlag("fromSensor")
-    public static final ConfigKey<Sensor<?>> SOURCE_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {}, "enricher.sourceSensor");
+    public static final ConfigKey<Sensor<?>> SOURCE_SENSOR = ConfigKeys.newConfigKey(
+            new TypeToken<Sensor<?>>() {}, 
+            "enricher.sourceSensor",
+            "The sensor whose change triggers re-evaluation of the target value");
     
     @SetFromFlag("targetSensor")
-    public static final ConfigKey<Sensor<?>> TARGET_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {}, "enricher.targetSensor");
+    public static final ConfigKey<Sensor<?>> TARGET_SENSOR = ConfigKeys.newConfigKey(
+            new TypeToken<Sensor<?>>() {}, 
+            "enricher.targetSensor",
+            "The map-sensor that will be updated on the associated entity");
+
     
     @SetFromFlag("key")
-    public static final ConfigKey<Object> KEY_IN_TARGET_SENSOR = ConfigKeys.newConfigKey(Object.class, "enricher.updatingMap.keyInTargetSensor",
-        "Key to update in the target sensor map, defaulting to the name of the source sensor");
+    public static final ConfigKey<Object> KEY_IN_TARGET_SENSOR = ConfigKeys.newConfigKey(
+            Object.class, 
+            "enricher.updatingMap.keyInTargetSensor",
+            "Key to update in the target sensor map, defaulting to the name of the source sensor");
 
     @SetFromFlag("computing")
     public static final ConfigKey<Function<?, ?>> COMPUTING = ConfigKeys.newConfigKey(
             new TypeToken<Function<?,?>>() {}, 
-            "enricher.updatingMap.computing");
+            "enricher.updatingMap.computing",
+            "The function to evaluate the value, which will to be set in the target map-sensor. See 'removingIfResultIsNull' for how null is handled.");
     
     @SetFromFlag("removingIfResultIsNull")
     public static final ConfigKey<Boolean> REMOVING_IF_RESULT_IS_NULL = ConfigKeys.newBooleanConfigKey(

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/YamlRollingTimeWindowMeanEnricher.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/YamlRollingTimeWindowMeanEnricher.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/YamlRollingTimeWindowMeanEnricher.java
index 6c51abd..4ba9fb2 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/YamlRollingTimeWindowMeanEnricher.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/YamlRollingTimeWindowMeanEnricher.java
@@ -57,11 +57,16 @@ import com.google.common.base.Function;
 @Catalog(name = "YAML Rolling Average", description = "Transforms sensor data into a rolling average based on a time window.")
 public class YamlRollingTimeWindowMeanEnricher<T extends Number> extends AbstractTransformer<T,Double> {
     
-    public static ConfigKey<Duration> WINDOW_DURATION = ConfigKeys.newConfigKey(Duration.class, "enricher.window.duration",
-        "Duration for which this window should store data, default one minute", Duration.ONE_MINUTE);
+    public static ConfigKey<Duration> WINDOW_DURATION = ConfigKeys.newConfigKey(
+            Duration.class, 
+            "enricher.window.duration",
+            "Duration for which this window should store data, default one minute", 
+            Duration.ONE_MINUTE);
 
-    public static ConfigKey<Double> CONFIDENCE_REQUIRED_TO_PUBLISH = ConfigKeys.newDoubleConfigKey("enricher.window.confidenceRequired",
-        "Minimum confidence level (ie period covered) required to publish a rolling average", 0.8d);
+    public static ConfigKey<Double> CONFIDENCE_REQUIRED_TO_PUBLISH = ConfigKeys.newDoubleConfigKey(
+            "enricher.window.confidenceRequired",
+            "Minimum confidence level (ie period covered) required to publish a rolling average", 
+            0.8d);
 
     public static class ConfidenceQualifiedNumber {
         final Double value;

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/YamlTimeWeightedDeltaEnricher.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/YamlTimeWeightedDeltaEnricher.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/YamlTimeWeightedDeltaEnricher.java
index dab8c8a..8052201 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/YamlTimeWeightedDeltaEnricher.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/YamlTimeWeightedDeltaEnricher.java
@@ -47,8 +47,11 @@ public class YamlTimeWeightedDeltaEnricher<T extends Number> extends AbstractTra
     Number lastValue;
     long lastTime = -1;
     
-    public static final ConfigKey<Duration> DELTA_PERIOD = ConfigKeys.newConfigKey(Duration.class, "enricher.delta.period",
-        "Duration that this delta should compute for, default per second", Duration.ONE_SECOND);
+    public static final ConfigKey<Duration> DELTA_PERIOD = ConfigKeys.newConfigKey(
+            Duration.class, 
+            "enricher.delta.period",
+            "Duration that this delta should compute for (default is one second)", 
+            Duration.ONE_SECOND);
     
     @Override
     public void setEntity(EntityLocal entity) {

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/enricher/stock/reducer/Reducer.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/enricher/stock/reducer/Reducer.java b/core/src/main/java/org/apache/brooklyn/enricher/stock/reducer/Reducer.java
index c24869d..ff0cd51 100644
--- a/core/src/main/java/org/apache/brooklyn/enricher/stock/reducer/Reducer.java
+++ b/core/src/main/java/org/apache/brooklyn/enricher/stock/reducer/Reducer.java
@@ -54,18 +54,30 @@ public class Reducer extends AbstractEnricher implements SensorEventListener<Obj
     private static final Logger LOG = LoggerFactory.getLogger(Reducer.class);
 
     @SetFromFlag("producer")
-    public static final ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(Entity.class,
-            "enricher.producer");
-    public static final ConfigKey<Sensor<?>> TARGET_SENSOR = ConfigKeys.newConfigKey(new TypeToken<Sensor<?>>() {},
-            "enricher.targetSensor");
-    public static final ConfigKey<List<? extends AttributeSensor<?>>> SOURCE_SENSORS = ConfigKeys.newConfigKey(new TypeToken<List<? extends AttributeSensor<?>>>() {},
-            "enricher.sourceSensors");
+    public static final ConfigKey<Entity> PRODUCER = ConfigKeys.newConfigKey(
+            Entity.class,
+            "enricher.producer",
+            "The entity with the trigger sensor (defaults to the enricher's entity)");
+    
+    public static final ConfigKey<Sensor<?>> TARGET_SENSOR = ConfigKeys.newConfigKey(
+            new TypeToken<Sensor<?>>() {},
+            "enricher.targetSensor",
+            "The sensor that will be set on the associated entity, with the target value");
+
+    public static final ConfigKey<List<? extends AttributeSensor<?>>> SOURCE_SENSORS = ConfigKeys.newConfigKey(
+            new TypeToken<List<? extends AttributeSensor<?>>>() {},
+            "enricher.sourceSensors",
+            "The sensors whose change triggers re-evaluation of the target value");
+
     public static final ConfigKey<Function<List<?>,?>> REDUCER_FUNCTION = ConfigKeys.newConfigKey(new TypeToken<Function<List<?>, ?>>() {},
-            "enricher.reducerFunction");
+            "enricher.reducerFunction",
+            "The function to execute to evaluate the target sensor value");
+    
     @SetFromFlag("transformation")
     public static final ConfigKey<String> REDUCER_FUNCTION_TRANSFORMATION = ConfigKeys.newStringConfigKey(
             "enricher.reducerFunction.transformation",
             "A string matching a pre-defined named reducer function, such as joiner, formatString, etc");
+    
     public static final ConfigKey<Map<String, Object>> PARAMETERS = ConfigKeys.newConfigKey(new TypeToken<Map<String, Object>>() {},
             "enricher.reducerFunction.parameters",
             "A map of parameters to pass into the reducer function");

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/entity/group/AbstractGroup.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/entity/group/AbstractGroup.java b/core/src/main/java/org/apache/brooklyn/entity/group/AbstractGroup.java
index 66d2d89..71ed88e 100644
--- a/core/src/main/java/org/apache/brooklyn/entity/group/AbstractGroup.java
+++ b/core/src/main/java/org/apache/brooklyn/entity/group/AbstractGroup.java
@@ -64,12 +64,15 @@ public interface AbstractGroup extends Entity, Group, Changeable {
             "group.members.delegate", "Deprecated: Add delegate child entities for members of the group", Boolean.FALSE);
 
     ConfigKey<String> MEMBER_DELEGATE_NAME_FORMAT = ConfigKeys.newStringConfigKey(
-            "group.members.delegate.nameFormat", "Delegate members name format string (Use %s for the original entity display name)", "%s");
+            "group.members.delegate.nameFormat", 
+            "Delegate members name format string (Use %s for the original entity display name)", 
+            "%s");
 
-    public static final ConfigKey<QuorumCheck> UP_QUORUM_CHECK = ConfigKeys.newConfigKeyWithDefault(ComputeServiceIndicatorsFromChildrenAndMembers.UP_QUORUM_CHECK, 
+    ConfigKey<QuorumCheck> UP_QUORUM_CHECK = ConfigKeys.newConfigKeyWithDefault(ComputeServiceIndicatorsFromChildrenAndMembers.UP_QUORUM_CHECK, 
         "Up check, applied by default to members, requiring at least one present and up",
         QuorumChecks.atLeastOne());
-    public static final ConfigKey<QuorumCheck> RUNNING_QUORUM_CHECK = ConfigKeys.newConfigKeyWithDefault(ComputeServiceIndicatorsFromChildrenAndMembers.RUNNING_QUORUM_CHECK,
+    
+    ConfigKey<QuorumCheck> RUNNING_QUORUM_CHECK = ConfigKeys.newConfigKeyWithDefault(ComputeServiceIndicatorsFromChildrenAndMembers.RUNNING_QUORUM_CHECK,
         "Problems check from children actual states (lifecycle), applied by default to members and children, not checking upness, but requiring by default that none are on-fire",
         QuorumChecks.all());
 

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/entity/group/Cluster.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/entity/group/Cluster.java b/core/src/main/java/org/apache/brooklyn/entity/group/Cluster.java
index 62f5471..bf64b26 100644
--- a/core/src/main/java/org/apache/brooklyn/entity/group/Cluster.java
+++ b/core/src/main/java/org/apache/brooklyn/entity/group/Cluster.java
@@ -18,6 +18,7 @@
  */
 package org.apache.brooklyn.entity.group;
 
+import org.apache.brooklyn.api.catalog.CatalogConfig;
 import org.apache.brooklyn.api.entity.Group;
 import org.apache.brooklyn.core.config.BasicConfigKey;
 import org.apache.brooklyn.core.entity.trait.Resizable;
@@ -29,6 +30,7 @@ import org.apache.brooklyn.util.core.flags.SetFromFlag;
  */
 public interface Cluster extends Group, Startable, Resizable {
     
+    @CatalogConfig(label = "Initial size")
     @SetFromFlag("initialSize")
     BasicConfigKey<Integer> INITIAL_SIZE = new BasicConfigKey<Integer>(
             Integer.class, "cluster.initial.size", "Initial cluster size", 1);

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/entity/group/DynamicCluster.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/entity/group/DynamicCluster.java b/core/src/main/java/org/apache/brooklyn/entity/group/DynamicCluster.java
index 59a28c3..2be07b0 100644
--- a/core/src/main/java/org/apache/brooklyn/entity/group/DynamicCluster.java
+++ b/core/src/main/java/org/apache/brooklyn/entity/group/DynamicCluster.java
@@ -25,6 +25,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
+import org.apache.brooklyn.api.catalog.CatalogConfig;
 import org.apache.brooklyn.api.entity.Entity;
 import org.apache.brooklyn.api.entity.EntitySpec;
 import org.apache.brooklyn.api.entity.Group;
@@ -103,13 +104,16 @@ public interface DynamicCluster extends AbstractGroup, Cluster, MemberReplaceabl
     ConfigKey<String> RESTART_MODE = ConfigKeys.newStringConfigKey(
             "dynamiccluster.restartMode", 
             "How this cluster should handle restarts; "
-            + "by default it is disallowed, but this key can specify a different mode. "
-            + "Modes supported by dynamic cluster are 'off', 'sequential', or 'parallel'. "
-            + "However subclasses can define their own modes or may ignore this.", null);
+                    + "by default it is disallowed, but this key can specify a different mode. "
+                    + "Modes supported by dynamic cluster are 'off', 'sequential', or 'parallel'. "
+                    + "However subclasses can define their own modes or may ignore this.", 
+            null);
 
     @SetFromFlag("quarantineFailedEntities")
     ConfigKey<Boolean> QUARANTINE_FAILED_ENTITIES = ConfigKeys.newBooleanConfigKey(
-            "dynamiccluster.quarantineFailedEntities", "If true, will quarantine entities that fail to start; if false, will get rid of them (i.e. delete them)", true);
+            "dynamiccluster.quarantineFailedEntities", 
+            "If true, will quarantine entities that fail to start; if false, will get rid of them (i.e. delete them)", 
+            true);
 
     @SetFromFlag("quarantineFilter")
     ConfigKey<Predicate<? super Throwable>> QUARANTINE_FILTER = ConfigKeys.newConfigKey(
@@ -132,6 +136,7 @@ public interface DynamicCluster extends AbstractGroup, Cluster, MemberReplaceabl
             "Initial cluster quorum size - number of initial nodes that must have been successfully started to report success (if < 0, then use value of INITIAL_SIZE)",
             -1);
 
+    @CatalogConfig(label = "Member spec")
     @SetFromFlag("memberSpec")
     ConfigKey<EntitySpec<?>> MEMBER_SPEC = ConfigKeys.newConfigKey(
             new TypeToken<EntitySpec<?>>() { },
@@ -140,7 +145,9 @@ public interface DynamicCluster extends AbstractGroup, Cluster, MemberReplaceabl
     @SetFromFlag("firstMemberSpec")
     ConfigKey<EntitySpec<?>> FIRST_MEMBER_SPEC = ConfigKeys.newConfigKey(
             new TypeToken<EntitySpec<?>>() { },
-            "dynamiccluster.firstmemberspec", "entity spec for creating new cluster members, used for the very first member if different", null);
+            "dynamiccluster.firstmemberspec", 
+            "entity spec for creating the first member of the cluster (if unset, will use the member spec for all)", 
+            null);
 
     @SetFromFlag("removalStrategy")
     ConfigKey<Function<Collection<Entity>, Entity>> REMOVAL_STRATEGY = ConfigKeys.newConfigKey(
@@ -183,7 +190,9 @@ public interface DynamicCluster extends AbstractGroup, Cluster, MemberReplaceabl
             "Time to wait (after members' start() effectors return) for SERVICE_UP before failing (default is not to wait)",
             null);
 
-    ConfigKey<Integer> MAX_SIZE = ConfigKeys.newIntegerConfigKey("cluster.max.size", "Size after which it will throw InsufficientCapacityException", Integer.MAX_VALUE);
+    ConfigKey<Integer> MAX_SIZE = ConfigKeys.newIntegerConfigKey("cluster.max.size", 
+            "Size after which it will throw InsufficientCapacityException", 
+            Integer.MAX_VALUE);
 
     @Beta
     @SetFromFlag("maxConcurrentChildCommands")

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/entity/group/DynamicFabric.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/entity/group/DynamicFabric.java b/core/src/main/java/org/apache/brooklyn/entity/group/DynamicFabric.java
index 2f50511..0b8e0b2 100644
--- a/core/src/main/java/org/apache/brooklyn/entity/group/DynamicFabric.java
+++ b/core/src/main/java/org/apache/brooklyn/entity/group/DynamicFabric.java
@@ -18,6 +18,7 @@
  */
 package org.apache.brooklyn.entity.group;
 
+import org.apache.brooklyn.api.catalog.CatalogConfig;
 import org.apache.brooklyn.api.entity.EntitySpec;
 import org.apache.brooklyn.api.entity.ImplementedBy;
 import org.apache.brooklyn.api.sensor.AttributeSensor;
@@ -50,13 +51,20 @@ public interface DynamicFabric extends AbstractGroup, Startable, Fabric {
                     + "for each given location).",
             true);
     
+    @CatalogConfig(label = "Member spec")
     @SetFromFlag("memberSpec")
     ConfigKey<EntitySpec<?>> MEMBER_SPEC = ConfigKeys.newConfigKey(
-            new TypeToken<EntitySpec<?>>() {}, "dynamiccfabric.memberspec", "entity spec for creating new cluster members", null);
+            new TypeToken<EntitySpec<?>>() {}, 
+            "dynamiccfabric.memberspec", 
+            "entity spec for creating new members (one per location)", 
+            null);
 
     @SetFromFlag("firstMemberSpec")
     ConfigKey<EntitySpec<?>> FIRST_MEMBER_SPEC = ConfigKeys.newConfigKey(
-            new TypeToken<EntitySpec<?>>() {}, "dynamiccfabric.firstmemberspec", "entity spec for creating new cluster members", null);
+            new TypeToken<EntitySpec<?>>() {}, 
+            "dynamiccfabric.firstmemberspec", 
+            "entity spec for the first member", 
+            null);
 
     @SetFromFlag("displayNamePrefix")
     ConfigKey<String> DISPLAY_NAME_PREFIX = ConfigKeys.newStringConfigKey(

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/entity/group/DynamicGroup.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/entity/group/DynamicGroup.java b/core/src/main/java/org/apache/brooklyn/entity/group/DynamicGroup.java
index 9ef1941..6b7f3a2 100644
--- a/core/src/main/java/org/apache/brooklyn/entity/group/DynamicGroup.java
+++ b/core/src/main/java/org/apache/brooklyn/entity/group/DynamicGroup.java
@@ -41,8 +41,10 @@ public interface DynamicGroup extends AbstractGroup {
 
     @SuppressWarnings("serial")
     @SetFromFlag("entityFilter")
-    ConfigKey<Predicate<? super Entity>> ENTITY_FILTER = ConfigKeys.newConfigKey(new TypeToken<Predicate<? super Entity>>() { },
-            "dynamicgroup.entityfilter", "Filter for entities which will automatically be in the group");
+    ConfigKey<Predicate<? super Entity>> ENTITY_FILTER = ConfigKeys.newConfigKey(
+            new TypeToken<Predicate<? super Entity>>() { },
+            "dynamicgroup.entityfilter", 
+            "Filter for entities which will automatically be in the group");
 
     AttributeSensor<Boolean> RUNNING = Sensors.newBooleanSensor(
             "dynamicgroup.running", "Whether the entity is running, and will automatically update group membership");

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/entity/stock/BasicStartable.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/entity/stock/BasicStartable.java b/core/src/main/java/org/apache/brooklyn/entity/stock/BasicStartable.java
index 1fc2721..c2263db 100644
--- a/core/src/main/java/org/apache/brooklyn/entity/stock/BasicStartable.java
+++ b/core/src/main/java/org/apache/brooklyn/entity/stock/BasicStartable.java
@@ -41,8 +41,10 @@ public interface BasicStartable extends Entity, Startable {
     @SetFromFlag("startLatch")
     ConfigKey<Boolean> START_LATCH = BrooklynConfigKeys.START_LATCH;
 
-    ConfigKey<Locations.LocationsFilter> LOCATIONS_FILTER = ConfigKeys.newConfigKey(Locations.LocationsFilter.class,
-            "brooklyn.locationsFilter", "Provides a hook for customizing locations to be used for a given context");
+    ConfigKey<Locations.LocationsFilter> LOCATIONS_FILTER = ConfigKeys.newConfigKey(
+            Locations.LocationsFilter.class,
+            "brooklyn.locationsFilter", 
+            "Provides a hook for customizing locations to be used for a given context");
 
     /** @deprecated since 0.7.0; use {@link Locations#LocationFilter} */
     @Deprecated

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/core/src/main/java/org/apache/brooklyn/entity/stock/DelegateEntity.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/brooklyn/entity/stock/DelegateEntity.java b/core/src/main/java/org/apache/brooklyn/entity/stock/DelegateEntity.java
index d4825a8..f228236 100644
--- a/core/src/main/java/org/apache/brooklyn/entity/stock/DelegateEntity.java
+++ b/core/src/main/java/org/apache/brooklyn/entity/stock/DelegateEntity.java
@@ -20,6 +20,7 @@ package org.apache.brooklyn.entity.stock;
 
 import java.util.concurrent.atomic.AtomicBoolean;
 
+import org.apache.brooklyn.api.catalog.CatalogConfig;
 import org.apache.brooklyn.api.entity.Entity;
 import org.apache.brooklyn.api.entity.Group;
 import org.apache.brooklyn.api.entity.ImplementedBy;
@@ -37,7 +38,11 @@ import com.google.common.base.Function;
 @ImplementedBy(DelegateEntityImpl.class)
 public interface DelegateEntity extends Entity {
 
-    AttributeSensorAndConfigKey<Entity, Entity> DELEGATE_ENTITY = ConfigKeys.newSensorAndConfigKey(Entity.class, "delegate.entity", "The delegate entity");
+    @CatalogConfig(label = "Delegate")
+    AttributeSensorAndConfigKey<Entity, Entity> DELEGATE_ENTITY = ConfigKeys.newSensorAndConfigKey(
+            Entity.class, 
+            "delegate.entity", 
+            "The delegate entity");
 
     AttributeSensor<String> DELEGATE_ENTITY_LINK = Sensors.newStringSensor("webapp.url", "The delegate entity link");
 

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/policy/src/main/java/org/apache/brooklyn/policy/autoscaling/AutoScalerPolicy.java
----------------------------------------------------------------------
diff --git a/policy/src/main/java/org/apache/brooklyn/policy/autoscaling/AutoScalerPolicy.java b/policy/src/main/java/org/apache/brooklyn/policy/autoscaling/AutoScalerPolicy.java
index a09c39d..0bcdd76 100644
--- a/policy/src/main/java/org/apache/brooklyn/policy/autoscaling/AutoScalerPolicy.java
+++ b/policy/src/main/java/org/apache/brooklyn/policy/autoscaling/AutoScalerPolicy.java
@@ -30,6 +30,7 @@ import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
 
 import org.apache.brooklyn.api.catalog.Catalog;
+import org.apache.brooklyn.api.catalog.CatalogConfig;
 import org.apache.brooklyn.api.entity.Entity;
 import org.apache.brooklyn.api.entity.EntityLocal;
 import org.apache.brooklyn.api.policy.PolicySpec;
@@ -264,10 +265,12 @@ public class AutoScalerPolicy extends AbstractPolicy {
     public static final String POOL_LOW_THRESHOLD_KEY = "pool.low.threshold";
     public static final String POOL_CURRENT_WORKRATE_KEY = "pool.current.workrate";
     
+    @CatalogConfig(label = "Metric")
     @SuppressWarnings("serial")
     @SetFromFlag("metric")
     public static final ConfigKey<AttributeSensor<? extends Number>> METRIC = BasicConfigKey.builder(new TypeToken<AttributeSensor<? extends Number>>() {})
             .name("autoscaler.metric")
+            .description("The (numeric) sensor to use for auto-scaling decisions, keeping it within the given bounds")
             .build();
 
     @SetFromFlag("entityWithMetric")
@@ -276,6 +279,7 @@ public class AutoScalerPolicy extends AbstractPolicy {
             .description("The Entity with the metric that will be monitored")
             .build();
     
+    @CatalogConfig(label = "Metric lower bound")
     @SetFromFlag("metricLowerBound")
     public static final ConfigKey<Number> METRIC_LOWER_BOUND = BasicConfigKey.builder(Number.class)
             .name("autoscaler.metricLowerBound")
@@ -283,6 +287,7 @@ public class AutoScalerPolicy extends AbstractPolicy {
             .reconfigurable(true)
             .build();
     
+    @CatalogConfig(label = "Metric upper bound")
     @SetFromFlag("metricUpperBound")
     public static final ConfigKey<Number> METRIC_UPPER_BOUND = BasicConfigKey.builder(Number.class)
             .name("autoscaler.metricUpperBound")
@@ -325,12 +330,15 @@ public class AutoScalerPolicy extends AbstractPolicy {
     @SetFromFlag("minPeriodBetweenExecs")
     public static final ConfigKey<Duration> MIN_PERIOD_BETWEEN_EXECS = BasicConfigKey.builder(Duration.class)
             .name("autoscaler.minPeriodBetweenExecs")
+            .description("When re-evaluating the desired size, wait at least this duration before computing")
             .defaultValue(Duration.millis(100))
             .build();
     
     @SetFromFlag("resizeUpStabilizationDelay")
     public static final ConfigKey<Duration> RESIZE_UP_STABILIZATION_DELAY = BasicConfigKey.builder(Duration.class)
             .name("autoscaler.resizeUpStabilizationDelay")
+            .description("The required duration of 'sustained load' before scaling up "
+                    + "(i.e. the length of time the metric must be above its upper bound before acting)")
             .defaultValue(Duration.ZERO)
             .reconfigurable(true)
             .build();
@@ -338,6 +346,8 @@ public class AutoScalerPolicy extends AbstractPolicy {
     @SetFromFlag("resizeDownStabilizationDelay")
     public static final ConfigKey<Duration> RESIZE_DOWN_STABILIZATION_DELAY = BasicConfigKey.builder(Duration.class)
             .name("autoscaler.resizeDownStabilizationDelay")
+            .description("The required duration of 'sustained low load' before scaling down "
+                    + "(i.e. the length of time the metric must be belowe its lower bound before acting)")
             .defaultValue(Duration.ZERO)
             .reconfigurable(true)
             .build();
@@ -345,6 +355,7 @@ public class AutoScalerPolicy extends AbstractPolicy {
     @SetFromFlag("minPoolSize")
     public static final ConfigKey<Integer> MIN_POOL_SIZE = BasicConfigKey.builder(Integer.class)
             .name("autoscaler.minPoolSize")
+            .description("The minimum acceptable pool size (never scaling down below this size, and automatically scaling up to this min size if required)")
             .defaultValue(1)
             .reconfigurable(true)
             .build();
@@ -352,12 +363,15 @@ public class AutoScalerPolicy extends AbstractPolicy {
     @SetFromFlag("maxPoolSize")
     public static final ConfigKey<Integer> MAX_POOL_SIZE = BasicConfigKey.builder(Integer.class)
             .name("autoscaler.maxPoolSize")
+            .description("The maximum acceptable pool size (never scaling up above this size, and automatically scaling down to this min size if required)")
             .defaultValue(Integer.MAX_VALUE)
             .reconfigurable(true)
             .build();
 
     public static final ConfigKey<Integer> INSUFFICIENT_CAPACITY_HIGH_WATER_MARK = BasicConfigKey.builder(Integer.class)
             .name("autoscaler.insufficientCapacityHighWaterMark")
+            .description("Level at which we either expect, or experienced, 'InsufficientCapacityException', "
+                    + "so should not attempt to go above this size. This is set automatically if that exception is hit.")
             .defaultValue(null)
             .reconfigurable(true)
             .build();
@@ -365,6 +379,7 @@ public class AutoScalerPolicy extends AbstractPolicy {
     @SetFromFlag("resizeOperator")
     public static final ConfigKey<ResizeOperator> RESIZE_OPERATOR = BasicConfigKey.builder(ResizeOperator.class)
             .name("autoscaler.resizeOperator")
+            .description("The operation to perform for resizing (defaults to calling resize(int) effector on a Resizable entity)")
             .defaultValue(new ResizeOperator() {
                     @Override
                     public Integer resize(Entity entity, Integer desiredSize) {
@@ -376,6 +391,7 @@ public class AutoScalerPolicy extends AbstractPolicy {
     @SetFromFlag("currentSizeOperator")
     public static final ConfigKey<Function<Entity,Integer>> CURRENT_SIZE_OPERATOR = BasicConfigKey.builder(new TypeToken<Function<Entity,Integer>>() {})
             .name("autoscaler.currentSizeOperator")
+            .description("The operation to perform to calculate the current size (defaults to calling getCurrentSize() on a Resizable entity)")
             .defaultValue(new Function<Entity,Integer>() {
                     @Override
                     public Integer apply(Entity entity) {
@@ -387,6 +403,7 @@ public class AutoScalerPolicy extends AbstractPolicy {
     @SetFromFlag("poolHotSensor")
     public static final ConfigKey<BasicNotificationSensor<? extends Map>> POOL_HOT_SENSOR = BasicConfigKey.builder(new TypeToken<BasicNotificationSensor<? extends Map>>() {})
             .name("autoscaler.poolHotSensor")
+            .description("Sensor to subscribe to, for 'pool hot' events. This is an alternative mechanism to keeping the 'metric' within a given range.")
             .defaultValue(DEFAULT_POOL_HOT_SENSOR)
             .build();
 
@@ -394,6 +411,7 @@ public class AutoScalerPolicy extends AbstractPolicy {
     @SetFromFlag("poolColdSensor")
     public static final ConfigKey<BasicNotificationSensor<? extends Map>> POOL_COLD_SENSOR = BasicConfigKey.builder(new TypeToken<BasicNotificationSensor<? extends Map>>() {})
             .name("autoscaler.poolColdSensor")
+            .description("Sensor to subscribe to, for 'pool cold' events. This is an alternative mechanism to keeping the 'metric' within a given range.")
             .defaultValue(DEFAULT_POOL_COLD_SENSOR)
             .build();
 
@@ -401,6 +419,7 @@ public class AutoScalerPolicy extends AbstractPolicy {
     @SetFromFlag("poolOkSensor")
     public static final ConfigKey<BasicNotificationSensor<? extends Map>> POOL_OK_SENSOR = BasicConfigKey.builder(new TypeToken<BasicNotificationSensor<? extends Map>>() {})
             .name("autoscaler.poolOkSensor")
+            .description("Sensor to subscribe to, for 'pool ok' events. This is an alternative mechanism to keeping the 'metric' within a given range.")
             .defaultValue(DEFAULT_POOL_OK_SENSOR)
             .build();
 
@@ -408,7 +427,7 @@ public class AutoScalerPolicy extends AbstractPolicy {
     @SetFromFlag("maxSizeReachedSensor")
     public static final ConfigKey<BasicNotificationSensor<? super MaxPoolSizeReachedEvent>> MAX_SIZE_REACHED_SENSOR = BasicConfigKey.builder(new TypeToken<BasicNotificationSensor<? super MaxPoolSizeReachedEvent>>() {})
             .name("autoscaler.maxSizeReachedSensor")
-            .description("Sensor for which a notification will be emitted (on the associated entity) when " +
+            .description("Sensor by which a notification will be emitted (on the associated entity) when " +
                     "we consistently wanted to resize the pool above the max allowed size, for " +
                     "maxReachedNotificationDelay milliseconds")
             .build();

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/policy/src/main/java/org/apache/brooklyn/policy/ha/ConnectionFailureDetector.java
----------------------------------------------------------------------
diff --git a/policy/src/main/java/org/apache/brooklyn/policy/ha/ConnectionFailureDetector.java b/policy/src/main/java/org/apache/brooklyn/policy/ha/ConnectionFailureDetector.java
index a844e00..623101c 100644
--- a/policy/src/main/java/org/apache/brooklyn/policy/ha/ConnectionFailureDetector.java
+++ b/policy/src/main/java/org/apache/brooklyn/policy/ha/ConnectionFailureDetector.java
@@ -40,9 +40,16 @@ import com.google.common.net.HostAndPort;
         + "emitting an event if the connection is lost/restored")
 public class ConnectionFailureDetector extends AbstractFailureDetector {
 
-    public static final ConfigKey<HostAndPort> ENDPOINT = ConfigKeys.newConfigKey(HostAndPort.class, "connectionFailureDetector.endpoint");
+    public static final ConfigKey<HostAndPort> ENDPOINT = ConfigKeys.newConfigKey(
+            HostAndPort.class, 
+            "connectionFailureDetector.endpoint",
+            "The host:port to be checked periodically");
 
-    public static final ConfigKey<Duration> POLL_PERIOD = ConfigKeys.newConfigKey(Duration.class, "connectionFailureDetector.pollPeriod", "", Duration.ONE_SECOND);
+    public static final ConfigKey<Duration> POLL_PERIOD = ConfigKeys.newConfigKey(
+            Duration.class, 
+            "connectionFailureDetector.pollPeriod", 
+            "The poll period for checking that the endpoint is reachable", 
+            Duration.ONE_SECOND);
 
     public static final BasicNotificationSensor<FailureDescriptor> CONNECTION_FAILED = HASensors.CONNECTION_FAILED;
 
@@ -61,7 +68,8 @@ public class ConnectionFailureDetector extends AbstractFailureDetector {
     @SetFromFlag("connectionRecoveredStabilizationDelay")
     public static final ConfigKey<Duration> CONNECTION_RECOVERED_STABILIZATION_DELAY = BasicConfigKey.builder(Duration.class)
             .name("connectionFailureDetector.serviceRecoveredStabilizationDelay")
-            .description("For a failed connection, time period for which the connection must be consistently up for (e.g. doesn't report up-down-up) before concluding recovered")
+            .description("For a failed connection, time period for which the connection must be consistently up for "
+                    + "(e.g. doesn't report up-down-up) before concluding recovered")
             .defaultValue(Duration.ZERO)
             .build();
 

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceFailureDetector.java
----------------------------------------------------------------------
diff --git a/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceFailureDetector.java b/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceFailureDetector.java
index 4cc0541..7b73072 100644
--- a/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceFailureDetector.java
+++ b/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceFailureDetector.java
@@ -75,11 +75,15 @@ public class ServiceFailureDetector extends ServiceStateLogic.ComputeServiceStat
     public static final BasicNotificationSensor<FailureDescriptor> ENTITY_FAILED = HASensors.ENTITY_FAILED;
 
     @SetFromFlag("onlyReportIfPreviouslyUp")
-    public static final ConfigKey<Boolean> ENTITY_FAILED_ONLY_IF_PREVIOUSLY_UP = ConfigKeys.newBooleanConfigKey("onlyReportIfPreviouslyUp", 
-        "Prevents the policy from emitting ENTITY_FAILED if the entity fails on startup (ie has never been up)", true);
+    public static final ConfigKey<Boolean> ENTITY_FAILED_ONLY_IF_PREVIOUSLY_UP = ConfigKeys.newBooleanConfigKey(
+            "onlyReportIfPreviouslyUp", 
+            "Prevents the policy from emitting ENTITY_FAILED if the entity fails on startup (ie has never been up)", 
+            true);
     
-    public static final ConfigKey<Boolean> MONITOR_SERVICE_PROBLEMS = ConfigKeys.newBooleanConfigKey("monitorServiceProblems", 
-        "Whether to monitor service problems, and emit on failures there (if set to false, this monitors only service up)", true);
+    public static final ConfigKey<Boolean> MONITOR_SERVICE_PROBLEMS = ConfigKeys.newBooleanConfigKey(
+            "monitorServiceProblems", 
+            "Whether to monitor service problems, and emit on failures there (if set to false, this monitors only service up)", 
+            true);
 
     @SetFromFlag("serviceOnFireStabilizationDelay")
     public static final ConfigKey<Duration> SERVICE_ON_FIRE_STABILIZATION_DELAY = BasicConfigKey.builder(Duration.class)

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceReplacer.java
----------------------------------------------------------------------
diff --git a/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceReplacer.java b/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceReplacer.java
index 9173895..9b83001 100644
--- a/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceReplacer.java
+++ b/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceReplacer.java
@@ -62,28 +62,38 @@ public class ServiceReplacer extends AbstractPolicy {
     // TODO if there are multiple failures perhaps we should abort quickly
     
     public static final BasicNotificationSensor<FailureDescriptor> ENTITY_REPLACEMENT_FAILED = new BasicNotificationSensor<FailureDescriptor>(
-            FailureDescriptor.class, "ha.entityFailed.replacement", "Indicates that an entity replacement attempt has failed");
+            FailureDescriptor.class, 
+            "ha.entityFailed.replacement", 
+            "Indicates that an entity replacement attempt has failed");
 
     @SetFromFlag("setOnFireOnFailure")
-    public static final ConfigKey<Boolean> SET_ON_FIRE_ON_FAILURE = ConfigKeys.newBooleanConfigKey("setOnFireOnFailure", "", true);
+    public static final ConfigKey<Boolean> SET_ON_FIRE_ON_FAILURE = ConfigKeys.newBooleanConfigKey(
+            "setOnFireOnFailure", 
+            "Whether to set the entity as 'ON_FIRE' when failure is detected", 
+            true);
     
     /** monitors this sensor, by default ENTITY_RESTART_FAILED */
     @SetFromFlag("failureSensorToMonitor")
     @SuppressWarnings("rawtypes")
-    public static final ConfigKey<Sensor> FAILURE_SENSOR_TO_MONITOR = new BasicConfigKey<Sensor>(Sensor.class, "failureSensorToMonitor", "", ServiceRestarter.ENTITY_RESTART_FAILED); 
+    public static final ConfigKey<Sensor> FAILURE_SENSOR_TO_MONITOR = new BasicConfigKey<Sensor>(
+            Sensor.class, 
+            "failureSensorToMonitor", 
+            "The sensor, emitted by an entity, used to trigger its replacement. Defaults to 'ha.entityFailed.restart' "
+                    + "(i.e. a 'ServiceRestarter' policy tried and failed to restart the entity)", 
+            ServiceRestarter.ENTITY_RESTART_FAILED); 
 
     /** skips replace if replacement has failed this many times failure re-occurs within this time interval */
     @SetFromFlag("failOnRecurringFailuresInThisDuration")
     public static final ConfigKey<Long> FAIL_ON_RECURRING_FAILURES_IN_THIS_DURATION = ConfigKeys.newLongConfigKey(
             "failOnRecurringFailuresInThisDuration", 
-            "abandon replace if replacement has failed many times within this time interval",
+            "Abandon replace if replacement has failed many times within this time interval",
             5*60*1000L);
 
     /** skips replace if replacement has failed this many times failure re-occurs within this time interval */
     @SetFromFlag("failOnNumRecurringFailures")
     public static final ConfigKey<Integer> FAIL_ON_NUM_RECURRING_FAILURES = ConfigKeys.newIntegerConfigKey(
             "failOnNumRecurringFailures", 
-            "abandon replace if replacement has failed this many times (100% of attempts) within the time interval",
+            "Abandon replace if replacement has failed this many times (100% of attempts) within the time interval",
             5);
 
     @SetFromFlag("ticker")

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceRestarter.java
----------------------------------------------------------------------
diff --git a/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceRestarter.java b/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceRestarter.java
index 03cae2e..2731308 100644
--- a/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceRestarter.java
+++ b/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceRestarter.java
@@ -57,7 +57,9 @@ public class ServiceRestarter extends AbstractPolicy {
     private static final Logger LOG = LoggerFactory.getLogger(ServiceRestarter.class);
 
     public static final BasicNotificationSensor<FailureDescriptor> ENTITY_RESTART_FAILED = new BasicNotificationSensor<FailureDescriptor>(
-            FailureDescriptor.class, "ha.entityFailed.restart", "Indicates that an entity restart attempt has failed");
+            FailureDescriptor.class, 
+            "ha.entityFailed.restart", 
+            "Indicates that an entity restart attempt has failed");
 
     /** skips retry if a failure re-occurs within this time interval */
     @SetFromFlag("failOnRecurringFailuresInThisDuration")
@@ -68,12 +70,20 @@ public class ServiceRestarter extends AbstractPolicy {
             Duration.minutes(3));
 
     @SetFromFlag("setOnFireOnFailure")
-    public static final ConfigKey<Boolean> SET_ON_FIRE_ON_FAILURE = ConfigKeys.newBooleanConfigKey("setOnFireOnFailure", "", true);
+    public static final ConfigKey<Boolean> SET_ON_FIRE_ON_FAILURE = ConfigKeys.newBooleanConfigKey(
+            "setOnFireOnFailure", 
+            "Whether to set the entity as 'ON_FIRE' if restart fails", 
+            true);
 
     /** monitors this sensor, by default ENTITY_FAILED */
     @SetFromFlag("failureSensorToMonitor")
     @SuppressWarnings({ "rawtypes", "unchecked" })
-    public static final ConfigKey<Sensor<?>> FAILURE_SENSOR_TO_MONITOR = (ConfigKey) ConfigKeys.newConfigKey(Sensor.class, "failureSensorToMonitor", "", HASensors.ENTITY_FAILED); 
+    public static final ConfigKey<Sensor<?>> FAILURE_SENSOR_TO_MONITOR = (ConfigKey) ConfigKeys.newConfigKey(
+            Sensor.class, 
+            "failureSensorToMonitor", 
+            "The sensor, emitted by an entity, used to trigger its restart. Defaults to 'ha.entityFailed' "
+                    + "(i.e. a 'ServiceFailureDetector' policy detected failure)", 
+            HASensors.ENTITY_FAILED); 
     
     protected final AtomicReference<Long> lastFailureTime = new AtomicReference<Long>();
 

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/policy/src/main/java/org/apache/brooklyn/policy/ha/SshMachineFailureDetector.java
----------------------------------------------------------------------
diff --git a/policy/src/main/java/org/apache/brooklyn/policy/ha/SshMachineFailureDetector.java b/policy/src/main/java/org/apache/brooklyn/policy/ha/SshMachineFailureDetector.java
index bd5738b..b5678aa 100644
--- a/policy/src/main/java/org/apache/brooklyn/policy/ha/SshMachineFailureDetector.java
+++ b/policy/src/main/java/org/apache/brooklyn/policy/ha/SshMachineFailureDetector.java
@@ -48,7 +48,9 @@ public class SshMachineFailureDetector extends AbstractFailureDetector {
     public static final BasicNotificationSensor<FailureDescriptor> CONNECTION_RECOVERED = HASensors.CONNECTION_RECOVERED;
 
     public static final ConfigKey<Duration> CONNECT_TIMEOUT = ConfigKeys.newDurationConfigKey(
-            "ha.sshConnection.timeout", "How long to wait for conneciton before declaring failure", Duration.TEN_SECONDS);
+            "ha.sshConnection.timeout", 
+            "How long to wait for conneciton before declaring failure", 
+            Duration.TEN_SECONDS);
 
     @Override
     public void init() {

http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/3d62a1e1/rest/rest-resources/src/test/java/org/apache/brooklyn/rest/resources/EntityConfigResourceTest.java
----------------------------------------------------------------------
diff --git a/rest/rest-resources/src/test/java/org/apache/brooklyn/rest/resources/EntityConfigResourceTest.java b/rest/rest-resources/src/test/java/org/apache/brooklyn/rest/resources/EntityConfigResourceTest.java
index a800ed2..49b3651 100644
--- a/rest/rest-resources/src/test/java/org/apache/brooklyn/rest/resources/EntityConfigResourceTest.java
+++ b/rest/rest-resources/src/test/java/org/apache/brooklyn/rest/resources/EntityConfigResourceTest.java
@@ -97,7 +97,7 @@ public class EntityConfigResourceTest extends BrooklynRestResourceTest {
         assertTrue(configKeyOptional.isPresent());
         
         assertEquals(configKeyOptional.get().getType(), "java.lang.String");
-        assertEquals(configKeyOptional.get().getDescription(), "Suggested version");
+        assertEquals(configKeyOptional.get().getDescription(), "The suggested version of the software to be installed");
         assertFalse(configKeyOptional.get().isReconfigurable());
         assertNull(configKeyOptional.get().getDefaultValue());
         assertNull(configKeyOptional.get().getLabel());


Mime
View raw message