doc

Author: d-a-v

doc/reference.rst

@@ -219,9 +219,9 @@ using FPSTR would become...
 C++
 ----
 
-- About C++ `new` operator and return value
+- About C++ ``operator new`` and return value and its replacement ``new0<>()``
 
-  The C++ standard says the following about the `new` operator behavior when encountering heap shortage (memory full):
+  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
 
@@ -237,17 +237,17 @@ C++
 
   When C++ exceptions are disabled, or when using new(nothrow), the above guarantees can't be upheld, so the second point above is the only viable solution.
 
-  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.
+  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:
+  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 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:
 
   Syntax is slightly different, the following shows the different usages: