doc

Author: d-a-v

doc/reference.rst

@@ -223,13 +223,13 @@ C++
 
   The C++ standard says the following about the ``new`` operator behavior when encountering heap shortage (memory full):
 
-  - has to throw a std::bad_alloc C++ exception
+  - has to throw a ``std::bad_alloc`` C++ exception
 
-  - throw an unhandled exception, which means calling abort()
+  - throw an unhandled exception, which means calling ``abort()``
 
   There are several reasons for the first point above, among which are:
 
-  - guarantee that the return of new is never a nullptr
+  - guarantee that the return of new is never a ``nullptr``
 
   - guarantee full construction of the top level object plus all member subobjects
 
@@ -239,15 +239,15 @@ C++
 
   Historically in Arduino environments, ``new`` is overloaded to simply return the equivalent ``malloc()`` which in turn can return ``nullptr``. In other cores, and up to our core version 2.5.2, that is considered as acceptable.
 
-  However, this behavior is not C++ standard, and there is good reason for that: there are hidden and very bad side effects. The class and member constructors are always called, even when memory is full (``this``=``nullptr``). In addition, the memory allocation for the top object could succeed, but allocation required for some member object could fail, leaving construction in an undefined state. So the historical behavior of Ardudino's ``new``, when faced with insufficient memory, will lead to bad crashes sooner or later, sometimes unexplainable, generally due to memory corruption even when the returned value is checked and managed.
+  However, this behavior is not C++ standard, and there is good reason for that: there are hidden and very bad side effects. The *class and member constructors are always called, even when memory is full* (``this``=``nullptr``). In addition, the memory allocation for the top object could succeed, but allocation required for some member object could fail, leaving construction in an undefined state. So the historical behavior of Ardudino's ``new``, when faced with insufficient memory, will lead to bad crashes sooner or later, sometimes unexplainable, generally due to memory corruption even when the returned value is checked and managed.
 
   As of core 2.6.0, we are sticking to the C++ standard. There are two clear cases when ``new`` encounters oom:
 
   - C++ exceptions are disabled (default build): ``new`` causes an exception, which in turn calls ``abort()`` and will "cleanly" crash, because there is no way to honor memory allocation or to recover gracefully.
 
-  - C++ exceptions are enabled (menu option): ``new`` throws a std::bad_alloc C++ exception, which can be caught and handled gracefully. This assures correct behavior, including handling of all subobjects, which guarantees stability.
+  - C++ exceptions are enabled (menu option): ``new`` throws a ``std::bad_alloc`` C++ exception, which can be caught and handled gracefully. This assures correct behavior, including handling of all subobjects, which guarantees stability.
 
-  To allow previous behavior, a new optional global allocator is introduced with a different semantic. It is similar to ``new`` but will return ``nullptr`` without side effects (if ``std::new`` is not used in constructors), as expected in arduino world. Syntax is slightly different:
+  To allow previous behavior, a new optional global allocator is introduced with a different semantic. It is similar to ``new`` but will return ``nullptr`` without side effects (if ``std::new`` is not used in constructors), as expected in arduino world.
 
   Syntax is slightly different, the following shows the different usages:
 
@@ -268,7 +268,7 @@ C++
       // abort() is never called, an exception is not thrown even if they are enabled
       if (sc == nullptr)
       {
-        // failed allocation
+        // failed allocation, handle here, possible bad hidden effects
       }
       else
       {