From 20bb0e05a62976af7d89a96cb5425728468fe498 Mon Sep 17 00:00:00 2001 From: "Bastian M. Wojek" Date: Sun, 27 Jun 2010 11:23:40 +0000 Subject: [PATCH] Added a tiny bit of documentation for the msr2data code --- src/classes/PMsr2Data.cpp | 115 ++++++++++++++++++++++++++++++++------ src/include/PMsr2Data.h | 3 +- src/msr2data.cpp | 17 +++--- 3 files changed, 110 insertions(+), 25 deletions(-) diff --git a/src/classes/PMsr2Data.cpp b/src/classes/PMsr2Data.cpp index 3a8eef87..3ad0ae70 100644 --- a/src/classes/PMsr2Data.cpp +++ b/src/classes/PMsr2Data.cpp @@ -53,6 +53,10 @@ using namespace boost::algorithm; //------------------------------------------------------------- /** *

Write formatted output to column-formatted ASCII output file + * + * \param outFile output file stream to the ASCII file + * \param value number to be written to the ASCII file + * \param width column width of the ASCII file */ void writeValues(ofstream &outFile, const double &value, const unsigned int &width) { @@ -66,7 +70,9 @@ void writeValues(ofstream &outFile, const double &value, const unsigned int &wid //------------------------------------------------------------- /** - *

+ *

Constructor + * + * \param ext extension/suffix of the msr-files to be processed */ PMsr2Data::PMsr2Data(const string &ext) : fFileExtension(ext), fRunListFile(false), fNumGlobalParam(0), fNumSpecParam(0), fNumTempRunBlocks(0) { @@ -81,7 +87,7 @@ PMsr2Data::PMsr2Data(const string &ext) : fFileExtension(ext), fRunListFile(fals //------------------------------------------------------------- /** - *

+ *

Destructor */ PMsr2Data::~PMsr2Data() { @@ -114,7 +120,11 @@ PMsr2Data::~PMsr2Data() //------------------------------------------------------------- /** - *

+ *

Determines the current run number + * + *

return: + * - current run number + * - 0 if all runs have been processed already */ unsigned int PMsr2Data::GetPresentRun() const { @@ -126,7 +136,13 @@ unsigned int PMsr2Data::GetPresentRun() const //------------------------------------------------------------- /** - *

+ *

Initialization of the internal list of runs using a single run number + * + *

return: + * - 0 if the run number is valid + * - 1 otherwise + * + * \param runNo run number */ int PMsr2Data::SetRunNumbers(unsigned int runNo) { @@ -142,7 +158,14 @@ int PMsr2Data::SetRunNumbers(unsigned int runNo) //------------------------------------------------------------- /** - *

+ *

Initialization of the internal list of runs using first and last run numbers + * + *

return: + * - 0 if the run numbers are valid + * - 1 otherwise + * + * \param runNoStart first run number + * \param runNoEnd last run number */ int PMsr2Data::SetRunNumbers(unsigned int runNoStart, unsigned int runNoEnd) { @@ -164,7 +187,14 @@ int PMsr2Data::SetRunNumbers(unsigned int runNoStart, unsigned int runNoEnd) //------------------------------------------------------------- /** - *

+ *

Initialization of the internal list of runs using a explicitly specified run numbers + * + *

return: + * - -1 if the vector is empty + * - 0 if all run numbers are valid + * - 1 otherwise + * + * \param runListVector vector containing the run numbers to be processed */ int PMsr2Data::SetRunNumbers(const vector &runListVector) { @@ -184,7 +214,14 @@ int PMsr2Data::SetRunNumbers(const vector &runListVector) //------------------------------------------------------------- /** - *

+ *

Initialization of the internal list of runs using a run list file + * + *

return: + * - -1 if the run list file cannot be opened + * - 0 if all run numbers are valid + * - 1 otherwise + * + * \param runListFile name of run list file */ int PMsr2Data::SetRunNumbers(const string &runListFile) { @@ -247,7 +284,11 @@ int PMsr2Data::SetRunNumbers(const string &runListFile) //------------------------------------------------------------- /** - *

+ *

Parse the musrfit startup xml file + * + *

return: + * - 0 if everything went fine + * - return value of the ParseFile-method otherwise */ int PMsr2Data::ParseXmlStartupFile() { @@ -275,7 +316,13 @@ int PMsr2Data::ParseXmlStartupFile() //------------------------------------------------------------- /** - *

+ *

Read in a msr-file + * + *

return: + * - PMUSR_SUCCESS if everything is OK + * - return value of the ReadMsrFile-method otherwise + * + * \param infile name of the msr-file to be read */ int PMsr2Data::ReadMsrFile(const string &infile) const { @@ -300,7 +347,11 @@ int PMsr2Data::ReadMsrFile(const string &infile) const //------------------------------------------------------------- /** - *

+ *

Read in a run data-file + * + *

return: + * - true if everything is OK + * - false otherwise */ bool PMsr2Data::ReadRunDataFile() { @@ -320,7 +371,13 @@ bool PMsr2Data::ReadRunDataFile() //------------------------------------------------------------- /** - *

+ *

Generate a new single run msr-file from a template + * + *

return: + * - true if everything is OK + * - false otherwise + * + * \param tempRun template run number */ bool PMsr2Data::PrepareNewInputFile(unsigned int tempRun) const { @@ -401,7 +458,16 @@ bool PMsr2Data::PrepareNewInputFile(unsigned int tempRun) const //------------------------------------------------------------- /** - *

+ *

Function defining the parameter order for the sort algorithm when a global msr-file is generated + * + *

return: + * - true if global parameters are listed before run specific ones + * - true if within the global parameters par1 appears before par2 + * - true if within the run specific parameters par1 appears before par2 + * - false otherwise + * + * \param par1 fit parameter + * \param par2 fit parameter */ bool compare_parameters(const PMsrParamStructure &par1, const PMsrParamStructure &par2) { @@ -423,7 +489,14 @@ bool compare_parameters(const PMsrParamStructure &par1, const PMsrParamStructure //------------------------------------------------------------- /** - *

+ *

Generate a new global msr-file from a template + * + *

return: + * - true if everything is OK + * - false otherwise + * + * \param tempRun template run number + * \param msrOutFile name of the global msr-file to be written */ bool PMsr2Data::PrepareGlobalInputFile(unsigned int tempRun, const string &msrOutFile) const { @@ -581,7 +654,7 @@ bool PMsr2Data::PrepareGlobalInputFile(unsigned int tempRun, const string &msrOu tempLines = fMsrHandler->GetMsrFunctions(); for (unsigned int i(0); i < tempLines->size(); ++i) { line = (*tempLines)[i].fLine.Data(); - split( tempVec, line, is_any_of(" ()+-*/=\t") ); // split the function line at spaces and some characters that might be juxtaposed to the parameters + split( tempVec, line, is_any_of(" ()+-*/=\t,") ); // split the function line at spaces and some characters that might be juxtaposed to the parameters for (unsigned int j(1); j < tempVec.size(); ++j) { if (!tempVec[j].substr(0,3).compare("par")) { try { @@ -881,7 +954,7 @@ bool PMsr2Data::PrepareGlobalInputFile(unsigned int tempRun, const string &msrOu string::size_type pos(0); for (unsigned int i(0); i < tempLines->size(); ++i) { line = (*tempLines)[i].fLine.Data(); - split( tempVec, line, is_any_of(" ()+-*/=\t") ); // split the function line at spaces and some characters that might be juxtaposed to the parameters + split( tempVec, line, is_any_of(" ()+-*/=\t,") ); // split the function line at spaces and some characters that might be juxtaposed to the parameters for (unsigned int j(1); j < tempVec.size(); ++j) { if (!tempVec[j].substr(0,3).compare("par")) { try { @@ -1198,7 +1271,17 @@ bool PMsr2Data::PrepareGlobalInputFile(unsigned int tempRun, const string &msrOu //------------------------------------------------------------- /** - *

+ *

Append fit parameters of a msr-file to the DB or ASCII file + * + *

return: + * - PMUSR_SUCCESS if everything is OK + * - -1 in case of an error + * + * \param outfile name of the DB/ASCII output file + * \param db DB or plain ASCII output + * \param withHeader write output file header or not + * \param global global mode or not + * \param counter counter used within the global mode to determine how many runs have been processed already */ int PMsr2Data::WriteOutput(const string &outfile, bool db, bool withHeader, bool global, unsigned int counter) const { diff --git a/src/include/PMsr2Data.h b/src/include/PMsr2Data.h index 8e44d6a5..4e978fff 100644 --- a/src/include/PMsr2Data.h +++ b/src/include/PMsr2Data.h @@ -48,7 +48,8 @@ using namespace std; //------------------------------------------------------------- /** - *

+ *

Class providing the necessary utilities for msr2data: + * generate new msr-files from a template, collect fit parameters from msr-files and write them to DB or plain ASCII files */ class PMsr2Data { diff --git a/src/msr2data.cpp b/src/msr2data.cpp index 9cb2d92e..032b4a2e 100644 --- a/src/msr2data.cpp +++ b/src/msr2data.cpp @@ -51,11 +51,11 @@ using namespace boost::algorithm; /** *

Checks if a string is an integer * - * return: + *

return: * - true if s is a number string * - false otherwise * - * \param s + * \param s string */ bool isNumber(const string &s) // will be replaced by boost::lexical_cast at some time { @@ -117,8 +117,8 @@ void msr2data_syntax() /** *

filters out the output file name from at argument string * - * return: - * - output file name is present in the argument list + *

return: + * - output file name if present in the argument list * - otherwise 'out.db' (db==true), 'out.dat' (db==false) * * \param arg argument string list from the msr2data call @@ -165,7 +165,7 @@ string msr2data_outputfile(vector &arg, bool db = true) /** *

Checks if option string is present in the argument input list * - * return: + *

return: * - true if option is not present * - false otherwise * @@ -191,13 +191,14 @@ bool msr2data_useOption(vector &arg, const string &s) *

Filters out the template run number (if present) and check at the * same time if only already existing msr-files shall be fitted (no template). * - * return: + *

return: * - template runNo if everything is OK * - -1 : tag: fit only, do not prepare input files * - -2 : fatal error - more than one fit-<temp> options are specified * * \param arg list of arguments * \param chainfit if true + * */ int msr2data_doFitting(vector &arg, bool &chainfit) { @@ -269,8 +270,8 @@ unsigned int msr2data_doInputCreation(vector &arg, bool &inputOnly) //-------------------------------------------------------------------------- /** - *

msr2data is used to generate msr-files based on template msr-files, automatically fitting these new msr-files, - * collection fitting parameters, etc. For a detailed description see + *

msr2data is used to generate msr-files based on template msr-files, automatically fit these new msr-files, + * collect fitting parameters, etc. For a detailed description see * \htmlonly musr2data online help * \endhtmlonly * \latexonly msr2data online help: \texttt{https://intranet.psi.ch/MUSR/Msr2Data}