added doxygen docu to spirit X3 under tests.

src/tests/spirit/PFunctionHandler.cpp

@@ -5,12 +5,10 @@
   Author: Andreas Suter
   e-mail: andreas.suter@psi.ch
 
-  $Id$
-
 ***************************************************************************/
 
 /***************************************************************************
- *   Copyright (C) 2007 by Andreas Suter                                   *
+ *   Copyright (C) 2007-2026 by Andreas Suter                              *
  *   andreas.suter@psi.c                                                   *
  *                                                                         *
  *   This program is free software; you can redistribute it and/or modify  *
@@ -38,14 +36,19 @@
 
 #include "PFunctionHandler.h"
 
-//-------------------------------------------------------------
-// Constructor
 //-------------------------------------------------------------
 /**
- * <p>
+ * @brief Constructs a PFunctionHandler from a file.
  *
- * \param fln
+ * Reads the specified file to extract parameter values (PAR block),
+ * map indices (MAP block), and function definitions (FUNCTIONS block).
+ * Validates that all required blocks are present and that map indices
+ * are within parameter bounds.
+ *
+ * @param fln Filename containing the function definitions
+ * @param debug Enable debug output showing parsing details
  */
+//-------------------------------------------------------------
 PFunctionHandler::PFunctionHandler(char *fln, bool debug) : fDebug(debug), fFileName(fln)
 {
   fValid = true;
@@ -58,14 +61,18 @@ PFunctionHandler::PFunctionHandler(char *fln, bool debug) : fDebug(debug), fFile
     fValid = MapsAreValid();
 }
 
-//-------------------------------------------------------------
-// Constructor
 //-------------------------------------------------------------
 /**
- * <p>
+ * @brief Constructs a PFunctionHandler from a vector of input lines.
  *
- * \param lines
+ * Parses the provided lines to extract PAR, MAP, and FUNCTIONS blocks.
+ * This constructor is useful for testing or when input comes from
+ * sources other than files. Validates that all required blocks are
+ * present and that map indices are within parameter bounds.
+ *
+ * @param lines Vector of strings containing the input (PAR, MAP, FUNCTIONS blocks)
  */
+//-------------------------------------------------------------
 PFunctionHandler::PFunctionHandler(std::vector<std::string> lines)
 {
   fValid = true;
@@ -152,13 +159,13 @@ PFunctionHandler::PFunctionHandler(std::vector<std::string> lines)
   }
 }
 
-//-------------------------------------------------------------
-// Destructor
 //-------------------------------------------------------------
 /**
- * <p>
+ * @brief Destructor - releases all resources.
  *
+ * Clears parameter, map, line, and function vectors to free memory.
  */
+//-------------------------------------------------------------
 PFunctionHandler::~PFunctionHandler()
 {
   std::cout << std::endl << "in ~PFunctionHandler()" << std::endl << std::endl;
@@ -169,13 +176,19 @@ PFunctionHandler::~PFunctionHandler()
   fFuncs.clear();
 }
 
-//-------------------------------------------------------------
-// DoParse (public)
 //-------------------------------------------------------------
 /**
- * <p>
+ * @brief Parses all function definitions using the X3 grammar.
  *
+ * Iterates through all function lines, parsing each with the Spirit X3
+ * grammar to create PFunction objects. Performs validation checks:
+ * - All functions parse successfully
+ * - Parameter and map indices are within bounds
+ * - Function numbers are unique (no duplicates)
+ *
+ * @return true if all functions parsed and validated successfully
  */
+//-------------------------------------------------------------
 bool PFunctionHandler::DoParse()
 {
   std::cout << std::endl << "in PFunctionHandler::DoParse() ...";
@@ -236,14 +249,17 @@ bool PFunctionHandler::DoParse()
   return success;
 }
 
-//-------------------------------------------------------------
-// Eval (public)
 //-------------------------------------------------------------
 /**
- * <p>
+ * @brief Evaluates a function by its function number.
  *
- * \param i
+ * Looks up the function in the internal vector using its function number
+ * (from the FUN# declaration) and evaluates it with current parameter values.
+ *
+ * @param i Function number to evaluate
+ * @return The evaluation result, or 0.0 if function not found
  */
+//-------------------------------------------------------------
 double PFunctionHandler::Eval(int i)
 {
   if (GetFuncIndex(i) == -1) {
@@ -254,14 +270,14 @@ double PFunctionHandler::Eval(int i)
   return fFuncs[GetFuncIndex(i)].Eval();
 }
 
-//-------------------------------------------------------------
-// GetFuncNo (public)
 //-------------------------------------------------------------
 /**
- * <p>
+ * @brief Gets the function number of the i-th parsed function.
  *
- * \param i
+ * @param i Index into the internal function vector (0-based)
+ * @return The function number (from FUN#), or -1 if index out of bounds
  */
+//-------------------------------------------------------------
 unsigned int PFunctionHandler::GetFuncNo(unsigned int i)
 {
   if (i > fFuncs.size())
@@ -270,13 +286,22 @@ unsigned int PFunctionHandler::GetFuncNo(unsigned int i)
   return fFuncs[i].GetFuncNo();
 }
 
-//-------------------------------------------------------------
-// ReadFile (private)
 //-------------------------------------------------------------
 /**
- * <p>
+ * @brief Reads and parses the input file.
  *
+ * Opens the file specified in fFileName and extracts:
+ * - PAR block: parameter values (up to 10 per line)
+ * - MAP block: map indices (up to 10 per line)
+ * - FUNCTIONS block: function definition lines
+ *
+ * Lines starting with # are treated as comments and ignored.
+ * Processing stops when END tag is encountered.
+ * Converts all input to uppercase for case-insensitive parsing.
+ *
+ * @return true if file was successfully read and all required blocks found
  */
+//-------------------------------------------------------------
 bool PFunctionHandler::ReadFile()
 {
   std::cout << std::endl << "in ~PFunctionHandler::ReadFile()";
@@ -377,13 +402,17 @@ bool PFunctionHandler::ReadFile()
   return success;
 }
 
-//-------------------------------------------------------------
-// MapsAreValid (private)
 //-------------------------------------------------------------
 /**
- * <p>
+ * @brief Validates that all map indices are within parameter bounds.
  *
+ * Checks that each value in the MAP block is a valid parameter index.
+ * Map values use 1-based indexing, so valid values are 1 to fParam.size().
+ * This validation prevents out-of-bounds access during function evaluation.
+ *
+ * @return true if all map indices are valid, false otherwise
  */
+//-------------------------------------------------------------
 bool PFunctionHandler::MapsAreValid()
 {
   bool success = true;
@@ -399,14 +428,18 @@ bool PFunctionHandler::MapsAreValid()
   return success;
 }
 
-//-------------------------------------------------------------
-// GetFuncIndex (private)
 //-------------------------------------------------------------
 /**
- * <p>
+ * @brief Finds the internal vector index for a function by its number.
  *
- * \param funcNo
+ * Searches the fFuncs vector for a function with the specified function
+ * number. This maps from the user-visible function number (FUN#) to the
+ * internal 0-based vector index.
+ *
+ * @param funcNo Function number to search for (from FUN# declaration)
+ * @return Index in fFuncs vector (0-based), or -1 if not found
  */
+//-------------------------------------------------------------
 int PFunctionHandler::GetFuncIndex(int funcNo)
 {
   int index = -1;