qt: Add module docstrings and update lint ignores

17 files changed, 198 insertions, 54 deletions

diff --git a/.flake8 b/.flake8
index 8838a6990..8460fa68d 100644
--- a/.flake8
+++ b/.flake8
@@ -62,6 +62,7 @@ min-version = 3.7.0
 max-complexity = 12
 per-file-ignores =
     qutebrowser/api/hook.py : N801
+    qutebrowser/qt/*.py : F403
     tests/* : B011,B028,D100,D101
     tests/unit/browser/test_history.py : D100,D101,N806
     tests/helpers/fixtures.py : D100,D101,N806
diff --git a/qutebrowser/qt/core.py b/qutebrowser/qt/core.py
index a80792ace..5cc437552 100644
--- a/qutebrowser/qt/core.py
+++ b/qutebrowser/qt/core.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt Core.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtcore-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/dbus.py b/qutebrowser/qt/dbus.py
index 5f0cc6475..e9ee15ff8 100644
--- a/qutebrowser/qt/dbus.py
+++ b/qutebrowser/qt/dbus.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt DBus.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtdbus-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/gui.py b/qutebrowser/qt/gui.py
index cec936687..edc3adaea 100644
--- a/qutebrowser/qt/gui.py
+++ b/qutebrowser/qt/gui.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import,unused-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import,unused-import
+
+"""Wrapped Qt imports for Qt Gui.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtgui-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/machinery.py b/qutebrowser/qt/machinery.py
index 6699d5e73..1eef24f0b 100644
--- a/qutebrowser/qt/machinery.py
+++ b/qutebrowser/qt/machinery.py
@@ -1,9 +1,11 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring
-# flake8: noqa
 # pyright: reportConstantRedefinition=false
 
+"""Qt wrapper selection.
+
+Contains selection logic and globals for Qt wrapper selection.
+"""
+
 import os
 import sys
 import argparse
@@ -25,7 +27,7 @@ WRAPPERS = [
 
 
 class Error(Exception):
-    pass
+    """Base class for all exceptions in this module."""
 
 
 class Unavailable(Error, ImportError):
@@ -37,7 +39,10 @@ class Unavailable(Error, ImportError):
 
 
 class UnknownWrapper(Error):
-    pass
+    """Raised when an Qt module is imported but the wrapper values are unknown.
+
+    Should never happen (unless a new wrapper is added).
+    """
 
 
 def _autoselect_wrapper() -> str:
diff --git a/qutebrowser/qt/network.py b/qutebrowser/qt/network.py
index e24a75bfa..2a665a3a9 100644
--- a/qutebrowser/qt/network.py
+++ b/qutebrowser/qt/network.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt Network.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtnetwork-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/opengl.py b/qutebrowser/qt/opengl.py
index 0fa09e5ac..5c3af3a5a 100644
--- a/qutebrowser/qt/opengl.py
+++ b/qutebrowser/qt/opengl.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-import
+
+"""Wrapped Qt imports for Qt OpenGL.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtopengl-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/printsupport.py b/qutebrowser/qt/printsupport.py
index cdd1b4b22..e733bf828 100644
--- a/qutebrowser/qt/printsupport.py
+++ b/qutebrowser/qt/printsupport.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt Print Support.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtprintsupport-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/qml.py b/qutebrowser/qt/qml.py
index c97a44d0a..efb6901f2 100644
--- a/qutebrowser/qt/qml.py
+++ b/qutebrowser/qt/qml.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt QML.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtqml-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/sip.py b/qutebrowser/qt/sip.py
index 12d346516..7be3b061c 100644
--- a/qutebrowser/qt/sip.py
+++ b/qutebrowser/qt/sip.py
@@ -1,7 +1,18 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,wildcard-import,unused-wildcard-import,no-else-raise
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for PyQt5.sip/PyQt6.sip.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/sip directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the PyQt6.sip API:
+https://www.riverbankcomputing.com/static/Docs/PyQt6/api/sip/sip-module.html
+
+Note that we don't yet abstract between PySide/PyQt here.
+"""
 
 from qutebrowser.qt import machinery
 
@@ -11,7 +22,7 @@ machinery.init()
 # still package later versions of PyQt6 with a top-level "sip" rather than "PyQt6.sip".
 _VENDORED_SIP = False
 
-if machinery.USE_PYSIDE6:
+if machinery.USE_PYSIDE6:  # pylint: disable=no-else-raise
     raise machinery.Unavailable()
 elif machinery.USE_PYQT5:
     try:
@@ -25,9 +36,8 @@ elif machinery.USE_PYQT6:
         _VENDORED_SIP = True
     except ImportError:
         pass
-
 else:
     raise machinery.UnknownWrapper()
 
 if not _VENDORED_SIP:
-    from sip import *  # type: ignore[import]  # pylint: disable=import-error
+    from sip import *  # type: ignore[import]
diff --git a/qutebrowser/qt/sql.py b/qutebrowser/qt/sql.py
index 187573bc1..825d0acc8 100644
--- a/qutebrowser/qt/sql.py
+++ b/qutebrowser/qt/sql.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt SQL.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtsql-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/test.py b/qutebrowser/qt/test.py
index c2ae4f192..11753a622 100644
--- a/qutebrowser/qt/test.py
+++ b/qutebrowser/qt/test.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt Test.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qttest-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/webenginecore.py b/qutebrowser/qt/webenginecore.py
index 8154d8c9f..fcffef9b9 100644
--- a/qutebrowser/qt/webenginecore.py
+++ b/qutebrowser/qt/webenginecore.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import,unused-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import,unused-import
+
+"""Wrapped Qt imports for Qt WebEngine Core.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtwebenginecore-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/webenginewidgets.py b/qutebrowser/qt/webenginewidgets.py
index fd2d281c8..9bb62db1f 100644
--- a/qutebrowser/qt/webenginewidgets.py
+++ b/qutebrowser/qt/webenginewidgets.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt WebEngine Widgets.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtwebenginewidgets-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/webkit.py b/qutebrowser/qt/webkit.py
index b4b983037..c8b5c0b39 100644
--- a/qutebrowser/qt/webkit.py
+++ b/qutebrowser/qt/webkit.py
@@ -1,14 +1,24 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,wildcard-import,no-else-raise
-# flake8: noqa
+# pylint: disable=wildcard-import
+
+"""Wrapped Qt imports for Qt WebKit.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6
+(though WebKit is only supported with Qt 5).
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the QtWebKit 5.212 API:
+https://qtwebkit.github.io/doc/qtwebkit/qtwebkit-index.html
+"""
 
 from qutebrowser.qt import machinery
 
 machinery.init()
 
 
-if machinery.USE_PYSIDE6:
+if machinery.USE_PYSIDE6:  # pylint: disable=no-else-raise
     raise machinery.Unavailable()
 elif machinery.USE_PYQT5:
     from PyQt5.QtWebKit import *
diff --git a/qutebrowser/qt/webkitwidgets.py b/qutebrowser/qt/webkitwidgets.py
index edf6354fb..2c60909cc 100644
--- a/qutebrowser/qt/webkitwidgets.py
+++ b/qutebrowser/qt/webkitwidgets.py
@@ -1,7 +1,17 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,wildcard-import,no-else-raise
-# flake8: noqa
+# pylint: disable=wildcard-import,no-else-raise
+
+"""Wrapped Qt imports for Qt WebKit Widgets.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6
+(though WebKit is only supported with Qt 5).
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the QtWebKit 5.212 API:
+https://qtwebkit.github.io/doc/qtwebkit/qtwebkitwidgets-index.html
+"""
 
 from qutebrowser.qt import machinery
 
diff --git a/qutebrowser/qt/widgets.py b/qutebrowser/qt/widgets.py
index 405483716..44b677f09 100644
--- a/qutebrowser/qt/widgets.py
+++ b/qutebrowser/qt/widgets.py
@@ -1,7 +1,16 @@
 # vim: ft=python fileencoding=utf-8 sts=4 sw=4 et:
-# FIXME:qt6 (lint)
-# pylint: disable=missing-module-docstring,import-error,wildcard-import,unused-wildcard-import
-# flake8: noqa
+# pylint: disable=import-error,wildcard-import,unused-wildcard-import
+
+"""Wrapped Qt imports for Qt Widgets.
+
+All code in qutebrowser should use this module instead of importing from
+PyQt/PySide directly. This allows supporting both Qt 5 and Qt 6.
+
+See machinery.py for details on how Qt wrapper selection works.
+
+Any API exported from this module is based on the Qt 6 API:
+https://doc.qt.io/qt-6/qtwidgets-index.html
+"""
 
 from qutebrowser.qt import machinery