From 295da2a29165973e673a136ddbb7e6fe64b42b61 Mon Sep 17 00:00:00 2001
From: Prashant Tiwari <prashaantt@gmail.com>
Date: Fri, 16 Jan 2015 13:04:40 +0530
Subject: [PATCH] Update Advice API doc for event and data params, multiple
 advice

---
 doc/advice_api.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/advice_api.md b/doc/advice_api.md
index 0b89e5a6..c1888064 100644
--- a/doc/advice_api.md
+++ b/doc/advice_api.md
@@ -86,6 +86,41 @@ function withDrama() {
 return withDrama;
 ```
 
+<a name="notes"></a>
+## Additional notes on using Advice
+
+### Retrieving event data
+
+In the above examples, the jQuery event and payload that will be passed to the `existingFunc` are available as extra parameters to the `customFunc` callback, respectively. This can be especially useful for calling `existingFunc` with the original arguments when using `this.around`:
+
+```js
+function withMelodiousHumour() {
+  this.around('yodel', function(func, event, data) {
+    if (data.tune) {
+      func(event, data); // event.type == 'yodel'
+    }
+  });
+}
+
+return withMelodiousHumour;
+```
+
+In the above example, `yodel` will never be called if `data.tune` is missing.
+
+### Shorthand for multiple advices
+
+Advice can be applied to multiple functions at once by listing more than one (space-separated) function names in the `existingFuncName` parameter. This can be used to club together common tasks on related methods:
+
+```js
+function withSoundCheck() {
+  this.before('announce yodel trumpet', function (event, data) {
+    checkOneTwo();
+  });
+}
+
+return withSoundCheck;
+```
+
 <a name="advice.withAdvice"></a>
 ## Making advice available to regular objects