Amend optional documentation

gmx::compat::optional, or the respective std::optional in C++17
are compelling to over-use in some cases. Added developer
documentation on when optional<T> is not the best choice.

Change-Id: I9cbfd42968ab8797109e35eba7e01afe6a1507ae

diff --git a/docs/dev-manual/language-features.rst b/docs/dev-manual/language-features.rst
index 87fec394b4a66cd82bdd879ac8a4c5a1be5b9945..1422fb5e3936c9d3de95af3edd7caeaa2b91ede3 100644 (file)
--- a/docs/dev-manual/language-features.rst
+++ b/docs/dev-manual/language-features.rst
@@ -64,12 +64,19 @@ a release.
 * Use ``optional<T>`` types in situations where there is exactly one,
   reason (that is clear to all parties) for having no value of type T,
   and where the lack of value is as natural as having any regular
-  value of T. Good examples include the return type of a function that
-  parses an integer value from a string, searching for a matching
+  value of T, see |linkoptionalboost|. Good examples include the return type of a
+  function that parses an integer value from a string, searching for a matching
   element in a range, or providing an optional name for a residue
-  type. Prefer some other construct when the logic requires an
-  explanation of the reason why no regular value for T exists, ie.  do
-  not use ``optional<T>`` for error handling.
+  type. Do use optional for lazy loading of resources, e.g., objects that have
+  no default constructor and are hard to construct.
+  Prefer other constructs when the logic requires an explanation of the
+  reason why no regular value for T exists, e.g.,  do not use ``optional<T>``
+  for error handling. 
+  ``optional<T>`` "models an object, not a pointer, even though operator*() and
+  operator->() are defined" (|linkoptionalcppref|). No dynamic memory allocation
+  ever takes place and forward declaration of objects stored in ``optional<T>``
+  does not work. Thus refrain from optional when passing handles; in contrast to
+  unique_ptr, optional has value semantics, not reference semantics.
 * Don't use C-style casts; use ``const_cast``, ``static_cast`` or
   ``reinterpret_cast as appropriate``. See the point on RTTI for
   ``dynamic_cast``. For emphasizing type (e.g. intentional integer division)
@@ -165,8 +172,9 @@ a release.
 .. |linkrefnotnull1| replace:: `here <http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-nullptr>`__
 .. |linkrefnotnull2| replace:: `here <http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-nullptr>`__
 .. |linkrefstringview| replace:: `here <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines.html#Rstr-view>`__
-
-
+.. |linkoptionalboost| replace:: `here <https://www.boost.org/doc/libs/release/libs/optional>`__
+.. |linkoptionalbartek| replace:: `here <https://www.bfilipek.com/2018/05/using-optional.html>`__
+.. |linkoptionalcppref| replace:: `cppreference <https://en.cppreference.com/w/cpp/utility/optional>`__
 
 .. _implementing exceptions: