add some comments

1 files changed, 31 insertions, 8 deletions

diff --git a/src/fit.c b/src/fit.c
index ea062ba..6a19255 100644
--- a/src/fit.c
+++ b/src/fit.c
@@ -5207,20 +5207,43 @@ double guess_energy(event *ev, double *pos, double *dir)
 
 int fit_event2(event *ev, double *xopt, double *fmin, int *id, size_t n, double maxtime)
 {
+    /* Fit the event `ev` under the hypothesis that it's from `n` particles
+     * with ids `id`. The best fit parameters are stored in `xopt` upon success
+     * and the negative log likelihood value at the minimum is stored in
+     * `fmin`. The order of the parameters in `xopt` is:
+     *
+     *     xopt[0] - x position (cm)
+     *     xopt[1] - y position (cm)
+     *     xopt[2] - z position (cm)
+     *     xopt[3] - t0 (ns)
+     *     xopt[4] - Kinetic energy of particle 1 (MeV)
+     *     xopt[5] - Theta direction of particle 1 (radians)
+     *     xopt[6] - Phi direction of particle 1 (radians)
+     *     xopt[7] - Kinetic energy of particle 2 (MeV)
+     *     xopt[8] - Theta direction of particle 2 (radians)
+     *     xopt[9] - Phi direction of particle 2 (radians)
+     *     ...
+     *
+     * `xopt` should be an array with at least 4+3*n elements.
+     *
+     * `maxtime` specifies the maximum time to perform the fit in seconds. Note
+     * that before doing the full fit we try to calculate a good seed position
+     * by running a "fast" likelihood calculation. This time does not count
+     * towards the maximum so it is possible for the fit to take slighly longer
+     * than maxtime.
+     *
+     * `id` should be an array of the particle ids (see id_particle.h for the
+     * macros defining the particle types).
+     *
+     * On success returns 0, and on error returns NLOPT_FORCED_STOP. This error
+     * is caused when the minimization is forced to halt when for example you
+     * press ctrl-c. */
     size_t i, j;
     fitParams fpars;
     double x[100], ss[100], lb[100], ub[100], fval, n_d2o, x0[100], T0, Tmin, mass, pos[3], t0, dir[3];
     struct timeval tv_start, tv_stop;
     double time_elapsed;
 
-    // x
-    // y
-    // z
-    // t0
-    // E
-    // theta
-    // phi
-
     opt = nlopt_create(NLOPT_LN_BOBYQA, 4+3*n);
     nlopt_set_min_objective(opt,nlopt_nll2,&fpars);