diff -r 6afbfb9b1af1 -r 3af218cf2007 mercurial/obsolete.py
--- a/mercurial/obsolete.py	Sat Feb 15 18:40:39 2014 +0900
+++ b/mercurial/obsolete.py	Thu Feb 13 17:33:45 2014 -0800
@@ -256,6 +256,9 @@
         * ensuring it is hashable
         * check mandatory metadata
         * encode metadata
+
+        If you are a human writing code creating marker you want to use the
+        `createmarkers` function in this module instead.
         """
         if metadata is None:
             metadata = {}