Added wrap-doc methods #8 (#5459)

* Added wrap-doc methods #8

src/openms/include/OpenMS/MATH/MISC/LinearInterpolation.h

@@ -184,7 +184,7 @@ namespace OpenMS
         }
       }
 
-      /**@brief Performs linear resampling.  The arg_value is split up and
+      /** @brief Performs linear resampling.  The arg_value is split up and
       added to the data points around arg_pos.
       */
       void addValue(KeyType arg_pos, ValueType arg_value)
@@ -237,7 +237,7 @@ namespace OpenMS
         }
       }
 
-      /**@brief Returns the interpolated derivative.
+      /** @brief Returns the interpolated derivative.
 
       Please drop me (= the maintainer) a message if you are using this.
       */
@@ -321,7 +321,7 @@ namespace OpenMS
         return data_;
       }
 
-      /**@brief Assigns data to the internal random access container from
+      /** @brief Assigns data to the internal random access container from
       which interpolated values are being sampled.
 
       SourceContainer must be assignable to ContainerType.
@@ -374,7 +374,7 @@ namespace OpenMS
         return scale_;
       }
 
-      /**@brief Accessor.  "Scale" is the difference (in "outside" units) between consecutive entries in "Data".
+      /** @brief Accessor.  "Scale" is the difference (in "outside" units) between consecutive entries in "Data".
 
       <b>Note:</b> Using this invalidates the inside and outside reference
       points.
@@ -401,8 +401,8 @@ namespace OpenMS
         offset_ = offset;
       }
 
-      /**@brief Specifies the mapping from "outside" to "inside" coordinates by the following data:
-      - <code>scale</code>: the difference in outside coordinates between consecutive values in the data vector.
+      /** @brief Specifies the mapping from "outside" to "inside" coordinates by the following data:
+       - <code>scale</code>: the difference in outside coordinates between consecutive values in the data vector.
       - <code>inside</code> and <code>outside</code>: these x-axis positions are mapped onto each other.
 
       For example, when you have a complicated probability distribution
@@ -422,7 +422,7 @@ namespace OpenMS
         offset_  = outside - scale * inside;
       }
 
-      /**@brief Specifies the mapping from "outside" to "inside" coordinates by the following data:
+      /** @brief Specifies the mapping from "outside" to "inside" coordinates by the following data:
       - <code>inside_low</code> and <code>outside_low</code>: these axis positions are mapped onto each other.
       - <code>inside_high</code> and <code>outside_high</code>: these axis positions are mapped onto each other.
 

src/openms/include/OpenMS/TRANSFORMATIONS/FEATUREFINDER/IsotopeWavelet.h

@@ -65,41 +65,44 @@ namespace OpenMS
 
 
     /** @brief Returns the value of the isotope wavelet at position @p t. Usually, you do not need to call this function.
-        * Please use @see sampleTheWavelet instead.
-        *
-        * Note that this functions returns the pure function value of psi and not the normalized (average=0)
-        * value given by Psi.
-        * @param t The position at which the wavelet has to be drawn (within the coordinate system of the wavelet).
-        * @param m The m/z position within the signal (i.e. the mass not de-charged) within the signal.
-        * @param z The charge @p z we want to detect.
-        * @param mode Indicates whether positive mode (+1) or negative mode (-1) has been used for ionization. */
+         Please use @see sampleTheWavelet instead.
+        
+         Note that this functions returns the pure function value of psi and not the normalized (average=0)
+         value given by Psi.
+         @param t The position at which the wavelet has to be drawn (within the coordinate system of the wavelet).
+         @param m The m/z position within the signal (i.e. the mass not de-charged) within the signal.
+         @param z The charge @p z we want to detect.
+         @param mode Indicates whether positive mode (+1) or negative mode (-1) has been used for ionization. 
+    */
     static double getValueByMass(const double t, const double m, const UInt z, const Int mode = +1)
     {
       return getValueByLambda(getLambdaL(m * z - z * mode * Constants::IW_PROTON_MASS), t * z + 1);
     }
 
     /** @brief Returns the value of the isotope wavelet at position @p t via a fast table lookup.
-    *	Usually, you do not need to call this function.
-        * Please use @see sampleTheWavelet instead.
-        *
-        * Note that this functions returns the pure function value of psi and not the normalized (average=0)
-        * value given by Psi.
-        * @param lambda The mass-parameter lambda.
-        * @param tz1 t (the position) times the charge (z) plus 1. */
+    	   Usually, you do not need to call this function.
+         Please use @see sampleTheWavelet instead.
+        
+         Note that this functions returns the pure function value of psi and not the normalized (average=0)
+         value given by Psi.
+         @param lambda The mass-parameter lambda.
+         @param tz1 t (the position) times the charge (z) plus 1. 
+      */
     static double getValueByLambda(const double lambda, const double tz1);
 
     /** @brief Returns the value of the isotope wavelet at position @p t.
-        * This function is usually significantly slower than the table lookup performed in @see getValueByLambda.
-        * Nevertheless, it might be necessary to call this function due to extrapolating reasons caused by the
-        * alignment of the wavelet.
-        *
-        * Usually, you do not need to call this function.
-        * Please use @see sampleTheWavelet instead.
-        *
-        * Note that this functions returns the pure function value of psi and not the normalized (average=0)
-        * value given by Psi.
-        * @param lambda The mass-parameter lambda.
-        * @param tz1 t (the position) times the charge (z) plus 1. */
+         This function is usually significantly slower than the table lookup performed in @see getValueByLambda.
+         Nevertheless, it might be necessary to call this function due to extrapolating reasons caused by the
+         alignment of the wavelet.
+        
+         Usually, you do not need to call this function.
+         Please use @see sampleTheWavelet instead.
+        
+         Note that this functions returns the pure function value of psi and not the normalized (average=0)
+         value given by Psi.
+         @param lambda The mass-parameter lambda.
+         @param tz1 t (the position) times the charge (z) plus 1. 
+      */
     static double getValueByLambdaExtrapol(const double lambda, const double tz1);
 
     static double getValueByLambdaExact(const double lambda, const double tz1);
