From ce0622e38a544037507ddf8eddf2607bbc912f20 Mon Sep 17 00:00:00 2001
From: Florian Bruhin <git@the-compiler.org>
Date: Thu, 28 Sep 2017 08:40:48 +0200
Subject: [PATCH] Document how initialization roughly works

---
 qutebrowser/app.py         | 20 +++++++++++++++++++-
 qutebrowser/qutebrowser.py | 16 +++++++++++++++-
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/qutebrowser/app.py b/qutebrowser/app.py
index 05420a9e4..c0dc80619 100644
--- a/qutebrowser/app.py
+++ b/qutebrowser/app.py
@@ -17,7 +17,25 @@
 # You should have received a copy of the GNU General Public License
 # along with qutebrowser.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Initialization of qutebrowser and application-wide things."""
+"""Initialization of qutebrowser and application-wide things.
+
+The run() function will get called once early initialization (in
+qutebrowser.py/earlyinit.py) is done. See the qutebrowser.py docstring for
+details about early initialization.
+
+As we need to access the config before the QApplication is created, we
+initialize everything the config needs before the QApplication is created, and
+then leave it in a partially initialized state (no saving, no config errors
+shown yet).
+
+We then set up the QApplication object and initialize a few more low-level
+things.
+
+After that, init() and _init_modules() take over and initialize the rest.
+
+After all initialization is done, the qt_mainloop() function is called, which
+blocks and spins the Qt mainloop.
+"""
 
 import os
 import sys
diff --git a/qutebrowser/qutebrowser.py b/qutebrowser/qutebrowser.py
index a2066acd3..8c80dfc22 100644
--- a/qutebrowser/qutebrowser.py
+++ b/qutebrowser/qutebrowser.py
@@ -17,7 +17,21 @@
 # You should have received a copy of the GNU General Public License
 # along with qutebrowser.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Early initialization and main entry point."""
+"""Early initialization and main entry point.
+
+qutebrowser's initialization process roughly looks like this:
+
+- This file gets imported, either via the setuptools entry point or
+  __main__.py.
+- At import time, we check for the correct Python version and show an error if
+  it's too old.
+- The main() function in this file gets invoked
+- Argument parsing takes place
+- earlyinit.early_init() gets invoked to do various low-level initialization and
+  checks whether all dependencies are met.
+- app.run() gets called, which takes over.
+  See the docstring of app.py for details.
+"""
 
 import sys
 import json