From e1456850465c5904baee4e5e0047e098c1269c1c Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Tue, 19 Jan 2016 15:10:06 -0600
Subject: [PATCH] Update docs to track complex number change (Fixes #108)

---
 doc/array.rst | 22 ++++++++++++++--------
 doc/misc.rst  |  8 ++++++++
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/doc/array.rst b/doc/array.rst
index 9078f6f1..8c3256eb 100644
--- a/doc/array.rst
+++ b/doc/array.rst
@@ -111,17 +111,23 @@ If you need double precision support, please::
 before including the header, as DP support apparently cannot be reliably
 autodetected.
 
-Under the hood, the complex types are simply `float2` and `double2`.
-
-.. warning::
-    Note that, at the OpenCL source code level, addition (real + complex) and
-    multiplication (complex*complex) are defined for e.g. `float2`, but yield
-    wrong results, so that you need to use the corresponding functions.
-    (The :mod:`Array` type implements complex arithmetic as you remember it,
-    without any idiotic quirks like this.)
+Under the hood, the complex types are struct types as defined in the header.
+Ideally, you should only access the structs through the provided functions,
+never directly.
 
 .. versionadded:: 2012.1
 
+.. versionchanged:: 2015.2
+
+    **[INCOMPATIBLE]** Changed PyOpenCL's complex numbers from ``float2`` and
+    ``double2`` OpenCL vector types to custom ``struct``. This was changed
+    because it very easily introduced bugs where
+
+    * complex*complex
+    * real+complex
+
+    *look* like they may do the right thing, but sliently do the wrong thing.
+
 The :class:`Array` Class
 ------------------------
 
diff --git a/doc/misc.rst b/doc/misc.rst
index 1da2f20f..6ef89aa5 100644
--- a/doc/misc.rst
+++ b/doc/misc.rst
@@ -143,6 +143,14 @@ Version 2015.2.1
 Version 2015.2
 --------------
 
+* **[INCOMPATIBLE]** Changed PyOpenCL's complex numbers from ``float2`` and
+  ``double2`` OpenCL vector types to custom ``struct``. This was changed
+  because it very easily introduced bugs where
+
+  * complex*complex
+  * real+complex
+
+  *look* like they may do the right thing, but sliently do the wrong thing.
 * Rewrite of the wrapper layer to be based on CFFI
 * Pypy compatibility
 * Faster kernel invocation through Python launcher code generation
-- 
GitLab