[doc] Document deprecation of returning references

The deprecation tag in doxygen is here to warn users. We cannot
mark the method as deprecated directly, because only the return
type will change.

dune/geometry/referenceelement.hh

@@ -137,6 +137,10 @@ namespace Dune {
        *  Denote by E the i-th subentity of codimension c of the current
        *  reference element. This method returns the GeometryType of E.
        *
+       *  \deprecated After dune-2.6 the return value will no longer be
+       *              a reference but a copy. Code storing pointers
+       *              or references to the result must be adjusted.
+       *
        *  \param[in]  i      number of subentity E (0 <= i < size( c ))
        *  \param[in]  c      codimension of subentity E
        */
@@ -146,7 +150,13 @@ namespace Dune {
       }
 
 
-      /** \brief obtain the type of this reference element */
+      /** \brief obtain the type of this reference element
+       *
+       *  \deprecated After dune-2.6 the return value will no longer be
+       *              a reference but a copy. Code storing pointers
+       *              or references to the result must be adjusted.
+       *
+       */
       decltype(auto) type() const
       {
         return _impl->type();
@@ -159,6 +169,10 @@ namespace Dune {
        *  reference element. This method returns the coordinates of
        *  the center of gravity of E within the current reference element.
        *
+       *  \deprecated After dune-2.6 the return value will no longer be
+       *              a reference but a copy. Code storing pointers
+       *              or references to the result must be adjusted.
+       *
        *  \param[in]  i   number of subentity E (0 <= i < size( c ))
        *  \param[in]  c   codimension of subentity E
        */
@@ -211,6 +225,10 @@ namespace Dune {
        *  The integration outer normal is the outer normal whose length coincides
        *  with the face's integration element.
        *
+       *  \deprecated After dune-2.6 the return value will no longer be
+       *              a reference but a copy. Code storing pointers
+       *              or references to the result must be adjusted.
+       *
        *  \param[in]  face  index of the face, whose normal is desired
        */
       decltype(auto) integrationOuterNormal(int face) const