update utils namespace documentation including doxygen parts

doc/src/pg_developer.rst

@@ -741,6 +741,8 @@ files additional settings and functions are needed:
 - the functions ``void pack_restart(int i, double *buf)`` and
   ``void unpack_restart(int nlocal, int nth)`` need to be implemented
 
+---------------------------
+
 LAMMPS utility functions
 ========================
 
@@ -796,11 +798,85 @@ typos or issues when processing input files.
    :project: progguide
 
 
-Convenience functions
+String processing functions
-^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following are functions to help with processing strings
+and parsing files or arguments.
+
+.. doxygenfunction:: trim
+   :project: progguide
+
+.. doxygenfunction:: trim_comment
+   :project: progguide
+
+.. doxygenfunction:: count_words(const char *text)
+   :project: progguide
+
+.. doxygenfunction:: count_words(const std::string &text)
+   :project: progguide
+
+.. doxygenfunction:: count_words(const std::string &text, const std::string &separators)
+   :project: progguide
+
+.. doxygenfunction:: trim_and_count_words
+   :project: progguide
+
+.. doxygenfunction:: split_words
+   :project: progguide
 
 .. doxygenfunction:: strmatch
    :project: progguide
 
+.. doxygenfunction:: is_integer
+   :project: progguide
+
+.. doxygenfunction:: is_double
+   :project: progguide
+
+Filename and path functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: guesspath
+   :project: progguide
+
+.. doxygenfunction:: path_basename
+   :project: progguide
+
+.. doxygenfunction:: path_join
+   :project: progguide
+
+.. doxygenfunction:: file_is_readable
+   :project: progguide
+
+Potential file functions
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: get_potential_file_path
+   :project: progguide
+
+.. doxygenfunction:: get_potential_date
+   :project: progguide
+
+.. doxygenfunction:: get_potential_units
+   :project: progguide
+
+.. doxygenfunction:: get_supported_conversions
+   :project: progguide
+
+.. doxygenfunction:: get_conversion_factor
+   :project: progguide
+
+Convenience functions
+^^^^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: logmesg
+   :project: progguide
+
+.. doxygenfunction:: getsyserror
+   :project: progguide
+
 .. doxygenfunction:: check_packages_for_style
    :project: progguide
+
+.. doxygenfunction:: timespec2seconds
+   :project: progguide

doc/utils/sphinx-config/false_positives.txt

@@ -248,6 +248,7 @@ bispectrum
 Bispectrum
 bitbucket
 bitmapped
+bitmask
 bitrate
 bitrates
 Bitzek
@@ -302,6 +303,7 @@ Bryantsev
 Btarget
 btype
 buckPlusAttr
+buf
 builtin
 Bulatov
 Bureekaew
@@ -370,6 +372,7 @@ charmm
 CHARMM
 charmmfsh
 charmmfsw
+charptr
 Chaudhuri
 checkbox
 checkmark
@@ -845,6 +848,7 @@ Erhart
 erorate
 erose
 erotate
+errno
 Ertas
 ervel
 Espanol
@@ -903,6 +907,7 @@ Fc
 fcc
 fcm
 Fd
+fd
 fdotr
 fdt
 Fehlberg
@@ -927,6 +932,7 @@ ffplay
 fft
 fftbench
 fftw
+fgets
 fhg
 Fi
 Fichthorn
@@ -962,6 +968,7 @@ fmackay
 fmag
 fmass
 fmm
+fmt
 fmx
 fmy
 fmz
@@ -991,6 +998,7 @@ Fraige
 framerate
 Frauenheim
 Fraunhofer
+fread
 Freitas
 Frenkel
 Friedrichs
@@ -2256,6 +2264,8 @@ Particuology
 pastewka
 Pastewka
 pathangle
+pathname
+pathnames
 Patomtrans
 Pattnaik
 Pavese
@@ -2855,8 +2865,12 @@ strcmp
 streitz
 Streitz
 Streiz
+strerror
 strided
 strietz
+strmatch
+strncmp
+strstr
 Stukowski
 Su
 subbox
@@ -2999,6 +3013,7 @@ Tmin
 tmp
 tN
 Tobias
+tokenizer
 tokyo
 tol
 toolchain

src/utils.cpp

@@ -71,7 +71,7 @@ using namespace LAMMPS_NS;
  *  This function is supposed to be a more safe, more specific and
  *  simple to use API to find pattern matches. The purpose is to replace
  *  uses of either strncmp() or strstr() in the code base to find
- *  substrings safely. With strncmp() finding prefixes, the number of
+ *  sub-strings safely. With strncmp() finding prefixes, the number of
  *  characters to match must be counted, which can lead to errors,
  *  while using "^pattern" will do the same with less problems.
  *  Matching for suffixes using strstr() is not as specific as 'pattern$',
@@ -88,7 +88,7 @@ bool utils::strmatch(const std::string &text, const std::string &pattern)
   return (pos >= 0);
 }
 
-/* This simplifies the repetitive task of outputting some
+/** This function simplifies the repetitive task of outputting some
  * message to both the screen and/or the log file. In combination
  * with using fmt::format(), which returns the formatted text
  * in a std::string() instance, this can be used to reduce
@@ -109,9 +109,11 @@ std::string utils::getsyserror()
   return std::string(strerror(errno));
 }
 
-/*
+/** On Linux the folder /proc/self/fd holds symbolic links to the actual
- * On Linux the folder /proc/self/fd holds symbolic links to the actual
  * pathnames associated with each open file descriptor of the current process.
+ *
+ * This function is used to provide a filename with error messages in functions
+ * where the filename is not passed as an argument, but the FILE * pointer.
  */
 const char *utils::guesspath(char *buf, int len, FILE *fp)
 {

src/utils.h

@@ -150,14 +150,14 @@ namespace LAMMPS_NS {
      */
     std::string trim(const std::string &line);
 
-    /** Trim anything from '#' onward
+    /** Return string with anything from '#' onward removed
      *
      * \param line string that should be trimmed
      * \return new string without comment (string)
      */
     std::string trim_comment(const std::string &line);
 
-    /** Count words in string
+    /** Count words in string with custom choice of separating characters
      *
      * \param text string that should be searched
      * \param separators string containing characters that will be treated as whitespace
@@ -189,11 +189,11 @@ namespace LAMMPS_NS {
 
     /** Take text and split into non-whitespace words.
      *
-     * This can handle single and double quotes, escaped quotes,
+     * This can handle strings with single and double quotes, escaped quotes,
-     * and escaped codes within quotes, but due to using an STL
+     * and escaped codes within quotes, but due to using an STL container and
-     * container and STL strings is rather slow because of making
+     * STL strings is rather slow because of making copies. Designed for parsing
-     * copies. Designed for parsing command lines and similar text
+     * command lines and similar text and not for time critical processing.
-     * and not for time critical processing. Use a tokenizer for that.
+     * Use a tokenizer class for that.
      *
      * \param text string that should be split
      * \return STL vector with the words
@@ -220,7 +220,7 @@ namespace LAMMPS_NS {
      *
      *  \param buf  storage buffer for pathname. output will be truncated if not large enough
      *  \param len  size of storage buffer. output will be truncated to this length - 1
-     *  \param fp   FILE pointer structe from STDIO library for which we want to detect the name
+     *  \param fp   FILE pointer struct from STDIO library for which we want to detect the name
      *  \return pointer to the storage buffer, i.e. buf
      */
     const char *guesspath(char *buf, int len, FILE *fp);