add documentation for potential file reader

src/potential_file_reader.cpp

@@ -29,6 +29,19 @@
 
 using namespace LAMMPS_NS;
 
+/** Class for reading and parsing LAMMPS potential files
+ *
+ * The value of the class member variable *ignore_comments* controls
+ * whether any text following the pound sign (#) should be ignored (true)
+ * or not (false). Default: true, i.e. ignore.
+ *
+ * \param  lmp             Pointer to LAMMPS instance
+ * \param  filename        Name of file to be read
+ * \param  potential_name  Name of potential style for error messages
+ * \param  auto_convert    Bitmask of supported unit conversions
+ *
+ * \sa TextFileReader */
+
 PotentialFileReader::PotentialFileReader(LAMMPS *lmp,
                                          const std::string &filename,
                                          const std::string &potential_name,
@@ -53,14 +66,21 @@ PotentialFileReader::PotentialFileReader(LAMMPS *lmp,
   }
 }
 
+/** Closes the file */
+
 PotentialFileReader::~PotentialFileReader() {
   delete reader;
 }
 
+/** Set comment (= text after '#') handling preference for the file to be read
+ *
+ * \param   value   Comment text is ignored if true, or not if false */
 void PotentialFileReader::ignore_comments(bool value) {
   reader->ignore_comments = value;
 }
 
+/** Read a line but ignore its content */
+
 void PotentialFileReader::skip_line() {
   try {
     reader->skip_line();
@@ -69,6 +89,17 @@ void PotentialFileReader::skip_line() {
   }
 }
 
+/** Read the next line(s) until *nparams* words have been read.
+ *
+ * This reads a line and counts the words in it, if the number
+ * is less than the requested number, it will read the next
+ * line, as well.  Output will be a string with all read lines
+ * combined.  The purpose is to somewhat replicate the reading
+ * behavior of formatted files in Fortran.
+ *
+ * \param   nparams  Number of words that must be read. Default: 0
+ * \return           String with the concatenated text */
+
 char *PotentialFileReader::next_line(int nparams) {
   try {
     return reader->next_line(nparams);
@@ -78,6 +109,15 @@ char *PotentialFileReader::next_line(int nparams) {
   return nullptr;
 }
 
+/** Read lines until *n* doubles have been read and stored in array *list*
+ *
+ * This reads lines from the file using the next_line() function,
+ * and splits them into floating-point numbers using the
+ * ValueTokenizer class and stores the number is the provided list.
+ *
+ * \param  list  Pointer to array with suitable storage for *n* doubles
+ * \param  n     Number of doubles to be read */
+
 void PotentialFileReader::next_dvector(double * list, int n) {
   try {
     return reader->next_dvector(list, n);
@@ -86,6 +126,16 @@ void PotentialFileReader::next_dvector(double * list, int n) {
   }
 }
 
+/** Read text until *nparams* words are read and passed to a tokenizer object for custom parsing.
+ *
+ * This reads lines from the file using the next_line() function,
+ * and splits them into floating-point numbers using the
+ * ValueTokenizer class and stores the number is the provided list.
+ *
+ * \param   nparams     Number of words to be read
+ * \param   separators  String with list of separators.
+ * \return              ValueTokenizer object for read in text */
+
 ValueTokenizer PotentialFileReader::next_values(int nparams, const std::string & separators) {
   try {
     return reader->next_values(nparams, separators);
@@ -95,6 +145,10 @@ ValueTokenizer PotentialFileReader::next_values(int nparams, const std::string &
   return ValueTokenizer("");
 }
 
+/** Read next line and convert first word to a double
+ *
+ * \return  Value of first word in line as double */
+
 double PotentialFileReader::next_double() {
   try {
     char * line = reader->next_line(1);
@@ -105,6 +159,10 @@ double PotentialFileReader::next_double() {
   return 0.0;
 }
 
+/** Read next line and convert first word to an int
+ *
+ * \return  Value of first word in line as int */
+
 int PotentialFileReader::next_int() {
   try {
     char * line = reader->next_line(1);
@@ -115,6 +173,10 @@ int PotentialFileReader::next_int() {
   return 0;
 }
 
+/** Read next line and convert first word to a tagint
+ *
+ * \return  Value of first word in line as tagint */
+
 tagint PotentialFileReader::next_tagint() {
   try {
     char * line = reader->next_line(1);
@@ -125,6 +187,10 @@ tagint PotentialFileReader::next_tagint() {
   return 0;
 }
 
+/** Read next line and convert first word to a bigint
+ *
+ * \return  Value of first word in line as bigint */
+
 bigint PotentialFileReader::next_bigint() {
   try {
     char * line = reader->next_line(1);
@@ -135,6 +201,10 @@ bigint PotentialFileReader::next_bigint() {
   return 0;
 }
 
+/** Read next line and return first word
+ *
+ * \return  First word of read in line */
+
 std::string PotentialFileReader::next_string() {
   try {
     char * line = reader->next_line(1);
@@ -145,6 +215,12 @@ std::string PotentialFileReader::next_string() {
   return "";
 }
 
+/** Look up and open the potential file
+ *
+ * \param   path  Path of the potential file to open
+ * \return        Pointer to TextFileReader object created
+ * \sa TextFileReader */
+
 TextFileReader *PotentialFileReader::open_potential(const std::string &path) {
   std::string filepath = utils::get_potential_file_path(path);