Improve class docs

lib/AbstractPicoPlugin.php

@@ -3,6 +3,9 @@
 /**
  * Abstract class to extend from when implementing a Pico plugin
  *
+ * Please refer to {@see PicoPluginInterface} for more information about how
+ * to develop a plugin for Pico.
+ *
  * @see PicoPluginInterface
  *
  * @author  Daniel Rudolf

lib/PicoPluginInterface.php

@@ -7,18 +7,11 @@
  * {@see DummyPlugin} as template for new plugins. For a list of deprecated
  * events see {@see PicoDeprecated}.
  *
- * You SHOULD NOT use deprecated events when implementing this interface.
+ * If you're developing a new plugin, you MUST both implement this interface
- * Deprecated events are triggered by the {@see PicoDeprecated} plugin, if
+ * and define the class constant `API_VERSION`. You SHOULD always use the
- * plugins which don't implement this interface are loaded. You can take
+ * API version of Pico's latest milestone when releasing a plugin. If you're
- * advantage from this behaviour if you want to do something only when old
+ * developing a new version of an existing plugin, it is strongly recommended
- * plugins are loaded. Consequently the old events are never triggered when
+ * to update your plugin to use Pico's latest API version.
- * your plugin is implementing this interface and no old plugins are present.
- *
- * If you're developing a new plugin, you MUST implement this interface. If
- * you're the developer of an old plugin, it is STRONGLY RECOMMENDED to use
- * the events introduced in Pico 1.0 when releasing a new version of your
- * plugin. If you want to use any of the new events, you MUST implement
- * this interface and update all other events you use.
  *
  * @author  Daniel Rudolf
  * @link    http://picocms.org