Skip to content

Commit b8536a2

Browse files
committed
api docs: code indentation and formatting (jQuery.a to jQuery.g entries plus jquery-2.xml)
1 parent a4eb034 commit b8536a2

24 files changed

+680
-533
lines changed

entries/jQuery.Callbacks.xml

Lines changed: 57 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -15,47 +15,47 @@
1515
<p>The following are two sample methods named <code>fn1</code> and <code>fn2</code>:</p>
1616
<pre><code>
1717
function fn1( value ) {
18-
console.log( value );
18+
console.log( value );
1919
}
2020

2121
function fn2( value ) {
22-
console.log("fn2 says: " + value);
23-
return false;
22+
console.log( "fn2 says: " + value );
23+
return false;
2424
}
25-
</code></pre>
25+
</code></pre>
2626
<p>These can be added as callbacks to a <code>$.Callbacks</code> list and invoked as follows:</p>
2727
<pre><code>
2828
var callbacks = $.Callbacks();
2929
callbacks.add( fn1 );
3030

31-
// outputs: foo!
31+
// Outputs: foo!
3232
callbacks.fire( "foo!" );
3333

3434
callbacks.add( fn2 );
3535

36-
// outputs: bar!, fn2 says: bar!
36+
// Outputs: bar!, fn2 says: bar!
3737
callbacks.fire( "bar!" );
38-
</code></pre>
38+
</code></pre>
3939
<p>The result of this is that it becomes simple to construct complex lists of callbacks where input values can be passed through to as many functions as needed with ease.</p>
4040
<p>Two specific methods were being used above: <code>.add()</code> and <code>.fire()</code>. The <code>.add()</code> method supports adding new callbacks to the callback list, while the <code>.fire()</code> method executes the added functions and provides a way to pass arguments to be processed by the callbacks in the same list.</p>
4141
<p>Another method supported by <code>$.Callbacks</code> is <code>.remove()</code>, which has the ability to remove a particular callback from the callback list. Here"s a practical example of <code>.remove()</code> being used:</p>
4242
<pre><code>
4343
var callbacks = $.Callbacks();
4444
callbacks.add( fn1 );
4545

46-
// outputs: foo!
46+
// Outputs: foo!
4747
callbacks.fire( "foo!" );
4848

4949
callbacks.add( fn2 );
5050

51-
// outputs: bar!, fn2 says: bar!
51+
// Outputs: bar!, fn2 says: bar!
5252
callbacks.fire( "bar!" );
5353

5454
callbacks.remove( fn2 );
5555

56-
// only outputs foobar, as fn2 has been removed.
56+
// Only outputs foobar, as fn2 has been removed.
5757
callbacks.fire( "foobar" );
58-
</code></pre>
58+
</code></pre>
5959
<h3 id="supported-flags">Supported Flags</h3>
6060
<p>The <code>flags</code> argument is an optional argument to <code>$.Callbacks()</code>, structured as a list of space-separated strings that change how the callback list behaves (eg. <code>$.Callbacks( "unique stopOnFalse" )</code>).</p>
6161
<h2>Possible flags:</h2>
@@ -81,9 +81,10 @@ callbacks.fire( "foobar" );
8181
output:
8282
foo
8383
*/
84-
</code></pre>
84+
</code></pre>
8585
<h2 id="memory"><code>$.Callbacks( "memory" )</code>:</h2>
86-
<pre><code>var callbacks = $.Callbacks( "memory" );
86+
<pre><code>
87+
var callbacks = $.Callbacks( "memory" );
8788
callbacks.add( fn1 );
8889
callbacks.fire( "foo" );
8990
callbacks.add( fn2 );
@@ -99,9 +100,10 @@ bar
99100
fn2 says:bar
100101
foobar
101102
*/
102-
</code></pre>
103+
</code></pre>
103104
<h2 id="unique"><code>$.Callbacks( "unique" )</code>:</h2>
104-
<pre><code>var callbacks = $.Callbacks( "unique" );
105+
<pre><code>
106+
var callbacks = $.Callbacks( "unique" );
105107
callbacks.add( fn1 );
106108
callbacks.fire( "foo" );
107109
callbacks.add( fn1 ); // repeat addition
@@ -117,17 +119,17 @@ bar
117119
fn2 says:bar
118120
foobar
119121
*/
120-
</code></pre>
122+
</code></pre>
121123
<h2 id="stopOnFalse"><code>$.Callbacks( "stopOnFalse" )</code>:</h2>
122124
<pre><code>
123125
function fn1( value ){
124-
console.log( value );
125-
return false;
126+
console.log( value );
127+
return false;
126128
}
127129

