From 793877d93abb59004cc2028d3c15c5a599f39dac Mon Sep 17 00:00:00 2001
From: Gian Merlino <gianmerlino@gmail.com>
Date: Fri, 6 Nov 2015 14:36:11 -0800
Subject: [PATCH] Parser interface docs.

---
 .../com/metamx/common/parsers/Parser.java     | 25 +++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/main/java/com/metamx/common/parsers/Parser.java b/src/main/java/com/metamx/common/parsers/Parser.java
index 88ca04c8..7b95edc3 100644
--- a/src/main/java/com/metamx/common/parsers/Parser.java
+++ b/src/main/java/com/metamx/common/parsers/Parser.java
@@ -20,9 +20,30 @@
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * Class that can parse Strings into Maps.
+ */
 public interface Parser<K, V>
 {
-  public Map<K, V> parse(String input) ;
-  public void setFieldNames(Iterable<String> fieldNames) ;
+  /**
+   * Parse a String into a Map.
+   *
+   * @throws ParseException if the String cannot be parsed
+   */
+  public Map<K, V> parse(String input);
+
+  /**
+   * Set the fieldNames that you expect to see in parsed Maps. Deprecated; Parsers should not, in general, be
+   * expected to know what fields they will return. Some individual types of parsers do need to know (like a TSV
+   * parser) and those parsers have their own way of setting field names.
+   */
+  @Deprecated
+  public void setFieldNames(Iterable<String> fieldNames);
+
+  /**
+   * Returns the fieldNames that we expect to see in parsed Maps, if known, or null otherwise. Deprecated; Parsers
+   * should not, in general, be expected to know what fields they will return.
+   */
+  @Deprecated
   public List<String> getFieldNames();
 }