Add explanatory docstring

1 files changed, 9 insertions, 0 deletions

diff --git a/beets/library.py b/beets/library.py
index 7fb96d400..b52d5f873 100644
--- a/beets/library.py
+++ b/beets/library.py
@@ -45,6 +45,15 @@ log = logging.getLogger('beets')
 # Library-specific query types.
 
 class SingletonQuery(dbcore.FieldQuery):
+    """This query is responsible for the 'singleton' lookup.
+
+    It is based on the FieldQuery and constructs a SQL clause
+    'album_id is NULL' which yields the same result as the previous filter
+    in Python but is more performant since it's done in SQL.
+
+    Using util.str2bool ensures that lookups like singleton:true, singleton:1
+    and singleton:false, singleton:0 are handled consistently.
+    """
     def __new__(cls, field, value, *args, **kwargs):
         query = dbcore.query.NoneQuery('album_id')
         if util.str2bool(value):