Fixed some documentation issues

bob/learn/em/isv_machine.cpp

@@ -16,7 +16,7 @@
 static auto ISVMachine_doc = bob::extension::ClassDoc(
   BOB_EXT_MODULE_PREFIX ".ISVMachine",
   "A ISVMachine. An attached :py:class:`bob.learn.em.ISVBase` should be provided for Joint Factor Analysis. The :py:class:`bob.learn.em.ISVMachine` carries information about the speaker factors :math:`y` and :math:`z`, whereas a :py:class:`bob.learn.em.JFABase` carries information about the matrices :math:`U` and :math:`D`.\n\n"
-  "References: [Vogt2008_ [McCool2013]_",
+  "References: [Vogt2008]_ [McCool2013]_",
   ""
 ).add_constructor(
   bob::extension::FunctionDoc(

bob/learn/em/plda_trainer.cpp

@@ -94,9 +94,9 @@ static PyObject* vector_as_list(const std::vector<blitz::Array<double,N> >& vec)
 
 static auto PLDATrainer_doc = bob::extension::ClassDoc(
   BOB_EXT_MODULE_PREFIX ".PLDATrainer",
-  "This class can be used to train the :math:`$F$`, :math:`$G$ and "
-  " :math:`$\\Sigma$` matrices and the mean vector :math:`$\\mu$` of a PLDA model."
-  "References: [ElShafey2014,PrinceElder2007,LiFu2012]",
+  "This class can be used to train the :math:`F`, :math:`G` and "
+  " :math:`\\Sigma` matrices and the mean vector :math:`\\mu` of a PLDA model."
+  "References: [ElShafey2014]_,[PrinceElder2007]_,[LiFu2012]_",
   ""
 ).add_constructor(
   bob::extension::FunctionDoc(

bob/learn/em/train.py

@@ -8,7 +8,23 @@ import numpy
 import bob.learn.em
 
 def train(trainer, machine, data, max_iterations = 50, convergence_threshold=None, initialize=True):
+  """
+  Trains a machine given a trainer and the proper data
 
+  **Parameters**:
+    trainer
+      A trainer mechanism
+    machine
+      A container machine
+    data 
+      The data to be trained
+    max_iterations
+      The maximum number of iterations to train a machine
+    convergence_threshold
+      The convergence threshold to train a machine. If None, the training procedure will stop with the iterations criteria
+    initialize
+      If True, runs the initialization procedure
+  """
   #Initialization
   if initialize:
     trainer.initialize(machine, data)
@@ -37,6 +53,21 @@ def train(trainer, machine, data, max_iterations = 50, convergence_threshold=Non
 
 
 def train_jfa(trainer, jfa_base, data, max_iterations=10, initialize=True):
+  """
+  Trains a :py:class`bob.learn.em.JFABase` given a :py:class`bob.learn.em.JFATrainer` and the proper data
+
+  **Parameters**:
+    trainer
+      A trainer mechanism (:py:class`bob.learn.em.JFATrainer`)
+    machine
+      A container machine (:py:class`bob.learn.em.JFABase`)
+    data
+      The data to be trained list(list(:py:class`bob.learn.em.GMMStats`))
+    max_iterations
+      The maximum number of iterations to train a machine
+    initialize
+      If True, runs the initialization procedure
+  """
 
   if initialize:
     trainer.initialize(jfa_base, data)

bob/learn/em/ztnorm.cpp

@@ -12,17 +12,18 @@
 /*** zt_norm ***/
 bob::extension::FunctionDoc zt_norm = bob::extension::FunctionDoc(
   "ztnorm",
-  "",
+  "Normalise raw scores with ZT-Norm."
+  "Assume that znorm and tnorm have no common subject id.",
   0,
   true
 )
 .add_prototype("rawscores_probes_vs_models,rawscores_zprobes_vs_models,rawscores_probes_vs_tmodels,rawscores_zprobes_vs_tmodels,mask_zprobes_vs_tmodels_istruetrial", "output")
-.add_parameter("rawscores_probes_vs_models", "array_like <float, 2D>", "")
-.add_parameter("rawscores_zprobes_vs_models", "array_like <float, 2D>", "")
-.add_parameter("rawscores_probes_vs_tmodels", "array_like <float, 2D>", "")
-.add_parameter("rawscores_zprobes_vs_tmodels", "array_like <float, 2D>", "")
+.add_parameter("rawscores_probes_vs_models", "array_like <float, 2D>", "Raw set of scores")
+.add_parameter("rawscores_zprobes_vs_models", "array_like <float, 2D>", "Z-Scores (raw scores of the Z probes against the models)")
+.add_parameter("rawscores_probes_vs_tmodels", "array_like <float, 2D>", "T-Scores (raw scores of the T probes against the models)")
+.add_parameter("rawscores_zprobes_vs_tmodels", "array_like <float, 2D>", "ZT-Scores (raw scores of the Z probes against the T-models)")
 .add_parameter("mask_zprobes_vs_tmodels_istruetrial", "array_like <float, 2D>", "")
-.add_return("output","array_like <float, 2D>","");
+.add_return("output","array_like <float, 2D>","The scores ZT Normalized");
 PyObject* PyBobLearnEM_ztNorm(PyObject*, PyObject* args, PyObject* kwargs) {
 
   char** kwlist = zt_norm.kwlist(0);
@@ -73,14 +74,14 @@ PyObject* PyBobLearnEM_ztNorm(PyObject*, PyObject* args, PyObject* kwargs) {
 /*** t_norm ***/
 bob::extension::FunctionDoc t_norm = bob::extension::FunctionDoc(
   "tnorm",
-  "",
+  "Normalise raw scores with T-Norm",
   0,
   true
 )
 .add_prototype("rawscores_probes_vs_models,rawscores_probes_vs_tmodels", "output")
-.add_parameter("rawscores_probes_vs_models", "array_like <float, 2D>", "")
-.add_parameter("rawscores_probes_vs_tmodels", "array_like <float, 2D>", "")
-.add_return("output","array_like <float, 2D>","");
+.add_parameter("rawscores_probes_vs_models", "array_like <float, 2D>", "Raw set of scores")
+.add_parameter("rawscores_probes_vs_tmodels", "array_like <float, 2D>", "T-Scores (raw scores of the T probes against the models)")
+.add_return("output","array_like <float, 2D>","The scores T Normalized");
 PyObject* PyBobLearnEM_tNorm(PyObject*, PyObject* args, PyObject* kwargs) {
 
   char** kwlist = zt_norm.kwlist(0);
@@ -110,14 +111,14 @@ PyObject* PyBobLearnEM_tNorm(PyObject*, PyObject* args, PyObject* kwargs) {
 /*** z_norm ***/
 bob::extension::FunctionDoc z_norm = bob::extension::FunctionDoc(
   "znorm",
-  "",
+  "Normalise raw scores with Z-Norm",
   0,
   true
 )
 .add_prototype("rawscores_probes_vs_models,rawscores_zprobes_vs_models", "output")
-.add_parameter("rawscores_probes_vs_models", "array_like <float, 2D>", "")
-.add_parameter("rawscores_zprobes_vs_models", "array_like <float, 2D>", "")
-.add_return("output","array_like <float, 2D>","");
+.add_parameter("rawscores_probes_vs_models", "array_like <float, 2D>", "Raw set of scores")
+.add_parameter("rawscores_zprobes_vs_models", "array_like <float, 2D>", "Z-Scores (raw scores of the Z probes against the models)")
+.add_return("output","array_like <float, 2D>","The scores T Normalized");
 PyObject* PyBobLearnEM_zNorm(PyObject*, PyObject* args, PyObject* kwargs) {
 
   char** kwlist = zt_norm.kwlist(0);