1 files changed, 45 insertions, 5 deletions

diff --git a/linden/indra/llcommon/lluri.h b/linden/indra/llcommon/lluri.h
index d67051a..d6d235d 100644
--- a/linden/indra/llcommon/lluri.h
+++ b/linden/indra/llcommon/lluri.h
@@ -14,12 +14,12 @@
  * ("GPL"), unless you have obtained a separate licensing agreement
  * ("Other License"), formally executed by you and Linden Lab.  Terms of
  * the GPL can be found in doc/GPL-license.txt in this distribution, or
- * online at http://secondlife.com/developers/opensource/gplv2
+ * online at http://secondlifegrid.net/programs/open_source/licensing/gplv2
  * 
  * There are special exceptions to the terms and conditions of the GPL as
  * it is applied to this Source Code. View the full text of the exception
  * in the file doc/FLOSS-exception.txt in this software distribution, or
- * online at http://secondlife.com/developers/opensource/flossexception
+ * online at http://secondlifegrid.net/programs/open_source/licensing/flossexception
  * 
  * By copying, modifying or distributing this software, you acknowledge
  * that you have read and understood your obligations described above,
@@ -125,12 +125,52 @@ public:
 
         /** @name Escaping Utilities */
         //@{
-        // Escape a string by urlencoding all the characters that aren't
-        // in the allowed string.
+        /**
+         * @brief Escape a raw url with a reasonable set of allowed characters.
+         *
+         * The default set was chosen to match HTTP urls and general
+     *  guidelines for naming resources. Passing in a raw url does not
+     *  produce well defined results because you really need to know
+     *  which segments are path parts because path parts are supposed
+     *  to be escaped individually. The default set chosen is:
+         *
+         *  ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
+         *  0123456789
+         *  -._~
+         *  :@!$'()*+,=/?&#;
+         *
+         * *NOTE: This API is basically broken because it does not
+     *  allow you to specify significant path characters. For example,
+     *  if the filename actually contained a /, then you cannot use
+     *  this function to generate the serialized url for that
+     *  resource.
+         *
+         * @param str The raw URI to escape.
+         * @return Returns the escaped uri or an empty string.
+         */
         static std::string escape(const std::string& str);
+
+        /**
+         * @brief Escape a string with a specified set of allowed characters.
+         *
+         * Escape a string by urlencoding all the characters that aren't
+         * in the allowed string.
+         * @param str The raw URI to escape.
+         * @param allowed Character array of allowed characters
+         * @param is_allowed_sorted Optimization hint if allowed array is sorted.
+         * @return Returns the escaped uri or an empty string.
+         */
         static std::string escape(
                 const std::string& str,
-                const std::string & allowed); 
+                const std::string& allowed,
+                bool is_allowed_sorted = false);
+
+        /**
+         * @brief unescape an escaped URI string.
+         *
+         * @param str The escped URI to unescape.
+         * @return Returns the unescaped uri or an empty string.
+         */
         static std::string unescape(const std::string& str);
         //@}