diff --git a/beets/ui/commands.py b/beets/ui/commands.py
index e7e631a49..d45192be1 100644
--- a/beets/ui/commands.py
+++ b/beets/ui/commands.py
@@ -1083,7 +1083,10 @@ default_commands.append(version_cmd)
 # modify: Declaratively change metadata.
 
 def modify_items(lib, mods, dels, query, write, move, album, confirm):
-    """Modifies matching items according to key=value assignments."""
+    """Modifies matching items according to user-specified assignments and
+    deletions. `mods` is a list of "field=value" strings indicating
+    assignments. `dels` is a list of fields to be deleted.
+    """
     # Parse key=value specifications into a dictionary.
     model_cls = library.Album if album else library.Item
     fsets = {}
@@ -1157,16 +1160,20 @@ modify_cmd.parser.add_option('-f', '--format', action='store',
     help='print with custom format', default=None)
 def modify_func(lib, opts, args):
     args = decargs(args)
+
+    # Split the arguments into query parts, assignments (field=value),
+    # and deletions (field!).
     mods = []
     dels = []
     query = []
     for arg in args:
         if arg.endswith('!') and '=' not in arg and ':' not in arg:
-            dels.append(arg[:-1])
+            dels.append(arg[:-1])  # Strip trailing !.
         elif '=' in arg:
             mods.append(arg)
         else:
             query.append(arg)
+
     if not mods and not dels:
         raise ui.UserError('no modifications specified')
     write = opts.write if opts.write is not None else \
@@ -1243,7 +1250,8 @@ def write_items(lib, query, pretend):
 
         # Check for and display changes.
         changed = ui.show_model_changes(item, clean_item,
-                                        library.ITEM_KEYS_WRITABLE, always=True)
+                                        library.ITEM_KEYS_WRITABLE,
+                                        always=True)
         if changed and not pretend:
             try:
                 item.write()
diff --git a/docs/changelog.rst b/docs/changelog.rst
index b5e4e47a5..49cdee63e 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -32,10 +32,9 @@ New stuff:
 * We now only use "primary" aliases for artist names from MusicBrainz. This
   eliminates some strange naming that could occur when the `languages` config
   option was set. Thanks to Filipe Fortes.
-* The :ref:`modify-cmd` command now allows removing flexible attribute. For
-  example: ``beet modify artist:beatles oldies!`` deletes the ``oldies``
-  flexible attribute from the database, for the matching items. Thanks to
-  brilnius.
+* The :ref:`modify-cmd` command now allows removing flexible attributes. For
+  example, ``beet modify artist:beatles oldies!`` deletes the ``oldies``
+  attribute from matching items. Thanks to brilnius.
 
 Fixes:
 
diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst
index b7d7e3b68..d479dcbae 100644
--- a/docs/reference/cli.rst
+++ b/docs/reference/cli.rst
@@ -208,8 +208,10 @@ Change the metadata for items or albums in the database.
 Supply a :doc:`query <query>` matching the things you want to change and a
 series of ``field=value`` pairs. For example, ``beet modify genius of love
 artist="Tom Tom Club"`` will change the artist for the track "Genius of Love."
-For removing fields (only possible with flexible attributes), specify one or
-more ``field!`` argument(s). The ``-a`` switch operates on albums instead of
+To remove fields (which is only possible for flexible attributes), follow a
+field name with an exclamation point: ``field!``.
+
+The ``-a`` switch operates on albums instead of
 individual tracks. Items will automatically be moved around when necessary if
 they're in your library directory, but you can disable that with ``-M``. Tags
 will be written to the files according to the settings you have for imports,