From e19833171ba22931742ed1216aa811eec69af013 Mon Sep 17 00:00:00 2001
From: Simon Willnauer <simonw@apache.org>
Date: Thu, 4 Feb 2016 11:39:44 +0100
Subject: [PATCH] Add more javadocs to Setting.java

---
 .../common/settings/Setting.java              | 22 ++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/core/src/main/java/org/elasticsearch/common/settings/Setting.java b/core/src/main/java/org/elasticsearch/common/settings/Setting.java
index 5c208e7e188..17d670b254a 100644
--- a/core/src/main/java/org/elasticsearch/common/settings/Setting.java
+++ b/core/src/main/java/org/elasticsearch/common/settings/Setting.java
@@ -46,6 +46,24 @@ import java.util.stream.Collectors;
 /**
  * A setting. Encapsulates typical stuff like default value, parsing, and scope.
  * Some (dynamic=true) can by modified at run time using the API.
+ * All settings inside elasticsearch or in any of the plugins should use this type-safe and generic settings infrastructure
+ * together with {@link AbstractScopedSettings}. This class contains several untility methods that makes it straight forward
+ * to add settings for the majority of the cases. For instance a simple boolean settings can be defined like this:
+ * <pre>{@code
+ * public static final Setting<Boolean>; MY_BOOLEAN = Setting.boolSetting("my.bool.setting", true, false, Scope.CLUSTER);}
+ * </pre>
+ * To retrieve the value of the setting a {@link Settings} object can be passed directly to the {@link Setting#get(Settings)} method.
+ * <pre>
+ * final boolean myBooleanValue = MY_BOOLEAN.get(settings);
+ * </pre>
+ * It's recommended to use typed settings rather than string based settings. For example adding a setting for an enum type:
+ * <pre>{@code
+ * public enum Color {
+ *     RED, GREEN, BLUE;
+ * }
+ * public static final Setting<Color> MY_BOOLEAN = new Setting<>("my.color.setting", Color.RED.toString(), Color::valueOf, false, Scope.CLUSTER);
+ * }
+ * </pre>
  */
 public class Setting<T> extends ToXContentToBytes {
     private final String key;
@@ -84,7 +102,9 @@ public class Setting<T> extends ToXContentToBytes {
     }
 
     /**
-     * Returns the settings key or a prefix if this setting is a group setting
+     * Returns the settings key or a prefix if this setting is a group setting.
+     * <b>Note: this method should not be used to retrieve a value from a {@link Settings} object.
+     * Use {@link #get(Settings)} instead</b>
      *
      * @see #isGroupSetting()
      */