@@ -118,18 +121,20 @@ namespace OpenMS
     }
 
     /** @brief Returns the table_steps_ parameter.
-        *
-        * This is an internally used parameter controlling the precision of several pre-sampling steps.
-        * Normally, this parameter can be left unchanged. */
+        
+         This is an internally used parameter controlling the precision of several pre-sampling steps.
+         Normally, this parameter can be left unchanged. 
+        */
     static double getTableSteps()
     {
       return table_steps_;
     }
 
     /** @brief Returns the inv_table_steps_ parameter.
-        *
-        * This is an internally used parameter controlling the precision of several pre-sampling steps.
-        * Normally, this parameter can be left unchanged. */
+        
+         This is an internally used parameter controlling the precision of several pre-sampling steps.
+         Normally, this parameter can be left unchanged. 
+        */
     static double getInvTableSteps()
     {
       return inv_table_steps_;
@@ -147,9 +152,10 @@ namespace OpenMS
 
 
     /** @brief Computes the averagine isotopic distribution we would expect at the de-convoluted mass.
-        * @param m The de-convoluted mass m.
-        * @param size Returns the number of significant peaks within a pattern occurring at mass @p m.
-        * @return The isotopic distribution. */
+         @param m The de-convoluted mass m.
+         @param size Returns the number of significant peaks within a pattern occurring at mass @p m.
+         @return The isotopic distribution. 
+         */
     static const IsotopeDistribution::ContainerType & getAveragine(const double m, UInt * size = nullptr);
 
 
@@ -195,13 +201,14 @@ namespace OpenMS
 
 
     /** @brief Should be called once before values are drawn from the isotope wavelet function.
-        * The function is automatically called by the public constructor.
-        *
-        * The function pre-computes the expensive gamma function. Parameters related to this function are:
-        * @see max_charge_ and @see peak_cutoff_. If both of these are set correctly @see getValue will never compute
-        * the gamma function online.
-        *
-        * @param max_m The maximal de-convoluted mass that occurs in the current data set. */
+         The function is automatically called by the public constructor.
+        
+         The function pre-computes the expensive gamma function. Parameters related to this function are:
+         @see max_charge_ and @see peak_cutoff_. If both of these are set correctly @see getValue will never compute
+         the gamma function online.
+        
+         @param max_m The maximal de-convoluted mass that occurs in the current data set. 
+         */
     static void preComputeExpensiveFunctions_(const double max_m);
 
 

src/openms/include/OpenMS/TRANSFORMATIONS/FEATUREFINDER/IsotopeWaveletTransform.h

@@ -288,7 +288,7 @@ namespace OpenMS
 
     /** @brief Computes a linear (intensity) interpolation.
         * @param mz_a The m/z value of the point left to the query.
-        * @param mz_a The intensity value of the point left to the query.
+        * @param intens_a The intensity value of the point left to the query.
         * @param mz_pos The query point.
         * @param mz_b The m/z value of the point right to the query.
         * @param intens_b The intensity value of the point left to the query. */

src/pyOpenMS/pxds/ISpectrumAccess.pxd

@@ -18,12 +18,12 @@ cdef extern from "<OpenMS/OPENSWATHALGO/DATAACCESS/ISpectrumAccess.h>" namespace
 
       # virtual boost::shared_ptr<ISpectrumAccess> lightClone() const = 0;
 
-      shared_ptr[OSSpectrum] getSpectrumById(int id_) nogil except +
-      libcpp_vector[size_t] getSpectraByRT(double RT, double deltaRT) nogil except +
-      size_t getNrSpectra() nogil except +
+      shared_ptr[OSSpectrum] getSpectrumById(int id_) nogil except + # wrap-doc:Return a pointer to a spectrum at the given string id
+      libcpp_vector[size_t] getSpectraByRT(double RT, double deltaRT) nogil except + # wrap-doc:Return a vector of ids of spectra that are within RT +/- deltaRT
+      size_t getNrSpectra() nogil except + # wrap-doc:Returns the number of spectra available
       # virtual SpectrumMeta getSpectrumMetaById(int id) const = 0;
 
-      shared_ptr[OSChromatogram] getChromatogramById(int id_) nogil except +
-      size_t getNrChromatograms() nogil except +
+      shared_ptr[OSChromatogram] getChromatogramById(int id_) nogil except + # wrap-doc:Return a pointer to a chromatogram at the given id
+      size_t getNrChromatograms() nogil except + # wrap-doc:Returns the number of chromatograms available
       libcpp_utf8_output_string getChromatogramNativeID(int id_) nogil except +
 

src/pyOpenMS/pxds/IsotopeMarker.pxd

@@ -10,8 +10,9 @@ cdef extern from "<OpenMS/FILTERING/TRANSFORMERS/IsotopeMarker.h>" namespace "Op
     cdef cppclass IsotopeMarker(PeakMarker) :
         # wrap-inherits:
         #  PeakMarker
-        IsotopeMarker() nogil except +
+        IsotopeMarker() nogil except + # wrap-doc:IsotopeMarker marks peak pairs which could represent an ion and its isotope
         IsotopeMarker(IsotopeMarker &) nogil except +
+
         void apply(libcpp_map[ double, bool ] & , MSSpectrum & ) nogil except +
         PeakMarker * create() nogil except + # wrap-ignore
         # TODO

src/pyOpenMS/pxds/IsotopeModel.pxd

@@ -5,17 +5,46 @@ from EmpiricalFormula cimport *
 cdef extern from "<OpenMS/TRANSFORMATIONS/FEATUREFINDER/IsotopeModel.h>" namespace "OpenMS":
 
     cdef cppclass IsotopeModel "OpenMS::IsotopeModel":
+        # wrap-doc:
+                #   Isotope distribution approximated using linear interpolation
+                #   -----
+                #   This models a smoothed (widened) distribution, i.e. can be used to sample actual raw peaks (depending on the points you query)
+                #   If you only want the distribution (no widening), use either
+                #   EmpiricalFormula::getIsotopeDistribution() // for a certain sum formula
+                #   or
+                #   IsotopeDistribution::estimateFromPeptideWeight (double average_weight)  // for averagine
+                #   -----
+                #   Peak widening is achieved by either a Gaussian or Lorentzian shape
+
         IsotopeModel() nogil except +
         IsotopeModel(IsotopeModel &) nogil except +
         UInt getCharge() nogil except +
         void setOffset(double offset) nogil except +
-        double getOffset() nogil except +
-        EmpiricalFormula getFormula() nogil except +
-        void setSamples(EmpiricalFormula &formula) nogil except +
+            # wrap-doc:
+                #   Set the offset of the model
+                #   -----
+                #   The whole model will be shifted to the new offset without being computing all over
+                #   This leaves a discrepancy which is minor in small shifts (i.e. shifting by one or two
+                #   standard deviations) but can get significant otherwise. In that case use setParameters()
+                #   which enforces a recomputation of the model
+
+        double getOffset() nogil except + # wrap-doc:Get the offset of the model
+        EmpiricalFormula getFormula() nogil except + # wrap-doc:Return the Averagine peptide formula (mass calculated from mean mass and charge -- use .setParameters() to set them)
+        void setSamples(EmpiricalFormula &formula) nogil except + # wrap-doc:Set sample/supporting points of interpolation
         double getCenter() nogil except +
+            # wrap-doc:
+                #   Get the center of the Isotope model
+                #   -----
+                #   This is a m/z-value not necessarily the monoisotopic mass
+
         IsotopeDistribution  getIsotopeDistribution() nogil except +
+            # wrap-doc:
+                #   Get the Isotope distribution (without widening) from the last setSamples() call
+                #   -----
+                #   Useful to determine the number of isotopes that the model contains and their position
+
         # BaseModel[ 1 ] * create() nogil except +
-        String getProductName() nogil except +
+        String getProductName() nogil except + # wrap-doc:Name of the model (needed by Factory)
 
 cdef extern from "<OpenMS/TRANSFORMATIONS/FEATUREFINDER/IsotopeModel.h>" namespace "OpenMS::IsotopeModel":
     cdef enum Averagines "OpenMS::IsotopeModel::Averagines":

src/pyOpenMS/pxds/IsotopeWavelet.pxd

@@ -12,22 +12,58 @@ cdef extern from "<OpenMS/TRANSFORMATIONS/FEATUREFINDER/IsotopeWavelet.h>" names
 
         # IsotopeWavelet * init(double max_m, UInt max_charge) nogil except +
         # IsotopeWavelet * getInstance() nogil except +
-        void destroy() nogil except +
+        void destroy() nogil except + # wrap-doc:Deletes the singleton instance
         double getValueByMass(double t, double m, UInt z, Int mode) nogil except +
+            # wrap-doc:
+                #   Returns the value of the isotope wavelet at position `t`. Usually, you do not need to call this function
+                #   -----
+                #   Note that this functions returns the pure function value of psi and not the normalized (average=0)
+                #   value given by Psi
+                #   -----
+                #   :param t: The position at which the wavelet has to be drawn (within the coordinate system of the wavelet)
+                #   :param m: The m/z position within the signal (i.e. the mass not de-charged) within the signal
+                #   :param z: The charge `z` we want to detect
+                #   :param mode: Indicates whether positive mode (+1) or negative mode (-1) has been used for ionization
+
         double getValueByLambda(double lambda_, double tz1) nogil except +
+            # wrap-doc:
+                #   Returns the value of the isotope wavelet at position `t` via a fast table lookup
+                #   -----
+                #   Usually, you do not need to call this function
+                #   Please use `sampleTheWavelet` instead
+                #   Note that this functions returns the pure function value of psi and not the normalized (average=0)
+                #   value given by Psi
+                #   -----
+                #   :param lambda: The mass-parameter lambda
+                #   :param tz1: t (the position) times the charge (z) plus 1
+
         double getValueByLambdaExtrapol(double lambda_, double tz1) nogil except +
-        double getValueByLambdaExact(double lambda_, double tz1) nogil except +
-        UInt getMaxCharge() nogil except +
-        void setMaxCharge(UInt max_charge) nogil except +
-        double getTableSteps() nogil except +
-        double getInvTableSteps() nogil except +
-        void setTableSteps(double table_steps) nogil except +
-        double getLambdaL(double m) nogil except +
-        # IsotopeDistribution::ContainerType  getAveragine(double m, UInt *size) nogil except +
-        Size getGammaTableMaxIndex() nogil except +
-        Size getExpTableMaxIndex() nogil except +
-        float myPow(float a, float b) nogil except +
-        UInt getMzPeakCutOffAtMonoPos(double mass, UInt z) nogil except +
-        UInt getNumPeakCutOff(double mass, UInt z) nogil except +
-        UInt getNumPeakCutOff(double mz) nogil except +
+            # wrap-doc:
+                #   Returns the value of the isotope wavelet at position `t`
+                #   -----
+                #   This function is usually significantly slower than the table lookup performed in @see getValueByLambda
+                #   Nevertheless, it might be necessary to call this function due to extrapolating reasons caused by the
+                #   alignment of the wavelet
+                #   -----
+                #   Usually, you do not need to call this function
+                #   Please use `sampleTheWavelet` instead
+                #   Note that this functions returns the pure function value of psi and not the normalized (average=0)
+                #   value given by Psi
+                #   -----
+                #   :param lambda: The mass-parameter lambda
+                #   :param tz1: t (the position) times the charge (z) plus 1
 
+        double getValueByLambdaExact(double lambda_, double tz1) nogil except +# TODO
+        UInt getMaxCharge() nogil except + # wrap-doc:Returns the largest charge state we will consider
+        void setMaxCharge(UInt max_charge) nogil except + # wrap-doc:Sets the `max_charge` parameter
+        double getTableSteps() nogil except + # wrap-doc:Returns the table_steps_ parameter
+        double getInvTableSteps() nogil except + # wrap-doc:Returns the inv_table_steps_ parameter
+        void setTableSteps(double table_steps) nogil except + # wrap-doc:Sets the `table_steps` parameter
+        double getLambdaL(double m) nogil except + # wrap-doc:Returns the mass-parameter lambda (linear fit)
+        # IsotopeDistribution::ContainerType  getAveragine(double m, UInt *size) nogil except +
+        Size getGammaTableMaxIndex() nogil except + # wrap-doc:Returns the largest possible index for the pre-sampled gamma table
+        Size getExpTableMaxIndex() nogil except + # wrap-doc:Returns the largest possible index for the pre-sampled exp table
+        float myPow(float a, float b) nogil except + # wrap-doc:Internally used function; uses register shifts for fast computation of the power function
+        UInt getMzPeakCutOffAtMonoPos(double mass, UInt z) nogil except +# TODO 
+        UInt getNumPeakCutOff(double mass, UInt z) nogil except +# TODO
+        UInt getNumPeakCutOff(double mz) nogil except +# TODO