diff --git a/src/main/java/org/sablecc/sablecc/analysis/Analysis.java b/src/main/java/org/sablecc/sablecc/analysis/Analysis.java
index bd6623f34ce80085653286105b10c091fb537cab..999e37aa76d901764bba0d5d048dbe255ea3fadd 100644
--- a/src/main/java/org/sablecc/sablecc/analysis/Analysis.java
+++ b/src/main/java/org/sablecc/sablecc/analysis/Analysis.java
@@ -7,24 +7,32 @@ import org.sablecc.sablecc.node.*;
 public interface Analysis extends Switch
 {
     /**
+     * @param node the node for which to look up the associated object
+     * @return the corresponding object previously associated using {@link #setIn(Node, Object)}, or {@code null} if there is none
      * @deprecated If you need a map field, declare it yourself.
      */
     @Deprecated
     Object getIn(Node node);
 
     /**
+     * @param node the node with which to associate the given object
+     * @param o the object to associate with the node
      * @deprecated If you need a map field, declare it yourself.
      */
     @Deprecated
     void setIn(Node node, Object o);
 
     /**
+     * @param node the node for which to look up the associated object
+     * @return the corresponding object previously associated using {@link #setOut(Node, Object)}, or {@code null} if there is none
      * @deprecated If you need a map field, declare it yourself.
      */
     @Deprecated
     Object getOut(Node node);
 
     /**
+     * @param node the node with which to associate the given object
+     * @param o the object to associate with the node
      * @deprecated If you need a map field, declare it yourself.
      */
     @Deprecated
diff --git a/src/main/java/org/sablecc/sablecc/analysis/AnalysisAdapter.java b/src/main/java/org/sablecc/sablecc/analysis/AnalysisAdapter.java
index 9a756d94c1735dc12b47ac2104c3306eaa20ff8d..c07b2600c60eb1a18f3fef46da7b244d42d8e74a 100644
--- a/src/main/java/org/sablecc/sablecc/analysis/AnalysisAdapter.java
+++ b/src/main/java/org/sablecc/sablecc/analysis/AnalysisAdapter.java
@@ -19,9 +19,6 @@ public class AnalysisAdapter implements Analysis
     @Deprecated
     private Hashtable<Node,Object> out;
 
-    /**
-     * @deprecated If you need a map field, declare it yourself.
-     */
     @Deprecated
     @Override
     public Object getIn(Node node)
@@ -34,9 +31,6 @@ public class AnalysisAdapter implements Analysis
         return this.in.get(node);
     }
 
-    /**
-     * @deprecated If you need a map field, declare it yourself.
-     */
     @Deprecated
     @Override
     public void setIn(Node node, Object o)
@@ -56,9 +50,6 @@ public class AnalysisAdapter implements Analysis
         }
     }
 
-    /**
-     * @deprecated If you need a map field, declare it yourself.
-     */
     @Deprecated
     @Override
     public Object getOut(Node node)
@@ -71,9 +62,6 @@ public class AnalysisAdapter implements Analysis
         return this.out.get(node);
     }
 
-    /**
-     * @deprecated If you need a map field, declare it yourself.
-     */
     @Deprecated
     @Override
     public void setOut(Node node, Object o)
diff --git a/src/main/java/org/sablecc/sablecc/parser/Parser.java b/src/main/java/org/sablecc/sablecc/parser/Parser.java
index aadf7435f6aceccef7955e225392839b594c6d00..c9535dfa6f49dd99abe9764e6e84e6094d3f2a5a 100644
--- a/src/main/java/org/sablecc/sablecc/parser/Parser.java
+++ b/src/main/java/org/sablecc/sablecc/parser/Parser.java
@@ -146,6 +146,8 @@ public class Parser implements IParser
     }
 
     /**
+     * @param productionRuleAsString internal name of the production rule in question
+     * @return {@code false} if creation of a new list should be skipped, {@code true} for default behavior
      * @deprecated Overriding this method no longer has any effect. This optimization is now applied automatically iff it is safe.
      */
     @Deprecated
diff --git a/src/main/resources/org/sablecc/sablecc/analyses.txt b/src/main/resources/org/sablecc/sablecc/analyses.txt
index f7c37c0826aa1b0b0a0d42521e32f4b83c8038cd..4a316079af302c480ee5a8f21a58d2a4215dfb89 100644
--- a/src/main/resources/org/sablecc/sablecc/analyses.txt
+++ b/src/main/resources/org/sablecc/sablecc/analyses.txt
@@ -15,24 +15,32 @@ import $1$.*;
 public interface Analysis extends Switch
 {
     /**
+     * @param node the node for which to look up the associated object
+     * @return the corresponding object previously associated using {@link #setIn(Node, Object)}, or {@code null} if there is none
      * @deprecated If you need a map field, declare it yourself.
      */
     @Deprecated
     Object getIn(Node node);
 
     /**
+     * @param node the node with which to associate the given object
+     * @param o the object to associate with the node
      * @deprecated If you need a map field, declare it yourself.
      */
     @Deprecated
     void setIn(Node node, Object o);
 
     /**
+     * @param node the node for which to look up the associated object
+     * @return the corresponding object previously associated using {@link #setOut(Node, Object)}, or {@code null} if there is none
      * @deprecated If you need a map field, declare it yourself.
      */
     @Deprecated
     Object getOut(Node node);
 
     /**
+     * @param node the node with which to associate the given object
+     * @param o the object to associate with the node
      * @deprecated If you need a map field, declare it yourself.
      */
     @Deprecated
@@ -78,9 +86,6 @@ public class AnalysisAdapter implements Analysis
     @Deprecated
     private Hashtable<Node,Object> out;
 
-    /**
-     * @deprecated If you need a map field, declare it yourself.
-     */
     @Deprecated
     @Override
     public Object getIn(Node node)
@@ -93,9 +98,6 @@ public class AnalysisAdapter implements Analysis
         return this.in.get(node);
     }
 
-    /**
-     * @deprecated If you need a map field, declare it yourself.
-     */
     @Deprecated
     @Override
     public void setIn(Node node, Object o)
@@ -115,9 +117,6 @@ public class AnalysisAdapter implements Analysis
         }
     }
 
-    /**
-     * @deprecated If you need a map field, declare it yourself.
-     */
     @Deprecated
     @Override
     public Object getOut(Node node)
@@ -130,9 +129,6 @@ public class AnalysisAdapter implements Analysis
         return this.out.get(node);
     }
 
-    /**
-     * @deprecated If you need a map field, declare it yourself.
-     */
     @Deprecated
     @Override
     public void setOut(Node node, Object o)
diff --git a/src/main/resources/org/sablecc/sablecc/parser.txt b/src/main/resources/org/sablecc/sablecc/parser.txt
index d6d876b18ead8e26bf711fa9d343eb7fc296c64f..e24642dd9c693de1b61f505c08586fdaba81ff72 100644
--- a/src/main/resources/org/sablecc/sablecc/parser.txt
+++ b/src/main/resources/org/sablecc/sablecc/parser.txt
@@ -154,6 +154,8 @@ public class Parser implements IParser
     }
 
     /**
+     * @param productionRuleAsString internal name of the production rule in question
+     * @return {@code false} if creation of a new list should be skipped, {@code true} for default behavior
      * @deprecated Overriding this method no longer has any effect. This optimization is now applied automatically iff it is safe.
      */
     @Deprecated