diff --git a/math/fftw/src/TFFTComplex.cxx b/math/fftw/src/TFFTComplex.cxx
index 5dbe161bf466cba5500bd4ca674951f06e61f46c..aae654a6a3eb237fca5715c89e704c6d53bbd418 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 e7f2db3cc749364de985a4dfab25a7c6936eb23c..858129546e4e774d92fbf084d2412344ab05aa3b 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 be5fe92ebde2584b2d26224a2e9d38201db50651..76ff07c403ebfe801fa29d20b5fd1fa3466c720a 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 154f4a3e137708c2c356ea6070c49f77bd53570e..f69727712983e481509867dfcfddca0d32acb85c 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 0d2696240044f306dbd9ec325ee6f095188ec19a..26c611a4f4a0e3c1890370c73764674c383c92d2 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 85a2cb6f2e5a23d8cd5a8356845a5830d6be4536..dfc336b297b734cdbafbea3a1ba7fa7b30db2ca0 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 6272085c6d9a24cb47a3ec01a244a57c88e01c4d..c83e6c4838725cbae95234826ddaff5fc1f9e436 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 b2c719939514dcea7736dde38d1629028186ed50..917a8326f0eac8ec3b1816bb9bec1210d3c13f59 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 9f66d880f46adb367472ba9dad6d7ef7461be1f7..0fe50ea3222ec79907214f63260a5448e62c05c4 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 8fdff25bf69ca02818223b0615ffb8b001e84eff..36beb5daf02bb06b2fa6271fd6ba6991df1ce142 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 885f668b6e5ee05e184b4448eb64db2d9e1067f2..d31bd1eb6e69e935c508fb365106b3fde3841794 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 279bc98d843036828817f081e30d7a34b8f9906c..eac2d6dc11010aed0c09b7249b7d073cba51c90f 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 f624e32654f848a29061c34d2ca6508934eeddcc..ce3c45a5f641c0583b9bbfa5936d39e8aaceee6c 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 e2edb907515b839ac53c92c0372d3204e16155f9..578f61e0c217e576118885c20947b03319ccdb03 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 437e9d8972b007625bf100f936c5e59ea09f5c19..d82f6445164448f92ac9a0199296b34653731f6c 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 dd8c7e8182100365117403c60b3518e6d86bdafa..3c6f7fb9c7db061fc731932b4db0e29a59efd8cd 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 5d7c827e2126ca0f35c83225af8acf4b289d24b9..07bff55d3ca1259588a44ef3fa69b96c018091b7 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 d368240ed3d1619fbe186ab34fcc793782a56d9b..0dd7a6dfde191f190552dd72cb5dc19ee1e6ef2e 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