From 4e70b8ecc66393cc7892eaa76cf8a162395408d9 Mon Sep 17 00:00:00 2001
From: Stephan Hageboeck <stephan.hageboeck@cern.ch>
Date: Mon, 20 May 2019 11:12:36 +0200
Subject: [PATCH] [RF] Documentation updates.

Collection of small documentation fixes in various RooFit classes.
---
 math/fftw/src/TFFTComplex.cxx                 | 48 +++++++++----------
 roofit/roofitcore/inc/RooAbsArg.h             | 22 ++++-----
 roofit/roofitcore/inc/RooAbsRealLValue.h      | 18 +++++++
 roofit/roofitcore/src/RooAbsMCStudyModule.cxx |  6 +--
 roofit/roofitcore/src/RooAddPdf.cxx           |  2 +-
 roofit/roofitcore/src/RooCurve.cxx            |  2 +-
 roofit/roofitcore/src/RooDataHist.cxx         |  6 +--
 roofit/roofitcore/src/RooDataSet.cxx          |  6 ++-
 roofit/roofitcore/src/RooEffProd.cxx          | 15 +++---
 roofit/roofitcore/src/RooFormulaVar.cxx       | 41 ++++++++--------
 roofit/roofitcore/src/RooFunctor.cxx          |  2 +-
 roofit/roofitcore/src/RooInvTransform.cxx     |  2 +-
 roofit/roofitcore/src/RooMCStudy.cxx          | 12 ++---
 roofit/roofitcore/src/RooProdPdf.cxx          |  2 +-
 roofit/roofitcore/src/RooProduct.cxx          |  4 +-
 roofit/roofitcore/src/RooRealSumPdf.cxx       |  8 ++--
 roofit/roostats/src/AsymptoticCalculator.cxx  | 39 ++++++++-------
 tutorials/roofit/rf604_constraints.C          |  4 +-
 18 files changed, 133 insertions(+), 106 deletions(-)

diff --git a/math/fftw/src/TFFTComplex.cxx b/math/fftw/src/TFFTComplex.cxx
index 5dbe161bf46..aae654a6a3e 100644
--- a/math/fftw/src/TFFTComplex.cxx
+++ b/math/fftw/src/TFFTComplex.cxx
@@ -10,30 +10,30 @@
  *************************************************************************/
 
 //////////////////////////////////////////////////////////////////////////
-//
-// TFFTComplex
-// One of the interface classes to the FFTW package, can be used directly
-// or via the TVirtualFFT class. Only the basic interface of FFTW is implemented.
-// Computes complex input/output discrete Fourier transforms (DFT)
-// in one or more dimensions. For the detailed information on the computed
-// transforms please refer to the FFTW manual, chapter "What FFTW really computes".
-//
-// How to use it:
-// 1) Create an instance of TFFTComplex - this will allocate input and output
-//    arrays (unless an in-place transform is specified)
-// 2) Run the Init() function with the desired flags and settings
-// 3) Set the data (via SetPoints(), SetPoint() or SetPointComplex() functions)
-// 4) Run the Transform() function
-// 5) Get the output (via GetPoints(), GetPoint() or GetPointComplex() functions)
-// 6) Repeat steps 3)-5) as needed
-//
-// For a transform of the same size, but with different flags or sign, rerun the Init()
-// function and continue with steps 3)-5)
-// NOTE: 1) running Init() function will overwrite the input array! Don't set any data
-//          before running the Init() function
-//       2) FFTW computes unnormalized transform, so doing a transform followed by
-//          its inverse will lead to the original array scaled by the transform size
-//
+/// \class TFFTComplex
+///
+/// One of the interface classes to the FFTW package, can be used directly
+/// or via the TVirtualFFT class. Only the basic interface of FFTW is implemented.
+/// Computes complex input/output discrete Fourier transforms (DFT)
+/// in one or more dimensions. For the detailed information on the computed
+/// transforms please refer to the FFTW manual, chapter "What FFTW really computes".
+///
+/// How to use it:
+/// 1) Create an instance of TFFTComplex - this will allocate input and output
+///    arrays (unless an in-place transform is specified)
+/// 2) Run the Init() function with the desired flags and settings
+/// 3) Set the data (via SetPoints(), SetPoint() or SetPointComplex() functions)
+/// 4) Run the Transform() function
+/// 5) Get the output (via GetPoints(), GetPoint() or GetPointComplex() functions)
+/// 6) Repeat steps 3)-5) as needed
+///
+/// For a transform of the same size, but with different flags or sign, rerun the Init()
+/// function and continue with steps 3)-5)
+/// NOTE: 1) running Init() function will overwrite the input array! Don't set any data
+///          before running the Init() function
+///       2) FFTW computes unnormalized transform, so doing a transform followed by
+///          its inverse will lead to the original array scaled by the transform size
+///
 //////////////////////////////////////////////////////////////////////////
 
 #include "TFFTComplex.h"
