From 1961bdf821afc6b437d3fff90ee5ff27b7f17e0d Mon Sep 17 00:00:00 2001
From: Florian Bruhin <git@the-compiler.org>
Date: Mon, 23 Jun 2014 15:17:36 +0200
Subject: [PATCH] Update HACKING

---
 doc/HACKING.asciidoc | 41 +++++++++++++++++++++++++++++++++++++++++
 doc/TODO             |  6 ------
 2 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/doc/HACKING.asciidoc b/doc/HACKING.asciidoc
index 6be6a4225..da92b6043 100644
--- a/doc/HACKING.asciidoc
+++ b/doc/HACKING.asciidoc
@@ -176,6 +176,46 @@ header]
 Hints
 -----
 
+Python and Qt objects
+~~~~~~~~~~~~~~~~~~~~~
+
+For many tasks, there are solutions in both Qt and the Python standard libary
+available.
+
+In qutebrowser, the policy is usually using the Python libraries, as they
+provide exceptions and other benefits.
+
+There are some exceptions for that:
+
+* `QThread` is used instead of Python threads because it provides signals and
+slots.
+* `QProcess` is used instead of Python's `subprocess` if certain actions (e.g.
+cleanup) when the process finished are desired, as it provides signals for
+that.
+* `QUrl` is used instead of storing URLs as string, see the
+<<handling-urls,handling URLs>> section for details.
+
+When using Qt objects, two issues must be taken care of:
+
+* Methods of Qt objects report their status by using their return values,
+instead of using exceptions.
++
+If a function gets or returns a Qt object which
+has an `.isValid()` method such as `QUrl` or `QModelIndex`, there's a helper
+function `qt_ensure_valid` in `qutebrowser.utils.qt` which should get called on
+all such objects. It will raise `qutebrowser.utils.qt.QtValueError` if the
+value is not valid.
++
+If a function returns something else on error, the return value should
+carefully be checked.
+* Methods of Qt objects have certain maximum values, based on their underlying
+C++ types.
++
+When passing a numeric parameter to a Qt function, all numbers should be
+range-checked using `qutebrowser.utils.check_overflow`, or passing a value
+which is too large should be avoided by other means (e.g. by setting a maximum
+value for a config object).
+
 Logging
 ~~~~~~~
 
@@ -266,6 +306,7 @@ There are also other arguments to customize the way the command is registered,
 see the class documentation for `register` in `qutebrowser.commands.utils` for
 details.
 
+[[handling-urls]]
 Handling URLs
 ~~~~~~~~~~~~~
 
diff --git a/doc/TODO b/doc/TODO
index d4248808c..c24eb11b4 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -18,12 +18,6 @@ Before 0.1
 - Implement some optional stuff from http://greenbytes.de/tech/tc2231/
   (especially filename with Content-Disposition: inline)
 - Icon
-- Check return values of Qt functions
-
-- Document in hacking:
-  Qt types vs. python types (exceptions for QProcess, QThread, ...)
-  qt_ensure_valid and qt_check_overflow
-  check return values
 
 New big features
 ================