Some documentation to clarify discussion on #4856.

lib/galaxy/util/__init__.py

@@ -605,7 +605,11 @@ def which(file):
 def in_directory( file, directory, local_path_module=os.path ):
     """
     Return true, if the common prefix of both is equal to directory
-    e.g. /a/b/c/d.rst and directory is /a/b, the common prefix is /a/b
+    e.g. /a/b/c/d.rst and directory is /a/b, the common prefix is /a/b.
+    This function isn't used exclusively for security checks, but if it is
+    used for such checks it is assumed that ``directory`` is a "trusted" path -
+    supplied by Galaxy or by the admin and ``file`` is something generated by
+    a tool, configuration, external web server, or user supplied input.
 
     local_path_module is used by Pulsar to check Windows paths while running on
     a POSIX-like system.