diff --git a/roofit/roofitcore/inc/RooAbsArg.h b/roofit/roofitcore/inc/RooAbsArg.h
index e7f2db3cc74..858129546e4 100644
--- a/roofit/roofitcore/inc/RooAbsArg.h
+++ b/roofit/roofitcore/inc/RooAbsArg.h
@@ -204,15 +204,15 @@ public:
     return kFALSE;
   }
 
-  // Create a fundamental-type object that stores our type of value. The
-  // created object will have a valid value, but not necessarily the same
-  // as our value. The caller is responsible for deleting the returned object.
+  /// Create a fundamental-type object that stores our type of value. The
+  /// created object will have a valid value, but not necessarily the same
+  /// as our value. The caller is responsible for deleting the returned object.
   virtual RooAbsArg *createFundamental(const char* newname=0) const = 0;
 
+  /// Is this argument an l-value, i.e., can it appear on the left-hand side
+  /// of an assignment expression? LValues are also special since they can
+  /// potentially be analytically integrated and generated.
   inline virtual Bool_t isLValue() const {
-    // Is this argument an l-value, ie, can it appear on the left-hand side
-    // of an assignment expression? LValues are also special since they can
-    // potentially be analytically integrated and generated.
     return kFALSE;
   }
 
@@ -224,13 +224,13 @@ public:
   friend class RooAddPdfOrig ;
   RooArgSet* getVariables(Bool_t stripDisconnected=kTRUE) const ;
   RooArgSet* getParameters(const RooAbsData* data, Bool_t stripDisconnected=kTRUE) const ;
+  /// Return the parameters of this p.d.f when used in conjuction with dataset 'data'
   RooArgSet* getParameters(const RooAbsData& data, Bool_t stripDisconnected=kTRUE) const {
-    // Return the parameters of this p.d.f when used in conjuction with dataset 'data'
     return getParameters(&data,stripDisconnected) ;
   }
-  RooArgSet* getParameters(const RooArgSet& set, Bool_t stripDisconnected=kTRUE) const {
-    // Return the parameters of the p.d.f given the provided set of observables
-    return getParameters(&set,stripDisconnected) ;
+  /// Return the parameters of the p.d.f given the provided set of observables
+  RooArgSet* getParameters(const RooArgSet& observables, Bool_t stripDisconnected=kTRUE) const {
+    return getParameters(&observables,stripDisconnected);
   }
   virtual RooArgSet* getParameters(const RooArgSet* depList, Bool_t stripDisconnected=kTRUE) const ;
   /// Return the observables of this pdf given a set of observables
@@ -238,7 +238,7 @@ public:
     return getObservables(&set,valueOnly) ;
   }
   RooArgSet* getObservables(const RooAbsData* data) const ;
-  // Return the observables of this pdf given the observables defined by `data`.
+  /// Return the observables of this pdf given the observables defined by `data`.
   RooArgSet* getObservables(const RooAbsData& data) const {
     return getObservables(&data) ;
   }
