--- a/langtools/src/jdk.jdeps/share/classes/com/sun/tools/jdeprscan/resources/jdeprscan.properties	Wed Mar 15 15:46:43 2017 +0100
+++ b/langtools/src/jdk.jdeps/share/classes/com/sun/tools/jdeprscan/resources/jdeprscan.properties	Wed Mar 15 13:02:54 2017 -0700
@@ -75,24 +75,52 @@
 
 scan.process.class=Processing class {0}...
 
+# The "removal tag": empty for normal deprecations,
+# nonempty for removal deprecations; do not translate.
 scan.dep.normal=
 scan.dep.removal=(forRemoval=true)
 
 scan.err.exception=error: unexpected exception {0}
 scan.err.noclass=error: cannot find class {0}
 scan.err.nofile=error: cannot find file {0}
+
+# 0: class name, 1: method name, 2: parameter and return types
 scan.err.nomethod=error: cannot resolve Methodref {0}.{1}:{2}
 
 scan.head.jar=Jar file {0}:
 scan.head.dir=Directory {0}:
 
+# In all of the messages below, 0 and 1 are as follows:
+#   0: type kind (class, interface, enum, or annotation type)
+#   1: type name
+# The last element is generally a "removal tag"; see above.
+
+# 2: class name, 3: removal tag
 scan.out.extends={0} {1} extends deprecated class {2} {3}
+
+# 2: interface name, 3: removal tag
 scan.out.implements={0} {1} implements deprecated interface {2} {3}
+
+# 2: class name, 3: removal tag
 scan.out.usesclass={0} {1} uses deprecated class {2} {3}
+
+# 2: class name, 3: method name, 4: method parameter and return types, 5: removal tag
 scan.out.usesmethod={0} {1} uses deprecated method {2}::{3}{4} {5}
+
+# 2: class name, 3: method name, 4: method parameter and return types, 5: removal tag
 scan.out.usesintfmethod={0} {1} uses deprecated method {2}::{3}{4} {5}
+
+# 2: class name, 3: field name, 4: removal tag
 scan.out.usesfield={0} {1} uses deprecated field {2}::{3} {4}
+
+# 2: field name, 3: type name, 4: removal tag
 scan.out.hasfield={0} {1} has field named {2} of deprecated type {3} {4}
+
+# 2: method name, 3: parameter type, 4: removal tag
 scan.out.methodparmtype={0} {1} has method named {2} having deprecated parameter type {3} {4}
+
+# 2: method name, 3: return type, 4: removal tag
 scan.out.methodrettype={0} {1} has method named {2} having deprecated return type {3} {4}
+
+# 2: class name, 3: method name, 4: method parameter and return types, 5: removal tag
 scan.out.methodoverride={0} {1} overrides deprecated method {2}::{3}{4} {5}