128130
function fn2( value ){
129-
fn1( "fn2 says: " + value );
130-
return false;
131+
fn1( "fn2 says: " + value );
132+
return false;
131133
}
132134

133135
var callbacks = $.Callbacks( "stopOnFalse" );
@@ -144,18 +146,18 @@ foo
144146
bar
145147
foobar
146148
*/
147-
</code></pre>
149+
</code></pre>
148150
<p>Because <code>$.Callbacks()</code> supports a list of flags rather than just one, setting several flags has a cumulative effect similar to "&amp;&amp;". This means it's possible to combine flags to create callback lists that, say, both are <i>unique</i> and <i>ensure if list was already fired, adding more callbacks will have it called with the latest fired value</i> (i.e. <code>$.Callbacks("unique memory")</code>).</p>
149151
<h2 id="unique-memory"><code>$.Callbacks( 'unique memory' )</code>:</h2>
150152
<pre><code>
151153
function fn1( value ) {
152-
console.log( value );
153-
return false;
154+
console.log( value );
155+
return false;
154156
}
155157

156158
function fn2( value ) {
157-
fn1( "fn2 says: " + value );
158-
return false;
159+
fn1( "fn2 says: " + value );
160+
return false;
159161
}
160162

161163
var callbacks = $.Callbacks( "unique memory" );
@@ -184,40 +186,42 @@ foobar
184186
<p>The methods of <code>$.Callbacks</code> can also be detached, should there be a need to define short-hand versions for convenience:</p>
185187
<pre><code>
186188
var callbacks = $.Callbacks(),
187-
add = callbacks.add,
188-
remove = callbacks.remove,
189-
fire = callbacks.fire;
189+
add = callbacks.add,
190+
remove = callbacks.remove,
191+
fire = callbacks.fire;
190192

191193
add( fn1 );
192194
fire( "hello world" );
193195
remove( fn1 );
194-
</code></pre>
196+
</code></pre>
195197
<h3 id="pubsub">$.Callbacks, $.Deferred and Pub/Sub</h3>
196198
<p>The general idea behind pub/sub (Publish/Subscribe, or, the Observer pattern) is the promotion of loose coupling in applications. Rather than single objects calling on the methods of other objects, an object instead subscribes to a specific task or activity of another object and is notified when it occurs. Observers are also called Subscribers, and we refer to the object being observed as the Publisher (or the subject). Publishers notify subscribers when events occur.</p>
197199
<p>To demonstrate the component-creation capabilities of <code>$.Callbacks()</code>, it's possible to implement a Pub/Sub system using only callback lists. Using <code>$.Callbacks</code> as a topics queue, a system for publishing and subscribing to topics can be implemented as follows:</p>
198-
<pre><code>var topics = {};
200+
<pre><code>
201+
var topics = {};
199202

