Update docs on @observable to hint about mixin Observable.

pkg/observe/lib/src/metadata.dart

Index: pkg/observe/lib/src/metadata.dart
diff --git a/pkg/observe/lib/src/metadata.dart b/pkg/observe/lib/src/metadata.dart
index 16c6ccab4155501f62a2843a5720170c3d7f7d67..f128102cae347e8f9d1037ec682b8d2623a2342b 100644
--- a/pkg/observe/lib/src/metadata.dart
+++ b/pkg/observe/lib/src/metadata.dart
@@ -5,31 +5,37 @@
 library observe.src.metadata;
 
 /// Use `@observable` to make a field automatically observable, or to indicate
-/// that a property is observable.
+/// that a property is observable. This only works on classes that extend or
+/// mix in `Observable`.
 const ObservableProperty observable = const ObservableProperty();
 
 /// An annotation that is used to make a property observable.
 /// Normally this is used via the [observable] constant, for example:
 ///
-///     class Monster {
+///     class Monster extends Observable {
 ///       @observable int health;
 ///     }
 ///
-/// If needed, you can subclass this to create another annotation that will also
-/// be treated as observable.
+// TODO(sigmund): re-add this to the documentation when it's really true:
+//     If needed, you can subclass this to create another annotation that will
+//     also be treated as observable.
 // Note: observable properties imply reflectable.
 class ObservableProperty {
   const ObservableProperty();
 }
 
 
-/// Use `@reflectable` to make a type or member available to reflection in the
-/// observe package. This is necessary to make the member visible to
-/// [PathObserver], or similar systems, once the code is deployed.
+/// This can be used to retain any properties that you wish to access with
+/// Dart's mirror system. If you import `package:observe/mirrors_used.dart`, all
+/// classes or members annotated with `@reflectable` wil be preserved by dart2js
+/// during compilation.  This is necessary to make the member visible to
+/// `PathObserver`, or similar systems, once the code is deployed, if you are
+/// not doing a different kind of code-generation for your app. If you are using
+/// polymer, you most likely don't need to use this annotation anymore.
 const Reflectable reflectable = const Reflectable();
 
 /// An annotation that is used to make a type or member reflectable. This makes
-/// it available to [PathObserver] at runtime. For example:
+/// it available to `PathObserver` at runtime. For example:
 ///
 ///     @reflectable
 ///     class Monster extends ChangeNotifier {