Doc updates

src/Composer/Plugin/PluginInterface.php

@@ -40,6 +40,10 @@ interface PluginInterface
     /**
      * Remove any hooks from Composer
      *
+     * This will be called when a plugin is deactivated before being
+     * uninstalled, but also before it gets upgraded to a new version
+     * so the old one can be deactivated and the new one activated.
+     *
      * @param Composer    $composer
      * @param IOInterface $io
      */
@@ -48,7 +52,7 @@ interface PluginInterface
     /**
      * Prepare the plugin to be uninstalled
      *
-     * This will be called after deactivate
+     * This will be called after deactivate.
      *
      * @param Composer    $composer
      * @param IOInterface $io