Add a guideline for describing method/function parameters and configuration parameters (#2869)

* Add guidelines
* Update examples so they match the requirements

Author: patiencedaur

doc/contributing/docs/_includes/class_template.rst

@@ -4,20 +4,20 @@
 
         Search for a tuple :ref:`via the given index <box_index-note>`.
 
-        :param index_object index_object: an :ref:`object reference
-                                          <app_server-object_reference>`.
+        :param index_object index_object: :ref:`object reference
+                                          <app_server-object_reference>`
         :param scalar/table      key: values to be matched against the index key
 
         :return: the tuple whose index-key fields are equal to the passed key values
         :rtype:  tuple
 
         **Possible errors:**
 
-        * no such index;
-        * wrong type;
-        * more than one tuple matches.
+        * No such index
+        * Wrong type
+        * More than one tuple matches
 
-        **Complexity factors:** Index size, Index type.
+        **Complexity factors:** index size, index type.
         See also :ref:`space_object:get() <box_space-get>`.
 
         **Example:**

doc/contributing/docs/_includes/confval_template.rst

@@ -0,0 +1,13 @@
+..  confval:: wal_dir
+
+    Since version 1.6.2.
+    A directory where write-ahead log (``.xlog``) files are stored.
+    Can be relative to :ref:`work_dir <cfg_basic-work_dir>`.
+    Sometimes ``wal_dir`` and :ref:`memtx_dir <cfg_basic-memtx_dir>` are specified with different values,
+    so that write-ahead log files and snapshot files can be stored on different disks.
+    If not specified, defaults to ``work_dir``.
+
+    | Type: string
+    | Default: "."
+    | Environment variable: TT_WAL_DIR
+    | Dynamic: no

doc/contributing/docs/examples.rst

@@ -6,18 +6,18 @@ as well as examples and templates.
 
 Use this checklist for documenting a function or a method:
 
-* Base description
-* Parameters
-* What this function returns (if nothing, write 'none')
-* Return type (if exists)
-* Possible errors (if exist)
-* Complexity factors (if exist)
-* Usage with memtx and vinyl (if differs)
-* Example(s)
-* Extra information (if needed)
+*   General description
+*   :ref:`Parameters <documenting_parameters>`
+*   What this function returns (if nothing, write 'none')
+*   Return type (if exists)
+*   Possible errors (if exist)
+*   Complexity factors (if exist)
+*   Usage with memtx and vinyl (if differs)
+*   Example(s)
+*   Extra information (if needed)
 
 Documenting functions
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 We use the Sphinx directives ``.. module::``
 and ``.. function::`` to describe functions of Tarantool modules:
@@ -29,8 +29,12 @@ The resulting output looks like this:
 
 ..  include:: ./_includes/function_template.rst
 
+..  note::
+
+    The best practices for :ref:`parameter description <documenting_parameters>` are listed below.
+
 Documenting class methods and data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
 Methods are described similarly to functions, but the ``.. class::``
 directive, unlike ``.. module::``, requires nesting.
@@ -46,3 +50,52 @@ the method and data of the ``index_object`` class:
 And the resulting output looks like this:
 
 ..  include:: ./_includes/class_template.rst
+
+..  note::
+
+    The best practices for :ref:`parameter description <documenting_parameters>` are listed below.
+
+..  _documenting_parameters:
+
+Parameters in functions and classes
+-----------------------------------
+
+This section explains how to document specific function or class method parameters as described above.
+To learn how to document :doc:`configuration parameters </reference/configuration/index>`
+passed to Tarantool via the command line or in an initialization file,
+see the :ref:`next section <documenting_confvals>`.
+
+For every function or class method parameter, list the following details:
+
+*   General description
+*   Type
+*   If optional, indicate *(optional)* in parentheses
+*   Default value (if optional), possible values
+
+In the "Possible errors" section of the function or class method,
+consider explaining what happens if the parameter hasn't been defined or has the wrong value.
+
+..  _documenting_confvals:
+
+Configuration parameters
+------------------------
+
+For every configuration parameter, list the following details:
+
+*   Since which Tarantool version
+*   General description
+*   Type
+*   Corresponding environment variable (if applicable)
+*   Default value
+*   Possible values
+*   Dynamic (yes or no)
+
+Example
+^^^^^^^
+
+..  literalinclude:: ./_includes/confval_template.rst
+    :language: rst
+
+Result:
+
+..  include:: ./_includes/confval_template.rst