diff --git a/src/ngAnimate/module.js b/src/ngAnimate/module.js
index f37c404f7d7f..07757c8784c6 100644
--- a/src/ngAnimate/module.js
+++ b/src/ngAnimate/module.js
@@ -267,9 +267,22 @@
  * .message.ng-enter-prepare {
  *   opacity: 0;
  * }
- *
  * ```
  *
+ * ### Animating between value changes
+ *
+ * Sometimes you need to animate between different expression states, whose values
+ * don't necessary need to be known or referenced in CSS styles.
+ * Unless possible with another ["animation aware" directive](#directive-support), that specific
+ * use case can always be covered with {@link ngAnimate.directive:ngAnimateSwap} as can be seen in
+ * {@link ngAnimate.directive:ngAnimateSwap#examples this example}.
+ *
+ * Note that {@link ngAnimate.directive:ngAnimateSwap} is a *structural directive*, which means it
+ * creates a new instance of the element (including any other/child directives it may have) and
+ * links it to a new scope every time *swap* happens. In some cases this might not be desirable
+ * (e.g. for performance reasons, or when you wish to retain internal state on the original
+ * element instance).
+ *
  * ## JavaScript-based Animations
  *
  * ngAnimate also allows for animations to be consumed by JavaScript code. The approach is similar to CSS-based animations (where there is a shared