DOC: Document methods in header file

Document methods in header file: Doxygen picks the method documentation
from the header files, and leaves the method documentation empty if it
does not find it there.

Increase consistency in the characters used for documentation blocks,
and follow the ITK SW Guideline.

Take advantage of the commit to fix the method descriptions where
necessary (i.e. provide an accurate description of the method, do not
use the description of another method, etc.), and improve the wording
where appropriate (avoiding expressions like "This method (...)"),
including fixing typos and grammar.

Finish method documentation sentences with a period.

Remove the documentation of trivial methods: constructors, destructors
and `PrintSelf` methods.

Modules/Core/Transform/include/itkScalableAffineTransform.h

@@ -83,13 +83,12 @@ class ITK_TEMPLATE_EXPORT ScalableAffineTransform : public AffineTransform<TPara
   using InverseTransformBaseType = typename Superclass::InverseTransformBaseType;
   using InverseTransformBasePointer = typename InverseTransformBaseType::Pointer;
 
-  /** Set the transformation to an Identity
-   *
-   * This sets the matrix to identity and the Offset to null. */
+  /** Set the transformation to an Identity.
+   * Sets the matrix to identity and the Offset to null. */
   void
   SetIdentity() override;
 
-  /** Set the scale of the transform */
+  /** Set the scale of the transform. */
   virtual void
   SetScale(const InputVectorType & scale);
 
@@ -99,7 +98,7 @@ class ITK_TEMPLATE_EXPORT ScalableAffineTransform : public AffineTransform<TPara
     this->SetScale(scale);
   }
 
-  /** Set the scale of the transform */
+  /** Set the scale of the transform. */
   virtual void
   SetScale(const double scale[VDimension]);
 
@@ -121,11 +120,11 @@ class ITK_TEMPLATE_EXPORT ScalableAffineTransform : public AffineTransform<TPara
     return m_Scale;
   }
 
-  /** Get an inverse of this transform. */
+  /** Get an inverse of the transform. */
   bool
   GetInverse(Self * inverse) const;
 
-  /** Return an inverse of this transform. */
+  /** Return an inverse of the transform. */
   InverseTransformBasePointer
   GetInverseTransform() const override;
 
@@ -142,13 +141,12 @@ class ITK_TEMPLATE_EXPORT ScalableAffineTransform : public AffineTransform<TPara
   ScalableAffineTransform(unsigned int parametersDimension);
   ScalableAffineTransform();
 
+  /** Compute the transformation matrix. */
   void
   ComputeMatrix() override;
 
-  /** Destroy an ScalableAffineTransform object   */
   ~ScalableAffineTransform() override = default;
 
-  /** Print contents of an ScalableAffineTransform */
   void
   PrintSelf(std::ostream & os, Indent indent) const override;
 

Modules/Core/Transform/include/itkScalableAffineTransform.hxx

@@ -25,7 +25,7 @@
 
 namespace itk
 {
-/** Constructor with default arguments */
+
 template <typename TParametersValueType, unsigned int VDimension>
 ScalableAffineTransform<TParametersValueType, VDimension>::ScalableAffineTransform()
   : Superclass(Self::ParametersDimension)
@@ -37,7 +37,6 @@ ScalableAffineTransform<TParametersValueType, VDimension>::ScalableAffineTransfo
   }
 }
 
-/** Constructor with default arguments */
 template <typename TParametersValueType, unsigned int VDimension>
 ScalableAffineTransform<TParametersValueType, VDimension>::ScalableAffineTransform(unsigned int,
                                                                                    unsigned int parametersDimension)
@@ -61,7 +60,6 @@ ScalableAffineTransform<TParametersValueType, VDimension>::ScalableAffineTransfo
   }
 }
 
-/** Constructor with default arguments */
 template <typename TParametersValueType, unsigned int VDimension>
 ScalableAffineTransform<TParametersValueType, VDimension>::ScalableAffineTransform(const MatrixType &       matrix,
                                                                                    const OutputVectorType & offset)
@@ -74,7 +72,6 @@ ScalableAffineTransform<TParametersValueType, VDimension>::ScalableAffineTransfo
   }
 }
 
-/** Print self */
 template <typename TParametersValueType, unsigned int VDimension>
 void
 ScalableAffineTransform<TParametersValueType, VDimension>::PrintSelf(std::ostream & os, Indent indent) const
@@ -97,7 +94,6 @@ ScalableAffineTransform<TParametersValueType, VDimension>::PrintSelf(std::ostrea
   os << std::endl;
 }
 
-// Set the parameters in order to fit an Identity transform
 template <typename TParametersValueType, unsigned int VDimension>
 void
 ScalableAffineTransform<TParametersValueType, VDimension>::SetIdentity()
@@ -110,7 +106,6 @@ ScalableAffineTransform<TParametersValueType, VDimension>::SetIdentity()
   this->Superclass::SetIdentity();
 }
 
-/** Set the scale of the transformation */
 template <typename TParametersValueType, unsigned int VDimension>
 void
 ScalableAffineTransform<TParametersValueType, VDimension>::SetScale(const InputVectorType & scale)
@@ -139,15 +134,13 @@ ScalableAffineTransform<TParametersValueType, VDimension>::SetScale(const double
   this->Modified();
 }
 
-// Get an inverse of this transform
 template <typename TParametersValueType, unsigned int VDimension>
 bool
 ScalableAffineTransform<TParametersValueType, VDimension>::GetInverse(Self * inverse) const
 {
   return this->Superclass::GetInverse(inverse);
 }
 
-// Return an inverse of this transform
 template <typename TParametersValueType, unsigned int VDimension>
 auto
 ScalableAffineTransform<TParametersValueType, VDimension>::GetInverseTransform() const -> InverseTransformBasePointer
@@ -157,7 +150,6 @@ ScalableAffineTransform<TParametersValueType, VDimension>::GetInverseTransform()
   return this->GetInverse(inv) ? inv.GetPointer() : nullptr;
 }
 
-/** Set the scale of the transformation */
 template <typename TParametersValueType, unsigned int VDimension>
 void
 ScalableAffineTransform<TParametersValueType, VDimension>::ComputeMatrix()

Modules/IO/GIPL/include/itkGiplImageIO.h

@@ -60,7 +60,7 @@ class ITKIOGIPL_EXPORT GiplImageIO : public ImageIOBase
   bool
   CanReadFile(const char *) override;
 
-  /** Set the spacing and dimension information for the set filename. */
+  /** Read information about the Gipl file and put the cursor of the stream just before the first data pixel. */
   void
   ReadImageInformation() override;
 

Modules/IO/GIPL/src/itkGiplImageIO.cxx

@@ -72,7 +72,6 @@ class GiplImageIOInternals
 #define GIPL_MAGIC_NUMBER 0xefffe9b0
 #define GIPL_MAGIC_NUMBER2 0x2ae389b8
 
-/** Constructor */
 GiplImageIO::GiplImageIO()
 {
   m_Internal = new GiplImageIOInternals;
@@ -81,7 +80,6 @@ GiplImageIO::GiplImageIO()
   m_IsCompressed = false;
 }
 
-/** Destructor */
 GiplImageIO::~GiplImageIO()
 {
   if (m_IsCompressed)
@@ -254,10 +252,6 @@ GiplImageIO::Read(void * buffer)
   SwapBytesIfNecessary(buffer, numberOfPixels);
 }
 
-/**
- *  Read Information about the Gipl file
- *  and put the cursor of the stream just before the first data pixel
- */
 void
 GiplImageIO::ReadImageInformation()
 {
@@ -1100,7 +1094,6 @@ GiplImageIO ::Write(const void * buffer)
   }
 }
 
-/** Print Self Method */
 void
 GiplImageIO::PrintSelf(std::ostream & os, Indent indent) const
 {

Modules/Nonunit/Review/include/itkScalarRegionBasedLevelSetFunction.h

@@ -120,10 +120,10 @@ class ITK_TEMPLATE_EXPORT ScalarRegionBasedLevelSetFunction
   using ListPixelIterator = typename ListPixelType::iterator;
   using ListImageType = Image<ListPixelType, Self::ImageDimension>;
 
-  /** \brief Performs the narrow-band update of the Heaviside function for each
-  voxel. The characteristic function of each region is recomputed (note the
-  shared data which contains information from the other level sets). Using the
-  new H values, the previous c_i are updated. */
+  /** Performs the narrow-band update of the Heaviside function for each
+   *  voxel. The characteristic function of each region is recomputed (note the
+   *  shared data which contains information from the other level sets). Using the
+   *  new $H$ values, the previous $c_i$ are updated. */
   void
   UpdatePixel(const unsigned int                  idx,
               NeighborhoodIterator<TInputImage> & iterator,
@@ -136,12 +136,14 @@ class ITK_TEMPLATE_EXPORT ScalarRegionBasedLevelSetFunction
   {}
   ~ScalarRegionBasedLevelSetFunction() override = default;
 
+  /** Compute the overlap multiplicative factors for the penalty term (sum) and
+   *  the background intensity fitting terms in multiphase level-sets. */
   ScalarValueType
   ComputeOverlapParameters(const FeatureIndexType & featIndex, ScalarValueType & product) override;
 
-  // update the background and foreground constants for pixel updates
-  // Called only when sparse filters are used to prevent iteration through the
-  // entire image
+  /** Update the background and foreground constants for pixel updates.
+   *  Called only when sparse filters are used to prevent iteration through the
+   *  entire image. */
   virtual void
   UpdateSharedDataInsideParameters(const unsigned int &     iId,
                                    const FeaturePixelType & iVal,

Modules/Nonunit/Review/include/itkScalarRegionBasedLevelSetFunction.hxx

@@ -21,8 +21,7 @@
 
 namespace itk
 {
-// Computes the overlap multiplicative factors for the penalty term (sum) and
-// the background intensity fitting terms in multiphase level-sets
+
 template <typename TInputImage, typename TFeatureImage, typename TSharedData>
 typename ScalarRegionBasedLevelSetFunction<TInputImage, TFeatureImage, TSharedData>::ScalarValueType
 ScalarRegionBasedLevelSetFunction<TInputImage, TFeatureImage, TSharedData>::ComputeOverlapParameters(
@@ -60,11 +59,6 @@ ScalarRegionBasedLevelSetFunction<TInputImage, TFeatureImage, TSharedData>::Comp
   return sum;
 }
 
-/* Performs the narrow-band update of the Heaviside function for each voxel. The
-characteristic function of each region is recomputed (note the shared
-data which contains information from the other level sets). Using the
-new H values, the previous c_i are updated. Used by only the sparse image
-filter */
 template <typename TInputImage, typename TFeatureImage, typename TSharedData>
 void
 ScalarRegionBasedLevelSetFunction<TInputImage, TFeatureImage, TSharedData>::UpdatePixel(

Modules/Numerics/Optimizersv4/include/itkRegistrationParameterScalesFromJacobian.h

@@ -70,7 +70,11 @@ class ITK_TEMPLATE_EXPORT RegistrationParameterScalesFromJacobian : public Regis
   using typename Superclass::JacobianType;
   using typename Superclass::VirtualImageConstPointer;
 
-  /** Estimate parameter scales. */
+  /** Estimate parameter scales from average Jacobian norms.
+   *  For each parameter, compute the squared norm of its transform Jacobian,
+   *  then average the squared norm over the sample points. This average is
+   *  used as the scale of this parameter.
+   */
   void
   EstimateScales(ScalesType & parameterScales) override;
 
@@ -94,7 +98,10 @@ class ITK_TEMPLATE_EXPORT RegistrationParameterScalesFromJacobian : public Regis
   FloatType
   EstimateStepScale(const ParametersType & step) override;
 
-  /** Estimate the scales of local steps. */
+  /** Estimate the scales of local steps. For each voxel, computes the impact
+   * of a step on its location as in ::EstimateStepScale. Then this impact is
+   * attributed to the corresponding local parameters.
+   */
   void
   EstimateLocalStepScales(const ParametersType & step, ScalesType & localStepScales) override;
 

Modules/Numerics/Optimizersv4/include/itkRegistrationParameterScalesFromJacobian.hxx

@@ -22,11 +22,6 @@
 namespace itk
 {
 
-/** Compute parameter scales from average jacobian norms.
- *  For each parameter, compute the squared norm of its transform Jacobian,
- *  then average the squared norm over the sample points. This average is
- *  used as the scale of this parameter.
- */
 template <typename TMetric>
 void
 RegistrationParameterScalesFromJacobian<TMetric>::EstimateScales(ScalesType & parameterScales)
@@ -66,9 +61,6 @@ RegistrationParameterScalesFromJacobian<TMetric>::EstimateScales(ScalesType & pa
   }
 }
 
-/**
- *  Compute the scale for a STEP, the impact of a STEP on the transform.
- */
 template <typename TMetric>
 auto
 RegistrationParameterScalesFromJacobian<TMetric>::EstimateStepScale(const ParametersType & step) -> FloatType
@@ -92,11 +84,6 @@ RegistrationParameterScalesFromJacobian<TMetric>::EstimateStepScale(const Parame
   return scaleSum / numSamples;
 }
 
-/**
- * Estimate the scales of local steps. For each voxel, we compute the impact
- * of a STEP on its location as in EstimateStepScale. Then we attribute this
- * impact to the corresponding local parameters.
- */
 template <typename TMetric>
 void
 RegistrationParameterScalesFromJacobian<TMetric>::EstimateLocalStepScales(const ParametersType & step,
@@ -132,10 +119,6 @@ RegistrationParameterScalesFromJacobian<TMetric>::EstimateLocalStepScales(const
   }
 }
 
-/**
- *  Compute the step scales for samples, i.e. the impacts on each sampled
- *  voxel from a change on the transform.
- */
 template <typename TMetric>
 void
 RegistrationParameterScalesFromJacobian<TMetric>::ComputeSampleStepScales(const ParametersType & step,
@@ -191,7 +174,6 @@ RegistrationParameterScalesFromJacobian<TMetric>::ComputeSampleStepScales(const
   }
 }
 
-/** Print the information about this class */
 template <typename TMetric>
 void
 RegistrationParameterScalesFromJacobian<TMetric>::PrintSelf(std::ostream & os, Indent indent) const

Modules/Registration/PDEDeformable/include/itkESMDemonsRegistrationFunction.h

@@ -185,16 +185,16 @@ class ITK_TEMPLATE_EXPORT ESMDemonsRegistrationFunction
     return global;
   }
 
-  /** Release memory for global data structure. */
+  /** Update the metric and release memory for the per-thread-global data structure. */
   void
   ReleaseGlobalDataPointer(void * gd) const override;
 
   /** Set the object's state before each iteration. */
   void
   InitializeIteration() override;
 
-  /** This method is called by a finite difference solver image filter at
-   * each pixel that does not lie on a data set boundary */
+  /** Compute update at a non-boundary neighbourhood. Called by a finite difference solver image filter at
+   * each pixel that does not lie on a data set boundary. */
   PixelType
   ComputeUpdate(const NeighborhoodType & it, void * gd, const FloatOffsetType & offset = FloatOffsetType(0.0)) override;
 

Modules/Registration/PDEDeformable/include/itkESMDemonsRegistrationFunction.hxx

@@ -22,9 +22,7 @@
 
 namespace itk
 {
-/**
- * Default constructor
- */
+
 template <typename TFixedImage, typename TMovingImage, typename TDisplacementField>
 ESMDemonsRegistrationFunction<TFixedImage, TMovingImage, TDisplacementField>::ESMDemonsRegistrationFunction()
 {
@@ -74,9 +72,6 @@ ESMDemonsRegistrationFunction<TFixedImage, TMovingImage, TDisplacementField>::ES
   m_SumOfSquaredChange = 0.0;
 }
 
-/*
- * Standard "PrintSelf" method.
- */
 template <typename TFixedImage, typename TMovingImage, typename TDisplacementField>
 void
 ESMDemonsRegistrationFunction<TFixedImage, TMovingImage, TDisplacementField>::PrintSelf(std::ostream & os,
@@ -133,9 +128,6 @@ ESMDemonsRegistrationFunction<TFixedImage, TMovingImage, TDisplacementField>::Ge
   return m_IntensityDifferenceThreshold;
 }
 
-/**
- * Set the function state values before each iteration
- */
 template <typename TFixedImage, typename TMovingImage, typename TDisplacementField>
 void
 ESMDemonsRegistrationFunction<TFixedImage, TMovingImage, TDisplacementField>::InitializeIteration()
@@ -189,9 +181,6 @@ ESMDemonsRegistrationFunction<TFixedImage, TMovingImage, TDisplacementField>::In
   m_SumOfSquaredChange = 0.0;
 }
 
-/**
- * Compute update at a non boundary neighbourhood
- */
 template <typename TFixedImage, typename TMovingImage, typename TDisplacementField>
 typename ESMDemonsRegistrationFunction<TFixedImage, TMovingImage, TDisplacementField>::PixelType
 ESMDemonsRegistrationFunction<TFixedImage, TMovingImage, TDisplacementField>::ComputeUpdate(
@@ -431,9 +420,6 @@ ESMDemonsRegistrationFunction<TFixedImage, TMovingImage, TDisplacementField>::Co
   return update;
 }
 
-/**
- * Update the metric and release the per-thread-global data.
- */
 template <typename TFixedImage, typename TMovingImage, typename TDisplacementField>
 void
 ESMDemonsRegistrationFunction<TFixedImage, TMovingImage, TDisplacementField>::ReleaseGlobalDataPointer(void * gd) const