From e7fbbc2748dac4addbc429e053ead795968d86c6 Mon Sep 17 00:00:00 2001
From: Gael Guennebaud <g.gael@free.fr>
Date: Tue, 30 Aug 2016 15:57:46 +0200
Subject: [PATCH] Doc: add links and discourage user to write their own
 expression (better use CwiseNullaryOp)

---
 Eigen/src/Core/CwiseNullaryOp.h      | 5 +++++
 doc/CustomizingEigen_NullaryExpr.dox | 5 +++--
 doc/NewExpressionType.dox            | 6 ++++++
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/Eigen/src/Core/CwiseNullaryOp.h b/Eigen/src/Core/CwiseNullaryOp.h
index ea1d463a6..bc3b3f240 100644
--- a/Eigen/src/Core/CwiseNullaryOp.h
+++ b/Eigen/src/Core/CwiseNullaryOp.h
@@ -40,6 +40,11 @@ struct traits<CwiseNullaryOp<NullaryOp, PlainObjectType> > : traits<PlainObjectT
   * See DenseBase::NullaryExpr(Index,const CustomNullaryOp&) for an example binding
   * C++11 random number generators.
   *
+  * A nullary expression can also be used to implement custom sophisticated matrix manipulations
+  * that cannot be covered by the existing set of natively supported matrix manipulations.
+  * See this \ref TopicCustomizing_NullaryExpr "page" for some examples and additional explanations
+  * on the behavior of CwiseNullaryOp.
+  *
   * \sa class CwiseUnaryOp, class CwiseBinaryOp, DenseBase::NullaryExpr
   */
 template<typename NullaryOp, typename PlainObjectType>
diff --git a/doc/CustomizingEigen_NullaryExpr.dox b/doc/CustomizingEigen_NullaryExpr.dox
index 9352c3d73..cefa5317c 100644
--- a/doc/CustomizingEigen_NullaryExpr.dox
+++ b/doc/CustomizingEigen_NullaryExpr.dox
@@ -1,11 +1,12 @@
 namespace Eigen {
 
-/** \page TopicCustomizing_NullaryExpr Manipulate matrices through nullary-expression
+/** \page TopicCustomizing_NullaryExpr Matrix manipulation via nullary-expressions
+
 
 The main purpose of the class CwiseNullaryOp is to define \em procedural matrices such as constant or random matrices as returned by the Ones(), Zero(), Constant(), Identity() and Random() methods.
 Nevertheless, with some imagination it is possible to accomplish very sophisticated matrix manipulation with minimal efforts such that \ref TopicNewExpressionType "implementing new expression" is rarely needed.
 
-\section NullaryExpr_Circulant
+\section NullaryExpr_Circulant Example 1: circulant matrix
 
 To explore these possibilities let us start with the  \em circulant example of the \ref TopicNewExpressionType "implementing new expression" topic.
 Let us recall that a circulant matrix is a matrix where each column is the same as the
diff --git a/doc/NewExpressionType.dox b/doc/NewExpressionType.dox
index c2e78bfee..c2f243312 100644
--- a/doc/NewExpressionType.dox
+++ b/doc/NewExpressionType.dox
@@ -2,6 +2,12 @@ namespace Eigen {
 
 /** \page TopicNewExpressionType Adding a new expression type
 
+<!--<span style="font-size:130%; color:red; font-weight: 900;"></span>-->
+\warning
+Disclaimer: this page is tailored to very advanced users who are not afraid of dealing with some %Eigen's internal aspects.
+In most cases, a custom expression can be avoided by either using custom \ref MatrixBase::unaryExpr "unary" or \ref MatrixBase::binaryExpr "binary" functors,
+while extremely complex matrix manipulations can be achieved by a nullary functors as described in the \ref TopicCustomizing_NullaryExpr "previous page".
+
 This page describes with the help of an example how to implement a new
 light-weight expression type in %Eigen. This consists of three parts:
 the expression type itself, a traits class containing compile-time