Fix Doxygen comments for void functions

Void functions should not use @return. It causes compiler warnings
like this one:

    src/classify/intproto.cpp:326:5: warning:
      '@return' command used in a comment that is attached to a function
      returning void [-Wdocumentation]

Some non-void functions also were documented with @return none.
Fix those comments, too.

Signed-off-by: Stefan Weil <sw@weilnetz.de>

src/classify/adaptmatch.cpp

@@ -849,8 +849,6 @@ bool Classify::AdaptableWord(WERD_RES* word) {
  * Globals:
  * - AllProtosOn dummy mask to match against all protos
  * - AllConfigsOn dummy mask to match against all configs
- *
- * @return none
  */
 void Classify::AdaptToChar(TBLOB* Blob, CLASS_ID ClassId, int FontinfoId,
                            float Threshold,

src/classify/cluster.cpp

@@ -509,7 +509,6 @@ LIST ClusterSamples(CLUSTERER *Clusterer, CLUSTERCONFIG *Config) {
  * longer exist.  Any sample lists that have been obtained
  * via calls to GetSamples are no longer valid.
  * @param Clusterer pointer to data structure to be freed
- * @return None
  */
 void FreeClusterer(CLUSTERER *Clusterer) {
   if (Clusterer != nullptr) {
@@ -534,7 +533,6 @@ void FreeClusterer(CLUSTERER *Clusterer) {
  * specified list of prototypes.  The clusters which are
  * pointed to by the prototypes are not freed.
  * @param ProtoList pointer to list of prototypes to be freed
- * @return None
  */
 void FreeProtoList(LIST *ProtoList) {
   destroy_nodes(*ProtoList, FreePrototype);
@@ -546,7 +544,6 @@ void FreeProtoList(LIST *ProtoList) {
  * is no longer marked as a prototype.  The cluster is NOT
  * deallocated by this routine.
  * @param arg prototype data structure to be deallocated
- * @return None
  */
 void FreePrototype(void *arg) {  //PROTOTYPE     *Prototype)
   auto *Prototype = static_cast<PROTOTYPE *>(arg);
@@ -646,8 +643,8 @@ float StandardDeviation(PROTOTYPE *Proto, uint16_t Dimension) {
  * tree are the individual samples themselves; they have no
  * sub-clusters.  The root node of the tree conceptually contains
  * all of the samples.
+ * The Clusterer data structure is changed.
  * @param Clusterer data structure holdings samples to be clustered
- * @return  None (the Clusterer data structure is changed)
  */
 static void CreateClusterTree(CLUSTERER *Clusterer) {
   ClusteringContext context;
@@ -863,7 +860,6 @@ int32_t MergeClusters(int16_t N,
  * structure.
  * @param Clusterer data structure holding cluster tree
  * @param Config    parameters used to control prototype generation
- * @return  None
  */
 static void ComputePrototypes(CLUSTERER* Clusterer, CLUSTERCONFIG* Config) {
   LIST ClusterStack = NIL_LIST;
@@ -1267,7 +1263,6 @@ static PROTOTYPE* MakeMixedProto(CLUSTERER* Clusterer,
  * @param i index of dimension to be changed
  * @param Proto prototype whose dimension is to be altered
  * @param ParamDesc description of specified dimension
- * @return  None
  */
 static void MakeDimRandom(uint16_t i, PROTOTYPE* Proto, PARAM_DESC* ParamDesc) {
   Proto->Distrib[i] = D_random;
@@ -1289,7 +1284,6 @@ static void MakeDimRandom(uint16_t i, PROTOTYPE* Proto, PARAM_DESC* ParamDesc) {
  * @param i index of dimension to be changed
  * @param Proto   prototype whose dimension is to be altered
  * @param Statistics  statistical info about prototype
- * @return  None
  */
 static void MakeDimUniform(uint16_t i, PROTOTYPE* Proto, STATISTICS* Statistics) {
   Proto->Distrib[i] = uniform;
@@ -1862,13 +1856,13 @@ static double Integral(double f1, double f2, double Dx) {
  * range and the StdDev is 1/2 the range.  A dimension with
  * zero standard deviation cannot be statistically analyzed.
  * In this case, a pseudo-analysis is used.
+ * The Buckets data structure is filled in.
  * @param Buckets histogram buckets to count samples
  * @param Cluster cluster whose samples are being analyzed
  * @param Dim dimension of samples which is being analyzed
  * @param ParamDesc description of the dimension
  * @param Mean  "mean" of the distribution
  * @param StdDev  "standard deviation" of the distribution
- * @return None (the Buckets data structure is filled in)
  */
 static void FillBuckets(BUCKETS *Buckets,
                  CLUSTER *Cluster,
@@ -2029,7 +2023,6 @@ static bool DistributionOK(BUCKETS* Buckets) {
  * This routine frees the memory used by the statistics
  * data structure.
  * @param Statistics  pointer to data structure to be freed
- * @return None
  */
 static void FreeStatistics(STATISTICS *Statistics) {
   free(Statistics->CoVariance);
@@ -2055,8 +2048,6 @@ static void FreeBuckets(BUCKETS *buckets) {
  * recursive calls to FreeCluster().
  *
  * @param Cluster pointer to cluster to be freed
- *
- * @return None
  */
 static void FreeCluster(CLUSTER *Cluster) {
   if (Cluster != nullptr) {
@@ -2096,7 +2087,6 @@ static uint16_t DegreesOfFreedom(DISTRIBUTION Distribution, uint16_t HistogramBu
  * is now adjusted to the new sample count.
  * @param Buckets histogram data structure to adjust
  * @param NewSampleCount  new sample count to adjust to
- * @return none
  */
 static void AdjustBuckets(BUCKETS *Buckets, uint32_t NewSampleCount) {
   int i;
@@ -2117,7 +2107,6 @@ static void AdjustBuckets(BUCKETS *Buckets, uint32_t NewSampleCount) {
  * This routine sets the bucket counts in the specified histogram
  * to zero.
  * @param Buckets histogram data structure to init
- * @return none
  */
 static void InitBuckets(BUCKETS *Buckets) {
   int i;
@@ -2156,7 +2145,7 @@ static int AlphaMatch(void *arg1,    //CHISTRUCT                             *Ch
  *
  * @param DegreesOfFreedom  degrees of freedom for new chi value
  * @param Alpha     confidence level for new chi value
- * @return none
+ * @return newly allocated data structure
  */
 static CHISTRUCT *NewChiStruct(uint16_t DegreesOfFreedom, double Alpha) {
   CHISTRUCT *NewChiStruct;

src/classify/clusttool.cpp

@@ -77,8 +77,6 @@ static float *ReadNFloats(TFile *fp, uint16_t N, float Buffer[]) {
  * @param File open text file to write N floats to
  * @param N number of floats to write
  * @param Array array of floats to write
- * @return None
- * @note Globals: None
  */
 static void WriteNFloats(FILE * File, uint16_t N, float Array[]) {
   for (int i = 0; i < N; i++)
@@ -92,8 +90,6 @@ static void WriteNFloats(FILE * File, uint16_t N, float Array[]) {
  * a carriage return to the end.
  * @param File open text file to write prototype style to
  * @param ProtoStyle prototype style to write
- * @return None
- * @note Globals: None
  */
 static void WriteProtoStyle(FILE *File, PROTOSTYLE ProtoStyle) {
   switch (ProtoStyle) {
@@ -254,8 +250,6 @@ PROTOTYPE *ReadPrototype(TFile *fp, uint16_t N) {
  * @param File open text file to write param descriptors to
  * @param N number of param descriptors to write
  * @param ParamDesc array of param descriptors to write
- * @return None
- * @note Globals: None
  */
 void WriteParamDesc(FILE *File, uint16_t N, const PARAM_DESC ParamDesc[]) {
   int i;
@@ -281,8 +275,6 @@ void WriteParamDesc(FILE *File, uint16_t N, const PARAM_DESC ParamDesc[]) {
  * @param File open text file to write prototype to
  * @param N number of dimensions in feature space
  * @param Proto prototype to write out
- * @return None
- * @note Globals: None
  */
 void WritePrototype(FILE *File, uint16_t N, PROTOTYPE *Proto) {
   int i;

src/classify/cutoffs.cpp

@@ -2,7 +2,6 @@
  ** Filename:    cutoffs.c
  ** Purpose:     Routines to manipulate an array of class cutoffs.
  ** Author:      Dan Johnson
- ** History:     Wed Feb 20 09:28:51 1991, DSJ, Created.
  **
  ** (c) Copyright Hewlett-Packard Company, 1988.
  ** Licensed under the Apache License, Version 2.0 (the "License");
@@ -39,8 +38,6 @@ namespace tesseract {
  * array are set to an arbitrarily high cutoff value.
  * @param fp file containing cutoff definitions
  * @param Cutoffs array to put cutoffs into
- * @return none
- * @note Globals: none
  */
 void Classify::ReadNewCutoffs(TFile* fp, CLASS_CUTOFF_ARRAY Cutoffs) {
   char Class[UNICHAR_LEN + 1];

src/classify/fpoint.cpp

@@ -39,8 +39,7 @@ float DistanceBetween(FPOINT A, FPOINT B) {
  * @param Point1 points to compute angle between
  * @param Point2 points to compute angle between
  * @param FullScale value to associate with 2*pi
- * @return none
- * @note Globals: none
+ * @return angle
  */
 float NormalizedAngleFrom(FPOINT *Point1, FPOINT *Point2, float FullScale) {
   float NumRadsInCircle = 2.0 * M_PI;

src/classify/intmatcher.cpp

@@ -96,7 +96,6 @@ namespace tesseract {
  * @param n Number of elements to sort
  * @param ra     Key array [1..n]
  * @param rb     Index array [1..n]
- * @return none
  */
 static void
 HeapSort (int n, int ra[], int rb[]) {
@@ -508,7 +507,6 @@ int Classify::PruneClasses(const INT_TEMPLATES_STRUCT* int_templates,
  * param NormalizationFactor Fudge factor from blob normalization process
  * param Result Class rating & configuration: (0.0 -> 1.0), 0=bad, 1=good
  * param Debug Debugger flag: 1=debugger on
- * @return none
  */
 void IntegerMatcher::Match(INT_CLASS ClassTemplate,
                            BIT_VECTOR ProtoMask,
@@ -752,7 +750,6 @@ void ScratchEvidence::ClearFeatureEvidence(const INT_CLASS class_template) {
 
 /**
  * Print debugging information for Configurations
- * @return none
  */
 static void IMDebugConfiguration(int FeatureNum, uint16_t ActualProtoNum,
                                  uint8_t Evidence, uint32_t ConfigWord) {
@@ -770,7 +767,6 @@ static void IMDebugConfiguration(int FeatureNum, uint16_t ActualProtoNum,
 
 /**
  * Print debugging information for Configurations
- * @return none
  */
 static void IMDebugConfigurationSum(int FeatureNum, uint8_t *FeatureEvidence,
                                     int32_t ConfigCount) {
@@ -790,7 +786,7 @@ static void IMDebugConfigurationSum(int FeatureNum, uint8_t *FeatureEvidence,
  * @param Feature Pointer to a feature struct
  * @param tables Evidence tables
  * @param Debug Debugger flag: 1=debugger on
- * @return none
+ * @return sum of feature evidence tables
  */
 int IntegerMatcher::UpdateTablesForFeature(
     INT_CLASS ClassTemplate,
@@ -931,7 +927,6 @@ int IntegerMatcher::UpdateTablesForFeature(
 
 /**
  * Print debugging information for Configurations
- * @return none
  */
 #ifndef GRAPHICS_DISABLED
 void IntegerMatcher::DebugFeatureProtoError(

src/classify/intproto.cpp

@@ -323,7 +323,6 @@ int AddIntProto(INT_CLASS Class) {
  * @param Proto   floating-pt proto to add to class pruner
  * @param ClassId   class id corresponding to Proto
  * @param Templates set of templates containing class pruner
- * @return none
  */
 void AddProtoToClassPruner (PROTO Proto, CLASS_ID ClassId,
                             INT_TEMPLATES Templates)
@@ -363,7 +362,6 @@ void AddProtoToClassPruner (PROTO Proto, CLASS_ID ClassId,
  * @param Class integer class that contains desired proto pruner
  * @param debug debug flag
  * @note Globals: none
- * @return none
  */
 void AddProtoToProtoPruner(PROTO Proto, int ProtoId,
                            INT_CLASS Class, bool debug) {
@@ -444,7 +442,6 @@ uint8_t CircBucketFor(float param, float offset, int num_buckets) {
  * Globals:
  * - FeatureShapes display list for features
  * - ProtoShapes display list for protos
- * @return none
  */
 void UpdateMatchDisplay() {
   if (IntMatchWindow != nullptr)
@@ -461,8 +458,6 @@ void UpdateMatchDisplay() {
  * @param Config    config to be added to class
  * @param ConfigId  id to be used for new config
  * @param Class   class to add new config to
- * @return none
- * @note Globals: none
  */
 void ConvertConfig(BIT_VECTOR Config, int ConfigId, INT_CLASS Class) {
   int ProtoId;
@@ -488,8 +483,6 @@ namespace tesseract {
  * @param Proto floating-pt proto to be converted to integer format
  * @param ProtoId id of proto
  * @param Class integer class to add converted proto to
- * @return none
- * @note Globals: none
  */
 void Classify::ConvertProto(PROTO Proto, int ProtoId, INT_CLASS Class) {
   INT_PROTO P;
@@ -592,7 +585,6 @@ INT_TEMPLATES Classify::CreateIntTemplates(CLASSES FloatProtos,
  * - FeatureShapes global display list for features
  * @param Feature   pico-feature to be displayed
  * @param Evidence  best evidence for this feature (0-1)
- * @return none
  */
 void DisplayIntFeature(const INT_FEATURE_STRUCT *Feature, float Evidence) {
   ScrollView::Color color = GetMatchColorFor(Evidence);
@@ -611,7 +603,6 @@ void DisplayIntFeature(const INT_FEATURE_STRUCT *Feature, float Evidence) {
  * @param Class   class to take proto from
  * @param ProtoId   id of proto in Class to be displayed
  * @param Evidence  total evidence for proto (0-1)
- * @return none
  */
 void DisplayIntProto(INT_CLASS Class, PROTO_ID ProtoId, float Evidence) {
   ScrollView::Color color = GetMatchColorFor(Evidence);
@@ -966,7 +957,6 @@ INT_TEMPLATES Classify::ReadIntTemplates(TFile *fp) {
  * Globals:
  * - FeatureShapes display list containing feature matches
  * - ProtoShapes display list containing proto matches
- * @return none
  */
 void Classify::ShowMatchDisplay() {
   InitIntMatchWindowIfReqd();
@@ -1022,8 +1012,6 @@ void ClearFeatureSpaceWindow(NORM_METHOD norm_method, ScrollView* window) {
  * @param File open file to write templates to
  * @param Templates templates to save into File
  * @param target_unicharset the UNICHARSET to use
- * @return none
- * @note Globals: none
  */
 void Classify::WriteIntTemplates(FILE *File, INT_TEMPLATES Templates,
                                  const UNICHARSET& target_unicharset) {
@@ -1129,8 +1117,6 @@ float BucketEnd(int Bucket, float Offset, int NumBuckets) {
  * @param ClassMask indicates which bits to change in each word
  * @param ClassCount  indicates what to change bits to
  * @param WordIndex indicates which word to change
- * @return none
- * @note Globals: none
  */
 void DoFill(FILL_SPEC *FillSpec,
             CLASS_PRUNER_STRUCT* Pruner,
@@ -1193,8 +1179,6 @@ bool FillerDone(TABLE_FILLER* Filler) {
  * @param Center center of filled area
  * @param Spread spread of filled area
  * @param debug debug flag
- * @return none
- * @note Globals: none
  */
 void FillPPCircularBits(uint32_t ParamTable[NUM_PP_BUCKETS][WERDS_PER_PP_VECTOR],
                         int Bit, float Center, float Spread, bool debug) {
@@ -1234,8 +1218,6 @@ void FillPPCircularBits(uint32_t ParamTable[NUM_PP_BUCKETS][WERDS_PER_PP_VECTOR]
  * @param Center center of filled area
  * @param Spread spread of filled area
  * @param debug debug flag
- * @return none
- * @note Globals: none
  */
 void FillPPLinearBits(uint32_t ParamTable[NUM_PP_BUCKETS][WERDS_PER_PP_VECTOR],
                       int Bit, float Center, float Spread, bool debug) {
@@ -1344,8 +1326,6 @@ CLASS_ID Classify::GetClassToDebug(const char *Prompt, bool* adaptive_on,
  * @param EndPad    place to put end pad for Level
  * @param SidePad   place to put side pad for Level
  * @param AnglePad  place to put angle pad for Level
- * @return none (results are returned in EndPad, SidePad, and AnglePad.
- * @note Globals: none
  */
 void GetCPPadsForLevel(int Level,
                        float *EndPad,
@@ -1407,8 +1387,6 @@ ScrollView::Color GetMatchColorFor(float Evidence) {
  * do not run past the end of the fill table.
  * @param Filler    filler to get next fill spec from
  * @param Fill    place to put spec for next fill
- * @return none (results are returned in Fill)
- * @note Globals: none
  */
 void GetNextFill(TABLE_FILLER *Filler, FILL_SPEC *Fill) {
   FILL_SWITCH *Next;
@@ -1451,14 +1429,11 @@ void GetNextFill(TABLE_FILLER *Filler, FILL_SPEC *Fill) {
 /**
  * This routine computes a data structure (Filler)
  * which can be used to fill in a rectangle surrounding
- * the specified Proto.
+ * the specified Proto. Results are returned in Filler.
  *
  * @param EndPad, SidePad, AnglePad padding to add to proto
  * @param Proto       proto to create a filler for
  * @param Filler        place to put table filler
- *
- * @return none (results are returned in Filler)
- * @note Globals: none
  */
 void InitTableFiller (float EndPad, float SidePad,
                       float AnglePad, PROTO Proto, TABLE_FILLER * Filler)

src/classify/kdtree.cpp

@@ -327,7 +327,6 @@ void KDWalk(KDTREE *Tree, void_proc action, void *context) {
  * which are pointed to by the nodes.  This memory is left
  * untouched.
  * @param Tree  tree data structure to be released
- * @return none
  */
 void FreeKDTree(KDTREE *Tree) {
   FreeSubTree(Tree->Root.Left);