Puts docs directly into the repo (who needs a wiki?). Inspired by what I saw in @cowboy's grunt repo. So simple I feel stupid not having thought about it before.

jaubourg · jaubourg · commit 8234f56c73a5 · 2012-05-04T01:23:31.000+02:00
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-## About
+# jQuery-JSONP
 
 jQuery-JSONP is a compact (1.8kB minified), yet feature-packed, alternative solution to jQuery's implementation of JSONP.
 
@@ -33,5 +33,5 @@ jQuery-JSONP has also been tested with jQuery 1.3.x up to 1.7.x
 
 ## Documentation
 
-* [API Documentation](/jaubourg/jquery-jsonp/wiki/API)
-* [Tips & Tricks](/jaubourg/jquery-jsonp/wiki/TipsAndTricks)
+* [API Documentation](/jaubourg/jquery-jsonp/blob/master/doc/API.md)
+* [Tips & Tricks](/jaubourg/jquery-jsonp/blob/master/doc/TipsAndTricks.md)
diff --git a/doc/API.md b/doc/API.md
@@ -0,0 +1,158 @@
+# API
+
+## `jQuery.jsonp( options )`
+
+### Overview
+
+Loads a remote JSON object using a JSONP request.
+
+`$.jsonp()` returns the extended options (the `xOptions` object) for the query (that is an object containing all the options passed to the function plus defaults for those not provided). In most cases you won't need `xOptions` to manipulate directly, but it is available if you need to abort the request manually (`xOptions` provides an `abort()` method to that end).
+
+*_As of version 2.3.0, if you use jQuery-JSONP with jQuery 1.5+, the `xOptions` object is a Promise. See [jQuery's documentation](http://api.jquery.com/deferred.promise/) for more information on Promises and Deferreds._* 
+
+`$.jsonp()` takes one argument, an object of key/value pairs, that are used to initialize and handle the request. All options are optional. A default can be set for any option with `$.jsonp.setup()`. See below for a full list of the key/values that can be used.
+
+### Options
+
+#### beforeSend - `function` (`undefined`)
+
+A function called before the request is even performed. You may return `false` in the callback to cancel the request.
+
+```js
+function (xOptions) {
+  this; // the xOptions object or xOptions.context if provided
+}
+```
+
+#### cache - `boolean` (`false`)
+
+If set to `false` it will force the data that you request not to be cached by the browser, unless the `pageCache` option is set to true.
+
+#### callback - `string` (`"_jqjsp"`)
+
+Name of the JSONP callback as provided in the request url. Most of the time, you won't have to change this value but some JSONP providers have a predefined callback name that cannot be overidden. Set the name of said callback in the `callback` option and `$.jsonp` will catch the call.
+
+*_As of version 2.0, the library defines a function for the callback in the global scope, so it is no longer safe to use the name of a function already defined: said function will be redefined by jQuery-JSONP._*
+
+*_On the other hand, it is still perfectly safe to have several concurrent requests using the same callback name: in that case, jQuery-JSONP ensures no collision occurs internally._*
+
+#### callbackParameter - `string` (`undefined`)
+
+*_as of version 1.0.1_*
+
+If provided, specifies the name of the url parameter that conveys the callback name to the service.
+
+Example:
+
+```js
+$.jsonp({
+  url: "http://service.org/path?param1=xx&param2=xx",
+  callbackParameter: "callback"
+});
+```
+
+is strictly equivalent to:
+
+```js
+$.jsonp({
+  url: "http://service.org/path?param1=xx&param2=xx&callback=?"
+});
+```
+
+#### charset - `string` (`undefined`)
+
+*_as of version 2.1.1_*
+
+Forces the request to be interpreted as a certain charset. Only needed for charset differences between the remote and local content.
+
+#### complete - `function` (`undefined`)
+
+A function to be called when the request finishes (after success and error callbacks are executed). The function gets passed two arguments: The `xOptions` object and a string describing the type of completion of the request (`"success"`, `"error"` or `"timeout"`).
+
+```js
+function (xOptions, textStatus) {
+  this; // the xOptions object or xOptions.context if provided
+}
+```
+
+#### context - `object` (`undefined`)
+
+*_as of version 2.1.1_*
+
+This object will be made the context of all `xOptions`-related callbacks. For example specifying a DOM element as the context will make it the context for the complete callback of a request, like so:
+
+```js
+$.jsonp({
+  url: "test.php?callback=?",
+  context: document.body,
+  complete: function() {
+    $(this).addClass("done");
+  }
+});
+```
+
+#### data - `object | string` (`undefined`)
+
+Data to be sent to the server. It is converted to a query string, if not already a string, and then appended to the url. Object must be key/value pairs. If value is an array, jQuery serializes multiple values with same key i.e. `{ foo: [ "bar1", "bar2" ] }` becomes `"&foo=bar1&foo=bar2"`.
+
+#### dataFilter - `function` (`undefined`)
+
+A function to be used to handle the raw responsed JSON object. This is a pre-filtering function to sanitize the response. You should return the sanitized data. The function gets one argument: The raw JSON object returned from the server.
+
+```js
+function (json) {
+  // do something
+  // return the sanitized json
+  return json;
+}
+```
+
+#### error - `function` (`undefined`)
+
+A function to be called if the request fails. The function is passed two arguments: The `xOptions` object and a string describing the type of error that occurred. Possible values for the second argument are `"error"` (the request finished but the JSONP callback was not called) or `"timeout"`.
+
+```js
+function (xOptions, textStatus) {
+  this; // the xOptions object or xOptions.context if provided
+}
+```
+
+#### pageCache - `boolean` (`false`)
+
+If set to true, will override the `cache` option and provide a page based caching of the result of the request. Whenever another request is made later on with `pageCache` set to `true` and with options inducing the exact same final url for the request, the cached response is used and no distant call is actually made.
+
+Lifetime of this cache is page-based which means it gets erased at each page reload.
+
+#### success - `function` (`undefined`)
+
+A function to be called if the request succeeds. The function gets passed two arguments: The JSON object returned from the server and a string describing the status (always `"success"`).
+
+```js
+function (json, textStatus) {
+  this; // the xOptions object or xOptions.context if provided
+}
+```
+
+#### timeout - `number` (`0`)
+
+If greater than `0`, sets a local timeout (in milliseconds) for the request. This will override the global timeout, if one is set via `$.jsonp.setup`. For example, you could use this property to give a single request a longer timeout than all other requests that you've set to time out in one second.
+
+#### traditional - `boolean` (`false`)
+
+*_as of version 2.0.2_*
+
+Set this to true if you wish to use the traditional style of [param serialization](http://api.jquery.com/jQuery.param/).
+
+#### url - `string` (`location.href`)
+
+The URL to request. If more than one `?` character is found in the url, the latest will be replaced by the value of the `callback` option. Note that, given this rule, no valid url can have more than two `?` characters.
+
+## `jQuery.jsonp.setup( options )`
+
+### Overview
+
+Setup global settings for JSONP requests.
+
+### Options
+
+See $.jsonp for a description of all available options.
diff --git a/doc/TipsAndTricks.md b/doc/TipsAndTricks.md
@@ -0,0 +1,124 @@
+# Tips & Tricks
+
+## Basic example
+
+Get user profiles from [YouTube](http://www.youtube.com/):
+
+```js
+function getProfile(userId) {
+
+    $.jsonp({
+      "url": "http://gdata.youtube.com/feeds/api/users/"+userId+"?callback=?",
+      "data": {
+          "alt": "json-in-script"
+      },
+      "success": function(userProfile) {
+          // handle user profile here 
+      },
+      "error": function(d,msg) {
+          alert("Could not find user "+userId);
+      }
+    });
+}
+```
+
+## Callback name is not in the url parameters
+
+By default, $.jsonp() uses "_jqjsp" as the callback name. You then just have to put "_jqjsp" where the callback name is supposed to be in the url.
+
+```js
+"http://weird-provider.org/_jqjsp/my-service?param1=1&param2=2&..."
+```
+
+If you find it confusing or unreadable to have _jqjsp buried inside the url, you can always use the callback option to use a different name and do something like this:
+
+```js
+$.jsonp({
+    url: "http://weird-provider.org/XXXXXXXX/my-service?param1=1&param2=2&...",
+    callback: "XXXXXXXX",
+    success: function(json) {
+       // This will be called in case of success no matter the callback name
+    },
+    error: function() {
+       // This will be called in case of error no matter the callback name
+    }
+});
+```
+
+## Provider calls a specific callback and I can't override its name in the url
+
+Thankfully, $.jsonp() can handle the situation and you won't have to create a function that's named after the callback and is supposed to handle every response received from this provider.
+
+Say services of _lazy-provider.org_ all call the same callback: _lazyCallback_. All you have to do is something like this:
+
+```js
+$.jsonp({
+    url: "http://lazy-provider.org/a-service?param1=1&param2=2&...",
+    callback: "lazyCallback",
+    success: function(json) {
+       // Will be given the response of 'a-service'
+    },
+    error: function() {
+       // Will be notified of an error requesting 'a-service'
+    }
+});
+
+$.jsonp({
+    url: "http://lazy-provider.org/another-service?param1=1&param2=2&...",
+    callback: "lazyCallback",
+    success: function(json) {
+       // Will be given the response of 'another-service'
+    },
+    error: function() {
+       // Will be notified of an error requesting 'another-service'
+    }
+});
+```
+
+Both requests can be sent concurrently and $.jsonp() ensures that no collision will ever occur.
+
+## How do I take advantage of the cache?
+
+$.jsonp handles two types of cache. One is browser based, the other is page based.
+
+### Browser cache
+
+Usual JSONP implementations rely on generated callback names to allow concurrent JSONP requests. $.jsonp does not. No matter the situation, provided you don't change it in the options, the callback will always be "_jqjsp". This means that the url used to perform the request is exactly the same from one call to another for the same set of parameters. In that case, "smart" Data APIs can issue a _304: Not Modified_ HTTP response, asking browsers to retrieve the previous response they obtained for the same url from cache.
+
+This is not an exact science. [YouTube](http://www.youtube.com/), for instance, does not always issue a _304_ but when it does eventually, it means further JSONP requests will not involve any network traffic.
+
+To take advantage of browser caching, you have to set the _cache_ option to true. For 1instance:
+
+```js
+$.jsonp({
+    url: "...",
+    cache: true,
+    success: function(json) {
+       // your success code here
+    },
+    error: function() {
+       // error handling goes here
+    }
+});
+```
+
+### Page-based cache
+
+Some providers just ignore situations when the callback name has not changed. In this case, you can use the page-based cache. This cache is stored in the javascript VM memory and ensures that, when you make a request that has been answered previously, you will get the exact same response and no network traffic will occur.
+
+This cache is wiped out as soon as the page is reloaded.
+
+To take advantage of page-based caching, you have to set the _pageCache_ option to true. Note that doing so overiddes any setting the _cache_ option could have and it is then also considered to be true. For instance:
+
+```js
+$.jsonp({
+    url: "...",
+    pageCache: true,
+    success: function(json) {
+       // your success code here
+    },
+    error: function() {
+       // error handling goes here
+    }
+});
+```