diff --git a/roofit/roofitcore/inc/RooAbsRealLValue.h b/roofit/roofitcore/inc/RooAbsRealLValue.h
index be5fe92ebde..76ff07c403e 100644
--- a/roofit/roofitcore/inc/RooAbsRealLValue.h
+++ b/roofit/roofitcore/inc/RooAbsRealLValue.h
@@ -64,15 +64,33 @@ public:
 
   // Get fit range limits
 
+  /// Retrive binning configuration with given name or default binning.
   virtual const RooAbsBinning& getBinning(const char* name=0, Bool_t verbose=kTRUE, Bool_t createOnTheFly=kFALSE) const = 0 ;
+  /// Retrive binning configuration with given name or default binning.
   virtual RooAbsBinning& getBinning(const char* name=0, Bool_t verbose=kTRUE, Bool_t createOnTheFly=kFALSE) = 0 ;
+  /// Check if binning with given name has been defined.
   virtual Bool_t hasBinning(const char* name) const = 0 ;
   virtual Bool_t inRange(const char* name) const ;
+  /// Get number of bins of currently defined range.
+  /// \param name Optionally, request number of bins for range with given name.
   virtual Int_t getBins(const char* name=0) const { return getBinning(name).numBins(); }
+  /// Get miniminum of currently defined range.
+  /// \param name Optionally, request minimum of range with given name.
   virtual Double_t getMin(const char* name=0) const { return getBinning(name).lowBound(); }
+  /// Get maximum of currently defined range.
+  /// \param name Optionally, request maximum of range with given name.
   virtual Double_t getMax(const char* name=0) const { return getBinning(name).highBound(); }
+  /// Get low and high bound of the variable.
+  /// \param name Optional range name. If not given, the default range will be used.
+  /// \return A pair with [lowerBound, upperBound]
+  std::pair<double, double> getRange(const char* name = 0) const {
+    return {getMin(name), getMax(name)};
+  }
+  /// Check if variable has a lower bound.
   inline Bool_t hasMin(const char* name=0) const { return !RooNumber::isInfinite(getMin(name)); }
+  /// Check if variable has an upper bound.
   inline Bool_t hasMax(const char* name=0) const { return !RooNumber::isInfinite(getMax(name)); }
+  /// Check if variable has a binning with given name.
   virtual Bool_t hasRange(const char* name) const { return hasBinning(name) ; }
 
   // Jacobian term management
diff --git a/roofit/roofitcore/src/RooAbsMCStudyModule.cxx b/roofit/roofitcore/src/RooAbsMCStudyModule.cxx
index 154f4a3e137..f6972771298 100644
--- a/roofit/roofitcore/src/RooAbsMCStudyModule.cxx
+++ b/roofit/roofitcore/src/RooAbsMCStudyModule.cxx
@@ -21,14 +21,14 @@
 
 RooAbsMCStudyModule is a base class for add-on modules to RooMCStudy that
 can perform additional calculations on each generate+fit cycle managed
-by RooMCStudy
+by RooMCStudy.
 
 This class can insert code to be executed before each generation step,
 between the generation and fitting step and after the fitting step.
 Any summary output variables declared in the RooDataSet exported through
-summaryData() is merged with the 'master' summary dataset in RooMCStudy
+summaryData() is merged with the 'master' summary dataset in RooMCStudy.
 
-Look at RooDLLSignificanceMCStudyModule for an example of an implementation
+Look at RooDLLSignificanceMCStudyModule for an example of an implementation.
 **/
 
 #include "RooFit.h"
diff --git a/roofit/roofitcore/src/RooAddPdf.cxx b/roofit/roofitcore/src/RooAddPdf.cxx
index 0d269624004..26c611a4f4a 100644
--- a/roofit/roofitcore/src/RooAddPdf.cxx
+++ b/roofit/roofitcore/src/RooAddPdf.cxx
@@ -363,7 +363,7 @@ RooAddPdf::~RooAddPdf()
 /// interpretation of the coefficients to be done in the given set of
 /// observables. If frozen, fractions are automatically transformed
 /// from the reference normalization set to the contextual normalization
