Doc refinements for #1499

beetbox · Nov 7, 2015 · 4e20ddc · 4e20ddc
1 parent 4baf9eb
commit 4e20ddc
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 13 deletions.
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -6,10 +6,9 @@ Changelog
 
 For developers:
 
-* :doc:`/dev/plugins`: New hooks ``albuminfo_received`` and
-  ``trackinfo_received`` have been added for developers who would like to
-  intercept fetched meta data, before they are applied in tag manipulation
-  operations. :bug:`872`
+* :doc:`/dev/plugins`: Two new hooks, ``albuminfo_received`` and
+  ``trackinfo_received``, let plugins intercept metadata as soon as it is
+  received, before it is applied to music in the database. :bug:`872`
 
 Fixes:
 

diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst
@@ -214,17 +214,17 @@ The events currently available are:
 * *import_begin*: called just before a ``beet import`` session starts up.
   Parameter: ``session``.
 
-* *trackinfo_received*: called after meta data for a track item has been fetched
-  from disparate sources, such as MusicBrainz. Gives a developer the option to
-  intercept the fetched ``TrackInfo`` object. Can be used to modify tags on a
-  ``beet import`` operation or during later adjustments, such as ``mbsync``.
-  Slow handlers of the event can impact the operation, since the event is fired
-  for any fetched possible match *before* user or autotagger selection was made.
+* *trackinfo_received*: called after metadata for a track item has been
+  fetched from a data source, such as MusicBrainz. You can modify the tags
+  that the rest of the pipeline sees on a ``beet import`` operation or during
+  later adjustments, such as ``mbsync``. Slow handlers of the event can impact
+  the operation, since the event is fired for any fetched possible match
+  *before* the user (or the autotagger machinery) gets to see the match.
   Parameter: ``info``.
 
-* *albuminfo_received*: Like *trackinfo_received*, the event indicates new meta
-  data for album items, but supplies an ``AlbumInfo`` object instead of a
-  ``TrackInfo``.
+* *albuminfo_received*: like *trackinfo_received*, the event indicates new
+  metadata for album items. The parameter is an ``AlbumInfo`` object instead
+  of a ``TrackInfo``.
   Parameter: ``info``.
 
 The included ``mpdupdate`` plugin provides an example use case for event listeners.