From 19cb15806506c806fb38a36870d5baaf889d4b0d Mon Sep 17 00:00:00 2001
From: Tim Walker <tim@tim-walkers-macbook-pro.local>
Date: Mon, 8 Feb 2010 22:24:39 -0800
Subject: [PATCH] doc: Merge/update old String query-related docs into source
 [#129 state:fixed_in_branch]

---
 src/lang/string.js | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/src/lang/string.js b/src/lang/string.js
index 35ef7b753..206457fad 100644
--- a/src/lang/string.js
+++ b/src/lang/string.js
@@ -359,6 +359,40 @@ Object.extend(String.prototype, (function() {
    *
    *  Parses a URI-like query string and returns an object composed of
    *  parameter/value pairs.
+   *  
+   *  This method is realy targeted at parsing query strings (hence the default 
+   *  value of`"&"` for the `separator` argument).
+   *  
+   *  For this reason, it does _not_ consider anything that is either before a 
+   *  question  mark (which signals the beginning of a query string) or beyond 
+   *  the hash symbol (`"#"`), and runs `decodeURIComponent()` on each 
+   *  parameter/value pair.
+   *  
+   *  `String#toQueryParams` also aggregates the values of identical keys into 
+   *  an array of values.
+   *  
+   *  Note that parameters which do not have a specified value will be set to 
+   *  `undefined`.
+   *  
+   *  ##### Examples
+   *  
+   *      'section=blog&id=45'.toQueryParams();
+   *      // -> {section: 'blog', id: '45'}
+   *      
+   *      'section=blog;id=45'.toQueryParams();
+   *      // -> {section: 'blog', id: '45'}
+   *      
+   *      'http://www.example.com?section=blog&id=45#comments'.toQueryParams();
+   *      // -> {section: 'blog', id: '45'}
+   *      
+   *      'section=blog&tag=javascript&tag=prototype&tag=doc'.toQueryParams();
+   *      // -> {section: 'blog', tag: ['javascript', 'prototype', 'doc']}
+   *      
+   *      'tag=ruby%20on%20rails'.toQueryParams();
+   *      // -> {tag: 'ruby on rails'}
+   *      
+   *      'id=45&raw'.toQueryParams();
+   *      // -> {id: '45', raw: undefined}
   **/
   function toQueryParams(separator) {
     var match = this.strip().match(/([^?#]*)(#.*)?$/);