Docs fine tuning

Author: Vasileios Karakasis

docs/deferrable_functions_reference.rst

@@ -10,6 +10,7 @@ The key characteristic of these functions is that they store their arguments whe
 ReFrame provides an ample set of deferrable utilities and it also allows users to write their own deferrable functions when needed.
 Please refer to ":doc:`deferrables`" for a hands-on explanation on how deferrable functions work and how to create custom deferrable functions.
 
+
 Explicit evaluation of deferrable functions
 -------------------------------------------
 
@@ -18,7 +19,8 @@ These :func:`evaluate` functions take an optional :class:`bool` argument ``cache
 Hence, if caching is enabled on a given deferrable function, any subsequent calls to :func:`evaluate` will simply return the previously cached results.
 
 .. versionchanged:: 3.8.0
-   Support cached evaluation.
+   Support of cached evaluation is added.
+
 
 Implicit evaluation of deferrable functions
 -------------------------------------------
@@ -58,16 +60,19 @@ Currently ReFrame provides three broad categories of deferrable functions:
 
  .. _deferrable-performance-functions:
 
+
+--------------------------------
 Deferrable performance functions
-................................
+--------------------------------
+
+.. versionadded:: 3.8.0
 
 Deferrable performance functions are a special type of deferrable functions which are intended for measuring a given quantity.
 Therefore, this kind of deferrable functions have an associated unit that can be used to interpret the return values from these functions.
 The unit of a deferrable performance function can be accessed through the public member :attr:`unit`.
 Regular deferrable functions can be promoted to deferrable performance functions using the :func:`~reframe.utility.sanity.make_performance_function` utility.
 Also, this utility allows to create performance functions directly from any callable.
 
-.. versionadded:: 3.8.0
 
 List of deferrable functions and utilities
 ------------------------------------------

docs/regression_test_api.rst

@@ -326,7 +326,7 @@ Built-in functions
 
    Decorate a member function as a performance function of the test.
 
-   This decorator converts the decorated method into a performance deferrable function (see :ref:`deferrable-performance-functions`) whose evaluation is deferred to the performance stage of the regression test.
+   This decorator converts the decorated method into a performance deferrable function (see ":ref:`deferrable-performance-functions`" for more details) whose evaluation is deferred to the performance stage of the regression test.
    The decorated function must take a single argument without a default value (i.e. ``self``) and any number of arguments with default values.
    A test may decorate multiple member functions as performance functions, where each of the decorated functions must be provided with the units of the performance quantitites to be extracted from the test.
    These performance units must be of type :class:`str`.

reframe/core/pipeline.py

@@ -657,9 +657,10 @@ def pipeline_hooks(cls):
     #:
     #: By default, ReFrame will populate this field during the test's
     #: instantiation with all the member functions decorated with the
-    #: :func:`performance_function` decorator. If no performance functions
-    #: are present in the class, no performance checking or reporting will be
-    #: carried out.
+    #: :func:`@performance_function
+    #: <reframe.core.pipeline.RegressionMixin.performance_function>` decorator.
+    #: If no performance functions are present in the class, no performance
+    #: checking or reporting will be carried out.
     #:
     #: This mapping may be extended or replaced by other performance variables
     #: that may be defined in any pipeline hook executing before the
@@ -677,6 +678,8 @@ def pipeline_hooks(cls):
     #:     the member functions decorated with the :func:`@performance_function
     #:     <reframe.core.pipeline.RegressionMixin.performance_function>`
     #:     decorator.
+    #:
+    #: .. versionadded:: 3.8.0
     perf_variables = variable(typ.Dict[str, _DeferredPerformanceExpression],
                               value={})
 

reframe/utility/__init__.py

@@ -305,7 +305,7 @@ def attrs(obj):
 
 
 def is_trivially_callable(fn, *, non_def_args=0):
-    '''Assert that a callable object is trivially callable.
+    '''Check that a callable object is trivially callable.
 
     An object is trivially callable when it can be invoked by providing just
     an expected number of non-default arguments to its call method. For
@@ -319,9 +319,9 @@ def is_trivially_callable(fn, *, non_def_args=0):
     :param fn: A callable to be tested if its trivially callable.
     :param non_def_args: The number of non-default arguments the callable
       ``fn`` expects when invoked.
-    :return: This function returns ``True`` if the expected number of
+    :return: This function returns :obj:`True` if the expected number of
       arguments matches the value of ``non_def_args``. Otherwise, it returns
-      ``False``.
+      :obj:`False`.
     '''
 
     if not callable(fn):

reframe/utility/sanity.py

@@ -919,6 +919,9 @@ def evaluate(expr, cache=False):
     to :func:`evaluate` on this deferred expression (when ``cache=False``)
     will simply return the previously cached result.
 
+    :param expr: The expression to be evaluated.
+    :param cache: Cache the result of this evaluation.
+
     .. note::
        When the ``cache`` argument is passed as ``True``, a deferred
        expression will always be evaluated and its results will be re-cached.
@@ -928,8 +931,9 @@ def evaluate(expr, cache=False):
     .. versionadded:: 2.21
 
     .. versionchanged:: 3.8.0
-       Add support for evaluation caching.
+       The ``cache`` argument is added.
     '''
+
     if isinstance(expr, _DeferredExpression):
         return expr.evaluate(cache=cache)
     else: