From 699e12bd881c1e52d4b15b3d8e7d2f7468a5ceca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=A0ar=C5=ABnas=20Nejus?= <snejus@protonmail.com>
Date: Sun, 9 Apr 2023 18:18:34 +0100
Subject: [PATCH] Add explanatory docstring

---
 beets/library.py | 9 +++++++++
 1 file changed, 9 insertions(+)

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):