Update info about arithmetic operations with datetime and interal objects

Part of #2835

Author: veod32

doc/reference/reference_lua/datetime.rst

@@ -49,6 +49,9 @@ Below is a list of the ``datetime`` module functions and methods.
         *   -   :ref:`interval_object:totable() <interval-totable>`
             -   Convert the information from an ``interval`` object into the table format.
 
+        *   -   :doc:`./datetime/interval_arithm`
+            -   ... [TBD]
+
 ..  toctree::
     :hidden:
 

doc/reference/reference_lua/datetime/datetime_object.rst

@@ -92,14 +92,14 @@ datetime_object
 
     ..  _datetime-format:
 
-    ..  method:: format( ['convensions'] )
+    ..  method:: format( ['convensions'] ) [TBD]
 
         Convert the standard ``datetime`` object presentation into a formatted string.
-        The formatting convension specifications are the same as in the `strftime <https://www.freebsd.org/cgi/man.cgi?query=strftime&sektion=3>`__ library.
+        The formatting convension specifications are the same as in the `strftime <https://www.freebsd.org/cgi/man.cgi?query=strftime&sektion=3>`__ library. [TBD]
         Additional convension for nanoseconds is `%f` which also allows a modifier to control the output precision of fractional part: `%5f` (see the example below).
         If no arguments are set for the method, the default convensions are used: `'%FT%T.%f%z'` (see the example below).
 
-        :param string convensions: string consisting of zero or more conversion specifications and ordinary characters
+        :param string convensions: string consisting of zero or more conversion specifications and ordinary characters [TBD]
 
         :return: string with the formatted date and time information
         :rtype: string
@@ -251,7 +251,7 @@ datetime_object
 
         :param table input: an :ref:`interval object <interval-new>` or an equivalent table (see **Example #1**)
         :param string adjust: defines how to round days in a month after an arithmetic operation.
-                                Possible values: ``none``, ``last``, ``excess`` (see **Example #2**). Defaults to ``none``.
+                                Possible values: ``none``, ``last``, ``excess`` (see **Example #2**). Defaults to ``none``. [TBD]
 
         :return: datetime_object
         :rtype: cdata

doc/reference/reference_lua/datetime/interval_arithm.rst

@@ -0,0 +1,94 @@
+.. _inverval_arithm:
+
+Inverval arithmetic
+===================
+
+Since :doc:`2.10.0 </release/2.10.0>`.
+
+The :doc:`datetime module </reference/reference_lua/datetime>` enables creating objects of two types: ``datetime`` and ``interval``.
+
+If you need to shift the ``datetime`` object values, you can use either the modifier methods, that is, the :ref:`:add <datetime-add>` or :ref:`:sub <datetime-sub>` methods,
+or apply interval arithmetic using overloaded `+ (__add)` or `- (__sub)` methods.
+
+``:add``/``:sub`` modify the current object, but ``+``/``+`` create copy of the object as the operation result.
+
+In the interval operation, each of the interval subcomponents are sequentially calculated starting from the largest (``year``) to the smallest (``nsec``):
+
+*   year -- years
+*   month -- months
+*   week -- weeks
+*   day -- days
+*   hour -- hours
+*   min -- minutes
+*   sec -- seconds
+*   nsec -- nanoseconds.
+
+If results of the operation exceed the allowed range for any of the components, an exception is raised.
+
+The ``datetime`` and ``interval`` objects can participate in arithmetic operations:
+
+*   The sum of two intervals is an interval object, which fields are sum of each particular component of operands.
+
+*   The result of subtraction of two intervals is similar: it's an interval object where each subcomponent is the result of subtraction of particular fields in the original operands.
+
+*   If you add datetime and interval objects, the result is a datetime object. Addition is being performed in a determined order from the largest component (``year``) to the smallest (``nsec``).
+
+*   Subtraction of two datetime objects produce an interval object. Difference of two time values is performed not as difference of the epoch seconds, but as difference of all the subcomponents, that is, years, months, days, hours, minutes, and seconds.
+
+*   An untyped table object can be used in each context where the typed datetime or interval objects are used if left operand is typed object with overloaded operation of ``+`` or ``-``.
+
+The matrix of the ``addition`` operands eligibility and their result types:
+
+..  container:: table
+
+    ..  list-table::
+        :widths: 25 25 25 25
+        :header-rows: 1
+
+        *    -
+            -   datetime
+            -   interval
+            -   table
+
+        *   -   **datetime**
+            -
+            -   datetime
+            -   datetime
+
+        *   -   **interval**
+            -   datetime
+            -   interval
+            -   interval
+
+        *   -   **table**
+            -
+            -
+            -
+
+The matrix of the ``subtraction`` operands eligibility and their result types:
+
+..  container:: table
+
+    ..  list-table::
+        :widths: 25 25 25 25
+        :header-rows: 1
+
+        *    -
+            -   datetime
+            -   interval
+            -   table
+
+        *   -   **datetime**
+            -   interval
+            -   datetime
+            -   datetime
+
+        *   -   **interval**
+            -
+            -   interval
+            -   interval
+
+        *   -   **table**
+            -
+            -
+            -

doc/reference/reference_lua/datetime/interval_new.rst

@@ -13,7 +13,7 @@ datetime.interval.new()
     :param table input: Table with :ref:`time units and parameters<interval-new-args>`. For all possible time units, the values are not restricted.
                                 If an empty table or no arguments are passed, the ``interval`` object with the default value ``0 seconds`` is created.
 
-    :return: :doc: interval object
+    :return: interval_object
     :rtype: cdata
 
     ..  _interval-new-args:

doc/reference/reference_lua/datetime/new.rst

@@ -18,7 +18,7 @@ datetime.new()
 
     ..  _datetime-new-args:
 
-    **Possible input time units for ``datetime.new()**
+    **Possible input time units for ``datetime.new()``**
 
     ..  container:: table