From 855672481f37ce3855c51d11d98682c78595434c Mon Sep 17 00:00:00 2001
From: miruka <miruka@disroot.org>
Date: Fri, 22 May 2020 17:27:57 -0400
Subject: [PATCH] Improve some python documentation and add an intro

---
 TODO.md                      |  2 ++
 src/backend/__init__.py      | 11 ++++++++++-
 src/backend/matrix_client.py |  2 +-
 src/backend/nio_callbacks.py |  2 +-
 src/backend/qml_bridge.py    | 19 ++++++++++++++-----
 5 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/TODO.md b/TODO.md
index f31b3580..4114ca5c 100644
--- a/TODO.md
+++ b/TODO.md
@@ -15,6 +15,8 @@
 
 ## Issues
 
+- SSL error on python 3.7
+
 - Jumping between accounts (clicking in account bar or alt+(Shift+)N) is
   laggy with hundreds of rooms in between
 - On startup, if a room's last event is a membership change,
diff --git a/src/backend/__init__.py b/src/backend/__init__.py
index a875d90b..310bcb98 100644
--- a/src/backend/__init__.py
+++ b/src/backend/__init__.py
@@ -1,6 +1,15 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 
-"""This package provides a Python backend accessible from the QML UI side."""
+"""This package provides Mirage's backend side that can interact with the UI.
+
+To learn more about how this package works, you might want to check the
+documentation in the following modules first:
+
+- `qml_bridge`
+- `backend`
+- `matrix_client`
+- `nio_callbacks`
+"""
 
 __app_name__     = "mirage"
 __display_name__ = "Mirage"
diff --git a/src/backend/matrix_client.py b/src/backend/matrix_client.py
index 70ae85bc..7710db7a 100644
--- a/src/backend/matrix_client.py
+++ b/src/backend/matrix_client.py
@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 
-"""Matrix client and related classes."""
+"""Matrix client to interact with a homeserver and other related classes."""
 
 import asyncio
 import html
diff --git a/src/backend/nio_callbacks.py b/src/backend/nio_callbacks.py
index 47eafe4b..2387263f 100644
--- a/src/backend/nio_callbacks.py
+++ b/src/backend/nio_callbacks.py
@@ -22,7 +22,7 @@ if TYPE_CHECKING:
 class NioCallbacks:
     """Register callbacks for nio's request responses and room events.
 
-    For every nio `Response` and `Event` subclasses, this class can have a
+    For every `nio.Response` and `nio.Event` subclasses, this class can have a
     method named `on<ClassName>` (e.g. `onRoomMessageText`) that will
     automatically be registered in nio.
 
diff --git a/src/backend/qml_bridge.py b/src/backend/qml_bridge.py
index 52a050a1..caa439df 100644
--- a/src/backend/qml_bridge.py
+++ b/src/backend/qml_bridge.py
@@ -4,6 +4,15 @@
 # directly or indirectly via another module import (e.g. backend).
 # See https://stackoverflow.com/a/55918049
 
+"""Provide `BRIDGE`, main object accessed by QML to interact with Python.
+
+PyOtherSide, the library that handles interaction between our Python backend
+and QML UI, will access the `BRIDGE` object and call its methods directly.
+
+The `BRIDGE` object should be the only existing instance of the `QMLBridge`
+class.
+"""
+
 import asyncio
 import logging as log
 import os
@@ -18,16 +27,16 @@ from .pyotherside_events import CoroutineDone, LoopException
 
 
 class QMLBridge:
-    """Setup asyncio and provide synchronous methods to call coroutines.
+    """Setup asyncio and provide methods to call coroutines from QML.
 
     A thread is created to run the asyncio loop in, to ensure all calls from
     QML return instantly.
-    Methods are provided for QML to call coroutines using PyOtherSide, which
-    doesn't have this ability out of the box.
+    Synchronous methods are provided for QML to call coroutines using
+    PyOtherSide, which doesn't have this ability out of the box.
 
     Attributes:
-        backend: The `Backend` containing the coroutines of interest and
-            `MatrixClient` objects.
+        backend: The `backend.Backend` object containing general coroutines
+            for QML and that manages `MatrixClient` objects.
     """
 
     def __init__(self) -> None: