Implement usage for NormaliseByPeakArea

Also clarify a property description
Refs #9574

Code/Mantid/Framework/CurveFitting/src/NormaliseByPeakArea.cpp

@@ -63,7 +63,8 @@ namespace Mantid
       mustBePositive->setLower(0.0);
       mustBePositive->setLowerExclusive(true); //strictly greater than 0.0
       declareProperty("Mass",-1.0,mustBePositive,"The mass, in AMU, defining the recoil peak to fit");
-      declareProperty("Sum", true, "If true all spectra are summed in quadrature to produce the final result");
+      declareProperty("Sum", true, "If true all spectra on the Y-space, fitted & symmetrised workspaces "
+                      "are summed in quadrature to produce the final result");
 
       declareProperty(new WorkspaceProperty<>("OutputWorkspace","",Direction::Output),
                       "Input workspace normalised by the fitted peak area");

Code/Mantid/docs/source/algorithms/NormaliseByPeakArea-v1.rst

@@ -9,12 +9,15 @@
 Description
 -----------
 
-Takes an input TOF spectrum and converts it to Y-space using the
-:ref:`algm-ConvertToYSpace` algorithm. The result is then
-fitted using the ComptonPeakProfile function using the given mass to
+Takes an input TOF spectrum from :ref:`LoadVesuvio <algm-LoadVesuvio>` and
+converts it to Y-space using the
+:ref:`ConvertToYSpace <algm-ConvertToYSpace>` algorithm. The result is then
+fitted using the ComptonPeakProfile function and the given mass to
 produce an estimate of the peak area. The input data is normalised by
 this value.
 
+The input workspace is required to be a point data workspace. See :ref:`ConvertToPointData <algm-ConvertToPointData>`.
+
 The algorithm has 4 outputs:
 
 -  the input data normalised by the fitted peak area;
@@ -23,7 +26,62 @@ The algorithm has 4 outputs:
 -  the input data converted to Y and then symmetrised about Y=0.
 
 If the sum option is requested then all input spectra are rebinned, in
-steps of 0.5 :math:`A^-1`, to a common Y grid and then summed to give a
+steps of 0.5 :math:`\AA^{-1}`, to a common Y grid and then summed to give a
 single spectrum.
 
+Usage
+-----
+
+**Example - Normalise without summation:**
+
+.. testcode:: NormaliseNoSumOutput
+
+    ###### Simulates LoadVesuvio #################
+    tof_ws = CreateSimulationWorkspace(Instrument='Vesuvio',BinParams=[50,0.5,562],UnitX='TOF')
+    tof_ws = CropWorkspace(tof_ws,StartWorkspaceIndex=0,EndWorkspaceIndex=4)
+    tof_ws = ConvertToPointData(tof_ws)
+    SetInstrumentParameter(tof_ws,ParameterName='t0',ParameterType='Number',Value='0.5')
+    ##############################################
+
+    normalised, yspace, fitted, symmetrised = \
+      NormaliseByPeakArea(InputWorkspace=tof_ws, Mass=1.0079,Sum=False)
+
+    print "Number of normalised spectra is: %d" % normalised.getNumberHistograms()
+    print "Number of Y-space spectra is: %d" % yspace.getNumberHistograms()
+    print "Number of fitted spectra is: %d" % fitted.getNumberHistograms()
+    print "Number of symmetrised spectra is: %d" % symmetrised.getNumberHistograms()
+
+.. testoutput:: NormaliseNoSumOutput
+
+    Number of normalised spectra is: 5
+    Number of Y-space spectra is: 5
+    Number of fitted spectra is: 5
+    Number of symmetrised spectra is: 5
+
+**Example - Normalise with summation:**
+
+.. testcode:: NormaliseWithSummedOutput
+
+    ###### Simulates LoadVesuvio #################
+    tof_ws = CreateSimulationWorkspace(Instrument='Vesuvio',BinParams=[50,0.5,562],UnitX='TOF')
+    tof_ws = CropWorkspace(tof_ws,StartWorkspaceIndex=0,EndWorkspaceIndex=4)
+    tof_ws = ConvertToPointData(tof_ws)
+    SetInstrumentParameter(tof_ws,ParameterName='t0',ParameterType='Number',Value='0.5')
+    ##############################################
+
+    normalised, yspace, fitted, symmetrised = \
+      NormaliseByPeakArea(InputWorkspace=tof_ws, Mass=1.0079,Sum=True)
+
+    print "Number of normalised spectra is: %d" % normalised.getNumberHistograms()
+    print "Number of Y-space spectra is: %d" % yspace.getNumberHistograms()
+    print "Number of fitted spectra is: %d" % fitted.getNumberHistograms()
+    print "Number of symmetrised spectra is: %d" % symmetrised.getNumberHistograms()
+
+.. testoutput:: NormaliseWithSummedOutput
+
+    Number of normalised spectra is: 5
+    Number of Y-space spectra is: 1
+    Number of fitted spectra is: 1
+    Number of symmetrised spectra is: 1
+
 .. categories::