-/// set by ratios of integrals
+/// set by ratios of integrals.
 
 void RooAddPdf::fixCoefNormalization(const RooArgSet& refCoefNorm) 
 {
diff --git a/roofit/roofitcore/src/RooCurve.cxx b/roofit/roofitcore/src/RooCurve.cxx
index 85a2cb6f2e5..dfc336b297b 100644
--- a/roofit/roofitcore/src/RooCurve.cxx
+++ b/roofit/roofitcore/src/RooCurve.cxx
@@ -32,7 +32,7 @@ p->setDrawOptions("curve_y","PL");
 p->Draw();
 ```
 
-To retrieve a RooCurve form a RooPlot, use RooPlot::getCurve().
+To retrieve a RooCurve from a RooPlot, use RooPlot::getCurve().
 **/
 
 #include "RooFit.h"
diff --git a/roofit/roofitcore/src/RooDataHist.cxx b/roofit/roofitcore/src/RooDataHist.cxx
index 6272085c6d9..c83e6c48387 100644
--- a/roofit/roofitcore/src/RooDataHist.cxx
+++ b/roofit/roofitcore/src/RooDataHist.cxx
@@ -19,9 +19,9 @@
 \class RooDataHist
 \ingroup Roofitcore
 
-RooDataSet is a container class to hold N-dimensional binned data. Each bins central 
-coordinates in N-dimensional space are represented by a RooArgSet of RooRealVar, RooCategory 
-or RooStringVar objects, thus data can be binned in real and/or discrete dimensions
+The RooDataHist is a container class to hold N-dimensional binned data. Each bin's central
+coordinates in N-dimensional space are represented by a RooArgSet containing RooRealVar, RooCategory
+or RooStringVar objects, thus data can be binned in real and/or discrete dimensions.
 **/
 
 #include "RooFit.h"
diff --git a/roofit/roofitcore/src/RooDataSet.cxx b/roofit/roofitcore/src/RooDataSet.cxx
index b2c71993951..917a8326f0e 100644
--- a/roofit/roofitcore/src/RooDataSet.cxx
+++ b/roofit/roofitcore/src/RooDataSet.cxx
@@ -604,7 +604,9 @@ RooDataSet::RooDataSet(const char *name, const char *title, const RooArgSet& var
 /// any variable in the source dataset. For cuts involving variables
 /// other than those contained in the source data set, such as
 /// intermediate formula objects, use the equivalent constructor
-/// accepting RooFormulaVar reference as cut specification
+/// accepting RooFormulaVar reference as cut specification.
+///
+/// This constructor will internally store the data in a TTree.
 ///
 /// For most uses the RooAbsData::reduce() wrapper function, which
 /// uses this constructor, is the most convenient way to create a
@@ -646,6 +648,8 @@ RooDataSet::RooDataSet(const char *name, const char *title, RooDataSet *dset,
 /// equivalent constructor with a string based cut expression is
 /// recommended.
 ///
+/// This constructor will internally store the data in a TTree.
+///
 /// For most uses the RooAbsData::reduce() wrapper function, which
 /// uses this constructor, is the most convenient way to create a
 /// subset of an existing data
diff --git a/roofit/roofitcore/src/RooEffProd.cxx b/roofit/roofitcore/src/RooEffProd.cxx
index 9f66d880f46..0fe50ea3222 100644
--- a/roofit/roofitcore/src/RooEffProd.cxx
+++ b/roofit/roofitcore/src/RooEffProd.cxx
@@ -13,14 +13,13 @@
 
 
 /////////////////////////////////////////////////////////////////////////////////////
-// BEGIN_HTML
-// The class RooEffProd implements the product of a PDF with an efficiency function.
-// The normalization integral of the product is calculated numerically, but the
-// event generation is handled by a specialized generator context that implements
-// the event generation in a more efficient for cases where the PDF has an internal
-// generator that is smarter than accept reject. 
-// END_HTML
-//
+/// \class RooEffProd
+/// The class RooEffProd implements the product of a PDF with an efficiency function.
+/// The normalization integral of the product is calculated numerically, but the
+/// event generation is handled by a specialized generator context that implements
+/// the event generation in a more efficient for cases where the PDF has an internal
+/// generator that is smarter than accept reject.
+///
 
 #include "RooFit.h"
 #include "RooEffProd.h"
diff --git a/roofit/roofitcore/src/RooFormulaVar.cxx b/roofit/roofitcore/src/RooFormulaVar.cxx
index 8fdff25bf69..36beb5daf02 100644
--- a/roofit/roofitcore/src/RooFormulaVar.cxx
+++ b/roofit/roofitcore/src/RooFormulaVar.cxx
@@ -15,26 +15,27 @@
  *****************************************************************************/
 
 //////////////////////////////////////////////////////////////////////////////
-//
-// RooFormulaVar is a generic implementation of a real valued object
-// which takes a RooArgList of servers and a C++ expression string defining how
-// its value should be calculated from the given list of servers.
-// RooFormulaVar uses a RooFormula object to perform the expression evaluation.
-//
-// If RooAbsPdf objects are supplied to RooFormulaVar as servers, their
-// raw (unnormalized) values will be evaluated. Use RooGenericPdf, which
-// constructs generic PDF functions, to access their properly normalized
-// values.
-//
-// The string expression can be any valid TFormula expression referring to the
-// listed servers either by name or by their ordinal list position:
-//
-//   RooFormulaVar("gen","x*y",RooArgList(x,y))  or
-//   RooFormulaVar("gen","@0*@1",RooArgList(x,y)) 
-//
-// The latter form, while slightly less readable, is more versatile because it
-// doesn't hardcode any of the variable names it expects
-//
+/// \class RooFormulaVar
+///
+/// A RooFormulaVar is a generic implementation of a real-valued object,
+/// which takes a RooArgList of servers and a C++ expression string defining how
+/// its value should be calculated from the given list of servers.
+/// RooFormulaVar uses a RooFormula object to perform the expression evaluation.
+///
+/// If RooAbsPdf objects are supplied to RooFormulaVar as servers, their
+/// raw (unnormalized) values will be evaluated. Use RooGenericPdf, which
+/// constructs generic PDF functions, to access their properly normalized
+/// values.
+///
+/// The string expression can be any valid TFormula expression referring to the
+/// listed servers either by name or by their ordinal list position:
+/// ```
+///   RooFormulaVar("gen","x*y",RooArgList(x,y))  or
+///   RooFormulaVar("gen","@0*@1",RooArgList(x,y))
+/// ```
+/// The latter form, while slightly less readable, is more versatile because it
+/// doesn't hardcode any of the variable names it expects
+///
 
 
 #include "RooFit.h"
diff --git a/roofit/roofitcore/src/RooFunctor.cxx b/roofit/roofitcore/src/RooFunctor.cxx
index 885f668b6e5..d31bd1eb6e6 100644
--- a/roofit/roofitcore/src/RooFunctor.cxx
+++ b/roofit/roofitcore/src/RooFunctor.cxx
@@ -20,7 +20,7 @@
 \class RooFunctor
 \ingroup Roofitcore
 
-Lightweight interface adaptor that exports a RooAbsPdf as a functor
+Lightweight interface adaptor that exports a RooAbsPdf as a functor.
 **/
 
 
diff --git a/roofit/roofitcore/src/RooInvTransform.cxx b/roofit/roofitcore/src/RooInvTransform.cxx
index 279bc98d843..eac2d6dc110 100644
--- a/roofit/roofitcore/src/RooInvTransform.cxx
+++ b/roofit/roofitcore/src/RooInvTransform.cxx
@@ -19,7 +19,7 @@
 \class RooInvTransform
 \ingroup Roofitcore
 
-Lightweight function binding that returns the inverse of an input function binding
+Lightweight function binding that returns the inverse of an input function binding.
 Apply the change of variables transformation x -> 1/x to the input
 function and its range. The function must be one dimensional and its
 range cannot include zero.
diff --git a/roofit/roofitcore/src/RooMCStudy.cxx b/roofit/roofitcore/src/RooMCStudy.cxx
index f624e32654f..ce3c45a5f64 100644
--- a/roofit/roofitcore/src/RooMCStudy.cxx
+++ b/roofit/roofitcore/src/RooMCStudy.cxx
@@ -19,9 +19,9 @@
 \class RooMCStudy
 \ingroup Roofitcore
 
-RooMCStudy is a help class to facilitate Monte Carlo studies
+RooMCStudy is a helper class to facilitate Monte Carlo studies
 such as 'goodness-of-fit' studies, that involve fitting a PDF 
-to multiple toy Monte Carlo sets generated from the same PDF 
+to multiple toy Monte Carlo sets generated from either same PDF
 or another PDF.
 
 Given a fit PDF and a generator PDF, RooMCStudy can produce
@@ -31,10 +31,10 @@ Additional plotting routines simplify the task of plotting
 the distribution of the minimized likelihood, the fitted parameter values,
 fitted error and pull distribution.
 RooMCStudy provides the option to insert add-in modules
-that modify the generate and fit cycle and allow to perform
+that modify the generate-and-fit cycle and allow to perform
 extra steps in the cycle. Output of these modules can be stored
 alongside the fit results in the aggregate results dataset.
-These study modules should derive from class RooAbsMCStudyModel
+These study modules should derive from the class RooAbsMCStudyModule.
 
 **/
 
@@ -72,10 +72,10 @@ ClassImp(RooMCStudy);
 
 /**
 Construct Monte Carlo Study Manager. This class automates generating data from a given PDF,
-fitting the PDF to that data and accumulating the fit statistics.
+fitting the PDF to data and accumulating the fit statistics.
 
 \param[in] model The PDF to be studied
-\param[in] observables The variables of the PDF to be considered the observables
+\param[in] observables The variables of the PDF to be considered observables
 \param[in] argX Arguments from the table below
 
 <table>
diff --git a/roofit/roofitcore/src/RooProdPdf.cxx b/roofit/roofitcore/src/RooProdPdf.cxx
index e2edb907515..578f61e0c21 100644
--- a/roofit/roofitcore/src/RooProdPdf.cxx
+++ b/roofit/roofitcore/src/RooProdPdf.cxx
@@ -2020,7 +2020,7 @@ RooArgSet* RooProdPdf::findPdfNSet(RooAbsPdf& pdf) const
 
 
 ////////////////////////////////////////////////////////////////////////////////
-/// Return all parameter constraint p.d.f.s on parameters listed in constrainedParams
+/// Return all parameter constraint p.d.f.s on parameters listed in constrainedParams.
 /// The observables set is required to distinguish unambiguously p.d.f in terms
 /// of observables and parameters, which are not constraints, and p.d.fs in terms
 /// of parameters only, which can serve as constraints p.d.f.s
diff --git a/roofit/roofitcore/src/RooProduct.cxx b/roofit/roofitcore/src/RooProduct.cxx
index 437e9d8972b..d82f6445164 100644
--- a/roofit/roofitcore/src/RooProduct.cxx
+++ b/roofit/roofitcore/src/RooProduct.cxx
@@ -19,9 +19,7 @@
 \class RooProduct
 \ingroup Roofitcore
 
-
-RooProduct a RooAbsReal implementation that represent the product
-of a given set of other RooAbsReal objects
+A RooProduct represents the product of a given set of RooAbsReal objects.
 
 **/
 
diff --git a/roofit/roofitcore/src/RooRealSumPdf.cxx b/roofit/roofitcore/src/RooRealSumPdf.cxx
index dd8c7e81821..3c6f7fb9c7d 100644
--- a/roofit/roofitcore/src/RooRealSumPdf.cxx
+++ b/roofit/roofitcore/src/RooRealSumPdf.cxx
@@ -19,7 +19,7 @@
     \ingroup Roofitcore
 
 
-Class RooRealSumPdf implements a PDF constructed from a sum of functions:
+The class RooRealSumPdf implements a PDF constructed from a sum of functions:
 \f[
   \mathrm{PDF}(x) = \frac{ \sum_{i=1}^{n-1} \mathrm{coef}_i * \mathrm{func}_i(x) + \left[ 1 - \sum_{i=1}^{n-1} \mathrm{coef}_i \right] * \mathrm{func}_n(x) }
             {\sum_{i=1}^{n-1} \mathrm{coef}_i * \int \mathrm{func}_i(x)dx  + \left[ 1 - \sum_{i=1}^{n-1} \mathrm{coef}_i \right] * \int \mathrm{func}_n(x) dx }
@@ -31,8 +31,10 @@ In the present version \f$\mathrm{coef}_i\f$ may not depend on \f$ x \f$, but th
 If the number of coefficients is one less than the number of functions, the PDF is assumed to be normalised. Due to this additional constraint,
 \f$\mathrm{coef}_n\f$ is computed from the other coefficients.
 
-If an \f$ n^\mathrm{th} \f$ coefficient is provided, the PDF will behave as an extended PDF, *i.e.* the total number of events will be measured in addition
-to the fractions of the various functions.
+### Extending the PDF
+If an \f$ n^\mathrm{th} \f$ coefficient is provided, the PDF **can** be used as an extended PDF, *i.e.* the total number of events will be measured in addition
+to the fractions of the various functions. This requires setting the last argument of the constructor
+
 
 */
 
diff --git a/roofit/roostats/src/AsymptoticCalculator.cxx b/roofit/roostats/src/AsymptoticCalculator.cxx
index 5d7c827e212..07bff55d3ca 100644
--- a/roofit/roostats/src/AsymptoticCalculator.cxx
+++ b/roofit/roostats/src/AsymptoticCalculator.cxx
@@ -14,24 +14,28 @@
 Hypothesis Test Calculator based on the asymptotic formulae for the profile
 likelihood ratio.
 
- Performs hypothesis tests using asymptotic formula for the profile likelihood and
-Asimov data set
+It performs hypothesis tests using the asymptotic formula for the profile likelihood and
+the "Asimov" data set.
 
 See G. Cowan, K. Cranmer, E. Gross and O. Vitells: Asymptotic formulae for
 likelihood- based tests of new physics. Eur. Phys. J., C71:1–19, 2011.
-It provides method to perform an hypothesis tests using the likelihood function
-and computes the p values for the null and the alternate using the asymptotic
+It provides methods to perform a hypothesis test using the likelihood function,
+and computes the \f$ p \f$-values for the null and the alternate hypothesis using the asymptotic
 formulae for the profile likelihood ratio described in the given paper.
 
-The calculator provides methods to produce the Asimov dataset, i.e a dataset
+The calculator provides methods to produce the Asimov dataset, i.e, a dataset
 generated where the observed values are equal to the expected ones.
-The Asimov data set is then used to compute the observed asymptotic p-value for
-the alternate hypothesis and the asymptotic expected p-values.
+The Asimov data set is then used to compute the observed asymptotic \f$ p \f$-value for
+the alternate hypothesis and the asymptotic expected \f$ p \f$-value.
 
 The asymptotic formulae are valid only for one POI (parameter of interest). So
-the calculator works only for one-dimensional (one POI) model.
-If more than one POI exists consider as POI only the first one is used.
+the calculator works only for one-dimensional (one POI) models.
 
+If more than one POI exists, only the first one is used for calculations.
+
+The calculator can generate Asimov datasets from two kinds of PDFs:
+- "Counting" distributions: RooPoisson, RooGaussian, or products of RooPoissons.
+- Extended, *i.e.* number of events can be read off from extended likelihood term.
 */
 
 
@@ -912,7 +916,8 @@ void AsymptoticCalculator::FillBins(const RooAbsPdf & pdf, const RooArgList &obs
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// iterate a Prod pdf to find all the Poisson or Gaussian part to set the observed value to expected one
+/// Inpspect a product pdf to find all the Poisson or Gaussian parts to set the observed
+/// values to expected ones.
 
 bool AsymptoticCalculator::SetObsToExpected(RooProdPdf &prod, const RooArgSet &obs)
 {
@@ -1003,9 +1008,9 @@ bool AsymptoticCalculator::SetObsToExpected(RooAbsPdf &pdf, const RooArgSet &obs
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// generate counting Asimov data for the case when the pdf cannot be extended
-/// assume pdf is a RooPoisson or can be decomposed in a product of RooPoisson,
-/// otherwise we cannot know how to make the Asimov data sets in the other cases
+/// Generate counting Asimov data for the case when the pdf cannot be extended.
+/// This function assumes that the pdf is a RooPoisson or can be decomposed in a product of RooPoisson,
+/// or is a RooGaussian. Otherwise, we cannot know how to make the Asimov data sets.
 
 RooAbsData * AsymptoticCalculator::GenerateCountingAsimovData(RooAbsPdf & pdf, const RooArgSet & observables,  const RooRealVar & , RooCategory * channelCat) {
     RooArgSet obs(observables);
@@ -1040,10 +1045,10 @@ RooAbsData * AsymptoticCalculator::GenerateCountingAsimovData(RooAbsPdf & pdf, c
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// compute the asimov data set for an observable of a pdf
-/// use the number of bins sets in the observables
-/// to do :  (possibility to change number of bins)
-/// implement integration over bin content
+/// Compute the asimov data set for an observable of a pdf.
+/// It generates binned data following the binning of the observables.
+// TODO: (possibility to change number of bins)
+// TODO: implement integration over bin content
 
 RooAbsData * AsymptoticCalculator::GenerateAsimovDataSinglePdf(const RooAbsPdf & pdf, const RooArgSet & allobs,  const RooRealVar & weightVar, RooCategory * channelCat) {
 
diff --git a/tutorials/roofit/rf604_constraints.C b/tutorials/roofit/rf604_constraints.C
index d368240ed3d..0dd7a6dfde1 100644
--- a/tutorials/roofit/rf604_constraints.C
+++ b/tutorials/roofit/rf604_constraints.C
@@ -48,7 +48,7 @@ void rf604_constraints()
    // -----------------------------------------
 
    // Construct Gaussian constraint p.d.f on parameter f at 0.8 with resolution of 0.1
-   RooGaussian fconstraint("fconstraint", "fconstraint", f, RooConst(0.8), RooConst(0.1));
+   RooGaussian fconstraint("fconstraint", "fconstraint", f, RooConst(0.8), RooConst(0.2));
 
    // M E T H O D   1   -   A d d   i n t e r n a l   c o n s t r a i n t   t o   m o d e l
    // -------------------------------------------------------------------------------------
@@ -68,7 +68,7 @@ void rf604_constraints()
    // M E T H O D   2   -     S p e c i f y   e x t e r n a l   c o n s t r a i n t   w h e n   f i t t i n g
    // -------------------------------------------------------------------------------------------------------
 
-   // Construct another Gaussian constraint p.d.f on parameter f at 0.8 with resolution of 0.1
+   // Construct another Gaussian constraint p.d.f on parameter f at 0.2 with resolution of 0.1
    RooGaussian fconstext("fconstext", "fconstext", f, RooConst(0.2), RooConst(0.1));
 
    // Fit with external constraint
-- 
GitLab