Added documentation for main routines.

doc/source/index.rst

@@ -3,8 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to m-unit-tests's documentation!
-========================================
+Dynare's m-unit-tests module
+============================
 
 Contents:
 
@@ -12,6 +12,112 @@ Contents:
    :maxdepth: 2
 
 
+.. function:: get_directory_description(basedir)
+
+   Returns a list of ``*.m`` files in directory ``basedir`` and its
+   subfolders. The input argument ``basedir`` is a string and the
+   returned argument is cell of strings with \\(n\\) elements where
+   each element is the relative address of a file. The default value
+   for ``basedir``is the current directory.
+
+
+.. function:: is_unitary_test_available(fname)
+
+   Returns ``1``  if unitary tests  defined in matlab  routine ``fname``
+   have  to be  run,  ``0`` otherwise.  The  mandatory input  argument
+   ``fname`` is a  string. The returned argument is set  equal to one if
+   and only if the first line contains the following comment:
+
+        .. code-block:: matlab
+           
+           % --*-- Unitary tests --*-- 
+
+   after the function header.
+
+
+.. function:: mtest(fname[, fpath])
+
+   Extracts  unit  test   sections  from  matlab's  routine  ``fname``
+   executes the tests and reports results.
+
+   **INPUTS**
+     - ``fname`` (*string*) Name of the Matlab routine where unit
+       tests to be run are defined.
+     - ``fpath`` (*string*) Path to the routine (optional).
+
+   **OUTPUTS**
+     - ``check`` (*integer*) Scalar equal to 0 if the test fails and 1
+       otherwise.
+     - ``info`` (*cell*) Describes the test results. Cell info has nn
+       rows and five columns. Each row correponds to a unitary test in
+       fname, and the columns report the following informations:
+
+       - Column 1 Name of the tested routine.
+       - Column 2 Number of the unitary test.
+       - Column 3 Status of the unitary test (0 if the unitary test fails, 1 otherwise).
+       - Column 4 Details about the failure (vector of 0 and 1).
+       - Column 5 Elapsed time in seconds (cpu time).
+
+   **REMARKS**
+     1. If only one input argument is provided, ``fname`` must contain
+        the full path to the routine.
+     2. For each unit test, :func:`mtest` generates a matlab function
+        saved in ``<fname>_test_x.m`` and runs the function. If the
+        function does not return errors the file is erased, otherwise the
+        file is kept on disk.
+
+.. function:: dtest(fname[, tpath])
+
+   Runs unit tests defined in ``fname``, by calling :func:`mtest`
+   routine, and displays the results.
+
+   **INPUTS**
+     - ``fname`` (*string*) Name (with path) of the Matlab routine
+       where unit tests to be run are defined.
+     - ``tpath`` (*string*) Path to the folder where the test routines
+       generated by :func:`mtest` should be temporarly saved
+       (optional, default value is the current directory).
+
+   **OUTPUTS**
+     None
+
+   **REMARKS**
+     1. The full path to the tested routine must be provided in ``fname``.
+
+.. function:: run_unitary_tests(listoffiles)
+
+   Runs unitary tests defined in a collection of files.
+
+   **INPUTS**
+     - ``listoffiles`` (*cell of strings*) The list of m files (with
+       path) where the unitary tests are written. This cell, with
+       \\(n\\) elements, is the output of :func:`get_directory_description` routine.
+
+   **OUTPUTS**
+     - ``report`` (*cell*) Results of the unitary tests (\\(n\\) rows
+       and five columns). Each row stores the second output argument
+       of :func:`mtest` routine (info).
+     - ``time`` (*double*) Current date and time as date vector (see
+       matlab's documentation for the ``clock`` function).
+
+
+.. function:: run_unitary_tests_in_directory(dirname[, savereport[, printreport, sendreport])
+
+   Runs all the unitary tests defined in a directory (and subfolders).
+
+   **INPUTS**
+     - ``dirname`` (*string*) Path to the directory.
+     - ``savereport`` (*integer*) Scalar equal to ``0`` or ``1``. If equal to ``1`` generated report is saved in a ``*.mat`` file.
+     - ``printreport`` (*integer*) Scalar equal to ``0`` or ``1``. If equal to ``1`` generated report is printed on screen.
+     - ``sendreport`` (*integer*) Scalar equal to ``0`` or ``1``. If equal to ``1`` generated report is sent by email.
+
+   **OUTPUTS**
+     - ``report`` (*cell*) First output argument of :func:`run_unitary_test routine`.
+
+   **REMARKS**
+     1. Git needs to be available on the system, and it is assumed that the content of ``dirname`` is versionned with Git.
+
+
 
 Indices and tables
 ==================