200203
jQuery.Topic = function( id ) {
201-
var callbacks,
202-
method,
203-
topic = id &amp;&amp; topics[ id ];
204+
var callbacks,
205+
method,
206+
topic = id &amp;&amp; topics[ id ];
204207

205-
if ( !topic ) {
206-
callbacks = jQuery.Callbacks();
207-
topic = {
208-
publish: callbacks.fire,
209-
subscribe: callbacks.add,
210-
unsubscribe: callbacks.remove
211-
};
212-
if ( id ) {
213-
topics[ id ] = topic;
214-
}
208+
if ( !topic ) {
209+
callbacks = jQuery.Callbacks();
210+
topic = {
211+
publish: callbacks.fire,
212+
subscribe: callbacks.add,
213+
unsubscribe: callbacks.remove
214+
};
215+
if ( id ) {
216+
topics[ id ] = topic;
215217
}
216-
return topic;
218+
}
219+
return topic;
217220
};
218-
</code></pre>
221+
</code></pre>
219222
<p>This can then be used by parts of your application to publish and subscribe to events of interest quite easily:</p>
220-
<pre><code>// Subscribers
223+
<pre><code>
224+
// Subscribers
221225
$.Topic( "mailArrived" ).subscribe( fn1 );
222226
$.Topic( "mailArrived" ).subscribe( fn2 );
223227
$.Topic( "mailSent" ).subscribe( fn1 );
@@ -237,18 +241,19 @@ hello world!
237241
fn2 says: hello world!
238242
woo! mail!
239243
*/
240-
</code></pre>
244+
</code></pre>
241245
<p>While this is useful, the implementation can be taken further. Using <code>$.Deferreds</code>, it's possible to ensure publishers only publish notifications for subscribers once particular tasks have been completed (resolved). See the below code sample for some further comments on how this could be used in practice:</p>
242-
<pre><code>// subscribe to the mailArrived notification
246+
<pre><code>
247+
// Subscribe to the mailArrived notification
243248
$.Topic( "mailArrived" ).subscribe( fn1 );
244249

245-
// create a new instance of Deferreds
250+
// Create a new instance of Deferreds
246251
var dfd = $.Deferred();
247252

248-
// define a new topic (without directly publishing)
253+
// Define a new topic (without directly publishing)
249254
var topic = $.Topic( "mailArrived" );
250255

251-
// when the deferred has been resolved, publish a
256+
// When the deferred has been resolved, publish a
252257
// notification to subscribers
253258
dfd.done( topic.publish );
254259

@@ -259,7 +264,7 @@ dfd.done( topic.publish );
259264
// messages are only published once the task has actually
260265
// finished.
261266
dfd.resolve( "it's been published!" );
262-
</code></pre>
267+
</code></pre>
263268
</longdesc>
264269
<category slug="callbacks-object"/>
265270
<category slug="version/1.7"/>

entries/jQuery.Deferred.xml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,15 @@
1717
<desc> A constructor function that returns a chainable utility object with methods to register multiple callbacks into callback queues, invoke callback queues, and relay the success or failure state of any synchronous or asynchronous function.</desc>
1818
<longdesc>
1919
<p>The <code>jQuery.Deferred()</code> constructor creates a new Deferred object. The <code>new</code> operator is optional.</p>
20-
<p>The <code>jQuery.Deferred</code> method can be passed an optional function, which is called just before the constructor returns and is passed the constructed <code>deferred</code> object as both the <code>this</code> object and as the first argument to the function. The called function can attach callbacks using <a href="/deferred.then"><code>deferred.then()</code></a>, for example.</p>
21-
<p>A Deferred object starts in the <em>pending</em> state. Any callbacks added to the object with <a href="/deferred.then"><code>deferred.then()</code></a>, <a href="/deferred.always"><code>deferred.always()</code></a>, <a href="/deferred.done"><code>deferred.done()</code></a>, or <a href="/deferred.fail"><code>deferred.fail()</code></a> are queued to be executed later. Calling <a href="/deferred.resolve"><code>deferred.resolve()</code></a> or <a href="/deferred.resolveWith"><code>deferred.resolveWith()</code></a> transitions the Deferred into the <em>resolved</em> state and immediately executes any <code>doneCallbacks</code> that are set. Calling <a href="/deferred.reject"><code>deferred.reject()</code></a> or <a href="/deferred.rejectWith"><code>deferred.rejectWith()</code></a> transitions the Deferred into the <em>rejected</em> state and immediately executes any <code>failCallbacks</code> that are set. Once the object has entered the resolved or rejected state, it stays in that state. Callbacks can still be added to the resolved or rejected Deferred — they will execute immediately.</p>
20+
<p>The <code>jQuery.Deferred</code> method can be passed an optional function, which is called just before the constructor returns and is passed the constructed <code>deferred</code> object as both the <code>this</code> object and as the first argument to the function. The called function can attach callbacks using <a href="/deferred.then/"><code>deferred.then()</code></a>, for example.</p>
21+
<p>A Deferred object starts in the <em>pending</em> state. Any callbacks added to the object with <a href="/deferred.then/"><code>deferred.then()</code></a>, <a href="/deferred.always/"><code>deferred.always()</code></a>, <a href="/deferred.done/"><code>deferred.done()</code></a>, or <a href="/deferred.fail/"><code>deferred.fail()</code></a> are queued to be executed later. Calling <a href="/deferred.resolve/"><code>deferred.resolve()</code></a> or <a href="/deferred.resolveWith/"><code>deferred.resolveWith()</code></a> transitions the Deferred into the <em>resolved</em> state and immediately executes any <code>doneCallbacks</code> that are set. Calling <a href="/deferred.reject/"><code>deferred.reject()</code></a> or <a href="/deferred.rejectWith/"><code>deferred.rejectWith()</code></a> transitions the Deferred into the <em>rejected</em> state and immediately executes any <code>failCallbacks</code> that are set. Once the object has entered the resolved or rejected state, it stays in that state. Callbacks can still be added to the resolved or rejected Deferred — they will execute immediately.</p>
2222
<h4>
2323
Enhanced Callbacks with jQuery Deferred
2424
</h4>
2525
<p>In JavaScript it is common to invoke functions that optionally accept callbacks that are called within that function. For example, in versions prior to jQuery 1.5, asynchronous processes such as <code>jQuery.ajax()</code> accept callbacks to be invoked some time in the near-future upon success, error, and completion of the ajax request.</p>
2626
<p><code>jQuery.Deferred()</code> introduces several enhancements to the way callbacks are managed and invoked. In particular, <code>jQuery.Deferred()</code> provides flexible ways to provide multiple callbacks, and these callbacks can be invoked regardless of whether the original callback dispatch has already occurred. jQuery Deferred is based on the <a href="http://wiki.commonjs.org/wiki/Promises/A">CommonJS Promises/A</a> design.</p>
27-
<p>One model for understanding Deferred is to think of it as a chain-aware function wrapper. The <a href="/deferred.then"><code>deferred.then()</code></a>, <a href="/deferred.always"><code>deferred.always()</code></a>, <a href="/deferred.done"><code>deferred.done()</code></a>, and <a href="/deferred.fail"><code>deferred.fail()</code></a> methods specify the functions to be called and the <a href="/deferred.resolve"><code>deferred.resolve(args)</code></a> or <a href="/deferred.reject"><code>deferred.reject(args)</code></a> methods "call" the functions with the arguments you supply. Once the Deferred has been resolved or rejected it stays in that state; a second call to <code>deferred.resolve()</code>, for example, is ignored. If more functions are added by <code>deferred.then()</code>, for example, after the Deferred is resolved, they are called immediately with the arguments previously provided.</p>
28-
<p>In most cases where a jQuery API call returns a Deferred or Deferred-compatible object, such as <a href="/jQuery.ajax"><code>jQuery.ajax()</code></a> or <a href="/jQuery.when"><code>jQuery.when()</code></a>, you will only want to use the <a href="/deferred.then"><code>deferred.then()</code></a>, <a href="/deferred.done"><code>deferred.done()</code></a>, and <a href="/deferred.fail"><code>deferred.fail()</code></a> methods to add callbacks to the Deferred's queues. The internals of the API call or code that created the Deferred will invoke <a href="/deferred.resolve"><code>deferred.resolve()</code></a> or <a href="/deferred.reject"><code>deferred.reject()</code></a> on the deferred at some point, causing the appropriate callbacks to run.</p>
27+
<p>One model for understanding Deferred is to think of it as a chain-aware function wrapper. The <a href="/deferred.then/"><code>deferred.then()</code></a>, <a href="/deferred.always/"><code>deferred.always()</code></a>, <a href="/deferred.done/"><code>deferred.done()</code></a>, and <a href="/deferred.fail/"><code>deferred.fail()</code></a> methods specify the functions to be called and the <a href="/deferred.resolve/"><code>deferred.resolve(args)</code></a> or <a href="/deferred.reject/"><code>deferred.reject(args)</code></a> methods "call" the functions with the arguments you supply. Once the Deferred has been resolved or rejected it stays in that state; a second call to <code>deferred.resolve()</code>, for example, is ignored. If more functions are added by <code>deferred.then()</code>, for example, after the Deferred is resolved, they are called immediately with the arguments previously provided.</p>
28+
<p>In most cases where a jQuery API call returns a Deferred or Deferred-compatible object, such as <a href="/jQuery.ajax/"><code>jQuery.ajax()</code></a> or <a href="/jQuery.when/"><code>jQuery.when()</code></a>, you will only want to use the <a href="/deferred.then/"><code>deferred.then()</code></a>, <a href="/deferred.done/"><code>deferred.done()</code></a>, and <a href="/deferred.fail/"><code>deferred.fail()</code></a> methods to add callbacks to the Deferred's queues. The internals of the API call or code that created the Deferred will invoke <a href="/deferred.resolve/"><code>deferred.resolve()</code></a> or <a href="/deferred.reject/"><code>deferred.reject()</code></a> on the deferred at some point, causing the appropriate callbacks to run.</p>
2929
</longdesc>
3030
<category slug="deferred-object"/>
3131
<category slug="version/1.5"/>

0 commit comments

Comments
 (0)