[#181] Document :superseded-by

Author: bbatsov

README.adoc

@@ -1928,6 +1928,37 @@ TIP: If you're into SemVer, it's a good idea to omit the patch version.
 This means you should use `0.5` instead of `0.5.0`. This applies
 for all metadata data that's version related.
 
+=== `:superseded-by`
+
+Often you'd combine `:deprecated` with `:superseded-by`, as there would be
+some newer API that supersedes whatever got deprecated.
+
+Typically for vars you'll use a non-qualified name if the replacement lives
+in the same namespace, and a fully-qualified name otherwise.
+
+[source,clojure]
+----
+;; in case we have a version
+(def ^{:deprecated "0.5"
+       :superseded-by "bar"} foo
+  "Use `bar` instead.
+  42)
+
+(ns foo.bar
+  "A deprecated ns."
+  {:deprecated "0.8"
+   :superseded-by "foo.baz"})
+
+(defn ^{:deprecated "0.5"
+        :superseded-by "bar"} foo
+  (bar))
+
+;; otherwise
+(defn ^{:deprecated true
+        :superseded-by "bar"} foo
+  (bar))
+----
+
 === `:added`
 
 The most common way to document when a public API was added to a