Document how initialization roughly works

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

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