doc: SCHWED-3149 document findings about the deprecation warning in the code

modules/gfx/pymod/export_primlist.cc

@@ -26,6 +26,36 @@ using namespace boost::python;
 using namespace ost;
 using namespace ost::gfx;
 
+/* The following #include triggers a deprecation warning upon compilation:
+
+In file included from /unibas/lcs-software/software/Python/2.7.11-goolf-1.7.20/lib/python2.7/site-packages/numpy/core/include/numpy/ndarraytypes.h:1781:0,
+                 from /unibas/lcs-software/software/Python/2.7.11-goolf-1.7.20/lib/python2.7/site-packages/numpy/core/include/numpy/ndarrayobject.h:18,
+                 from /unibas/lcs-software/software/Python/2.7.11-goolf-1.7.20/lib/python2.7/site-packages/numpy/core/include/numpy/arrayobject.h:4,
+                 from /home/zohixe92/build/ost-develop/modules/gfx/pymod/export_primlist.cc:30:
+/unibas/lcs-software/software/Python/2.7.11-goolf-1.7.20/lib/python2.7/site-packages/numpy/core/include/numpy/npy_1_7_deprecated_api.h:15:2: warning: #warning "Using deprecated NumPy API, disable it by " "#defining NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION" [-Wcpp]
+ #warning "Using deprecated NumPy API, disable it by " \
+  ^
+
+It looks like just including <numpy/arrayobject.h>, without actually using anything from it, already triggers the
+warning. This could be a side effect of other includes in export_primlist.cc though, such as boost.
+
+The Numpy C API documentation <https://docs.scipy.org/doc/numpy-1.15.1/reference/c-api.deprecations.html> is very
+unclear about what is deprecated exactly (the whole API or only direct data access?) The Array API doc
+<https://docs.scipy.org/doc/numpy-1.16.0/reference/c-api.array.html> doesn't clearly state what to import instead,
+and while some functions are marked as deprecated I couldn't see that we are using any of them. Last, the migration sed
+script <https://github.com/numpy/numpy/blob/master/tools/replace_old_macros.sed> didn't trigger any changes.
+
+The warnings appear to be safe though, behavior has been checked in <https://jira.biozentrum.unibas.ch/browse/SCHWED-3149>
+and Numpy guarantees to maintain them until the next major release (2.0). So it is safe to ignore them for now.
+They can be silenced with the following #define, however it was decided to keep them for now as functionality *will*
+disappear in the future.
+
+#define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION
+
+In the future it might be desirable to move to the newer API in Boost::Python::NumPy
+which uses modern C++ instead of old-style C macros.
+<https://www.boost.org/doc/libs/1_64_0/libs/python/doc/html/numpy/reference/ndarray.html>
+*/
 #if OST_NUMPY_SUPPORT_ENABLED
 #include <numpy/arrayobject.h>
 #endif