hideablerevs: expand docstring to warn about possible traps

Sean Farley just wasted multiple hours trying to figure out why his code was
crashing. We update the docstring to make the constraint clearer.

mercurial/repoview.py

@@ -22,9 +22,14 b' from . import ('
 )
 
 def hideablerevs(repo):
-    """Revisions candidates to be hidden
+    """Revision candidates to be hidden
+
+    This is a standalone function to allow extensions to wrap it.
 
-    This is a standalone function to help extensions to wrap it."""
+    Because we use the set of immutable changesets as a fallback subset in
+    branchmap (see mercurial.branchmap.subsettable), you cannot set "public"
+    changesets as "hideable". Doing so would break multiple code assertions and
+    lead to crashes."""
     return obsolete.getrevs(repo, 'obsolete')
 
 def _getstatichidden(repo):