allow marking a config item as :deprecated

docs/docgen.rb

@@ -66,6 +66,9 @@ class LogStashConfigDocGenerator
   end # def add_comment
 
   def add_config(code)
+    # trim off any possible multiline lamdas for a :validate
+    code.sub!(/, *:validate => \(lambda.*$/, '')
+
     # call the code, which calls 'config' in this class.
     # This will let us align comments with config options.
     name, opts = eval(code)
@@ -84,7 +87,7 @@ class LogStashConfigDocGenerator
     name, description = eval(fixed_code)
     @flags[name] = description
     clear_comments
-  end # def add_config
+  end # def add_flag
 
   def set_config_name(code)
     name = eval(code)

docs/docs.html.erb

@@ -29,6 +29,7 @@ This is what it might look like in your config file:
 <%= section %> {
   <%= name %> {
 <% sorted_settings.each do |setting_name, config|
+     next if config[:deprecated]
      if config[:validate].is_a?(Array) 
        annotation = "#{config[:validate].inspect}"
      else 
@@ -49,10 +50,14 @@ This is what it might look like in your config file:
 <h4> 
   <a name="setting_<%= setting_name %>">
     <%= setting_name %><%= " (required setting)" if config[:required] %>
+    <%= " <strong>DEPRECATED</strong>" if config[:deprecated] %>
 </a>
 </h4>
 
 <ul>
+<% if config[:deprecated] -%>
+  <li> DEPRECATED WARNING: This config item is deprecated. It may be removed in a further version. </li>
+<% end -%>
 <% if config[:validate].is_a?(Symbol) -%>
   <li> Value type is <%= config[:validate] %> </li>
 <% elsif config[:validate].nil? -%>

lib/logstash/config/mixin.rb

@@ -48,6 +48,15 @@ module LogStash::Config::Mixin
       exit 1
     end
 
+    # warn about deprecated variable use
+    params.each do |name, value|
+      opts = self.class.get_config[name]
+      if opts[:deprecated]
+        @logger.warn("Deprecated config item #{name.inspect} set " +
+                     "in #{self.class.name}")
+      end
+    end
+
     # Set defaults from 'config :foo, :default => somevalue'
     self.class.get_config.each do |name, opts|
       next if params.include?(name.to_s)