* clarify the situation with experimental parts

* remove all what was marked deprecated

doc/Doxyfile.in

@@ -214,7 +214,7 @@ ALIASES                = "only_for_vectors=This is only for vectors (either row-
                          "addexample=\anchor"  \
                          "label=\bug" \
                          "redstar=<a href='#warningarraymodule' style='color:red;text-decoration: none;'>*</a>" \
-                         "nonstableyet=\warning This class/function is not considered to be part of the stable public API yet. Some (minor) changes might happen in future releases."
+                         "nonstableyet=\warning This class/function is not considered to be part of the stable public API yet. Changes may happen in future releases. See \ref Experimental \"Experimental parts of Eigen\""
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
 # sources only. Doxygen will then generate output that is more tailored for C.

doc/Experimental.dox

@@ -0,0 +1,47 @@
+namespace Eigen {
+
+/** \page Experimental Experimental parts of Eigen
+
+\b Table \b of \b contents
+  - \ref summary
+  - \ref modules
+  - \ref core
+
+\section summary Summary
+
+Experimental features may at any time:
+\li be removed;
+\li be subject to an API incompatible change;
+\li introduce API or ABI incompatible changes in your own application if you let them affect your API or ABI.
+
+\section modules Experimental modules
+
+The following modules are considered entirely experimental:
+\li SVD
+\li QR
+\li Sparse
+
+\section core Experimental parts of the Core module
+
+In the Core module, the only classes subject to ABI stability guarantee (meaning that you can use it for data members in your public ABI) is:
+\li Matrix
+\li Map
+
+All other classes offer no ABI guarantee, e.g. the layout of their data can be changed.
+
+The only classes subject to (even partial) API stability guarantee (meaning that you can safely construct and use objects) are:
+\li MatrixBase : partial API stability (see below)
+\li Matrix : full API stability (except for experimental stuff inherited from MatrixBase)
+\li Map : full API stability (except for experimental stuff inherited from MatrixBase)
+
+All other classes offer no direct API guarantee, e.g. their methods can be changed; however notice that most classes inherit MatrixBase and that this is where most of their API comes from -- so in practice most of the API is stable.
+
+Here are the MatrixBase methods that are considered experimental, hence not part of any API stability guarantee:
+\li all methods documented as internal
+\li all methods hidden in the Doxygen documentation
+\li all methods marked as experimental
+\li all methods defined in experimental modules
+
+*/
+
+}