add some documentation for the programmer guide and doxygen decorations

doc/doxygen/Doxyfile.in

@@ -424,6 +424,8 @@ INPUT                  = @LAMMPS_SOURCE_DIR@/utils.cpp                 \
                          @LAMMPS_SOURCE_DIR@/input.h                   \
                          @LAMMPS_SOURCE_DIR@/tokenizer.cpp             \
                          @LAMMPS_SOURCE_DIR@/tokenizer.h               \
+                         @LAMMPS_SOURCE_DIR@/arg_info.cpp              \
+                         @LAMMPS_SOURCE_DIR@/arg_info.h                \
                          @LAMMPS_SOURCE_DIR@/text_file_reader.cpp      \
                          @LAMMPS_SOURCE_DIR@/text_file_reader.h        \
                          @LAMMPS_SOURCE_DIR@/potential_file_reader.cpp \

doc/src/Developer_utils.rst

@@ -292,6 +292,50 @@ This code example should produce the following output:
 
 ----------
 
+
+Argument parsing classes
+---------------------------
+
+The purpose of argument parsing classes it to simplify and unify how
+arguments of commands in LAMMPS are parsed and to make abstractions of
+repetitive tasks.
+
+The :cpp:class:`LAMMPS_NS::ArgInfo` class provides an abstraction
+for parsing references to compute or fix styles or variables. These
+would start with a "c\_", "f\_", "v\_" followed by the ID or name of
+than instance and may be postfixed with one or two array indices
+"[<number>]" with numbers > 0.
+
+A typical code segment would look like this:
+
+.. code-block:: C++
+   :caption: Usage example for ArgInfo class
+
+   int nvalues = 0;
+   for (iarg = 0; iarg < nargnew; iarg++) {
+     ArgInfo argi(arg[iarg]);
+
+     which[nvalues] = argi.get_type();
+     argindex[nvalues] = argi.get_index1();
+     ids[nvalues] = argi.copy_name();
+
+     if ((which[nvalues] == ArgInfo::UNKNOWN)
+          || (which[nvalues] == ArgInfo::NONE)
+          || (argi.get_dim() > 1))
+       error->all(FLERR,"Illegal compute XXX command");
+
+     nvalues++;
+   }
+
+----------
+
+.. doxygenclass:: LAMMPS_NS::ArgInfo
+   :project: progguide
+   :members:
+
+
+----------
+
 File reader classes
 -------------------
 

doc/utils/sphinx-config/false_positives.txt

@@ -2478,6 +2478,9 @@ Poresag
 pos
 Poschel
 posix
+postfix
+postfixed
+postfixes
 Postma
 Potapkin
 potin

src/arg_info.cpp

@@ -18,6 +18,17 @@
 
 using namespace LAMMPS_NS;
 
+/** Class for processing references to fixes, computes and variables
+ *
+ * This class provides an abstraction for the repetitive task of
+ * parsing arguments that may contain references to fixes, computes,
+ * or variables. It will identify the name and the index in the first
+ * and second dimension, if present.
+ *
+ *
+ * \param arg      string with possible reference
+ * \param allowed  integer with bitmap of allowed types of references */
+
 ArgInfo::ArgInfo(const std::string &arg, int allowed)
   : type(NONE), dim(0), index1(-1), index2(-1)
 {
@@ -72,6 +83,16 @@ ArgInfo::ArgInfo(const std::string &arg, int allowed)
 
 /* ---------------------------------------------------------------------- */
 
+/*! make copy of the ID of the reference as C-style string
+ *
+ * The ID is copied into a buffer allocated with "new" and thus
+ * must be later deleted with "delete []" to avoid a memory leak.
+ * Because it is a full copy in a newly allocated buffer, the
+ * lifetime of this string extends beyond the the time the ArgInfo
+ * class is in scope.
+ *
+ * \return copy of string as char * */
+
 char *ArgInfo::copy_name()
 {
   char *dest = new char[name.size()+1];

src/arg_info.h

@@ -21,7 +21,8 @@
 namespace LAMMPS_NS {
   class ArgInfo {
   public:
-    enum {
+    /*! constants for argument types */
+    enum ArgTypes {
       ERROR          =-2,
       UNKNOWN        =-1,
       NONE           = 0,
@@ -51,11 +52,52 @@ namespace LAMMPS_NS {
     virtual ~ArgInfo() {}
 
   public:
+    /*! get type of reference
+     *
+     * Return a type constant for the reference. This may be either
+     * COMPUTE, FIX, VARIABLE (if not restricted to a subset of those
+     * by the "allowed" argument of the constructor) or NONE, if it
+     * if not a recognized or allowed reference, or UNKNOWN, in case
+     * some error happened identifying or parsing the values of the indices
+     *
+     * \return  integer with a constant from ArgTypes enumerator */
+
     int  get_type() const { return type; }
+
+    /*! get dimension of reference
+     *
+     * This will return either 0, 1, 2 depending on whether the
+     * reference has no, one or two "[<number>]" postfixes.
+     *
+     * \return  integer with the dimensionality of the reference */
     int  get_dim()  const { return dim; }
+
+    /*! get index of first dimension
+     *
+     * This will return the <number> in the first "[<number>]"
+     * postfix or 0 if there is no postfix.
+     *
+     * \return  integer with index or the postfix or 0 */
     int  get_index1() const { return index1; }
+
+    /*! get index of second dimension
+     *
+     * This will return the <number> in the second "[<number>]"
+     * postfix or -1 if there is no second postfix.
+     *
+     * \return  integer with index of the postfix or -1 */
     int  get_index2() const { return index2; }
+
+    /*! return reference to the ID or name of the reference
+     *
+     * This string is pointing to an internal storage element and
+     * is only valid to use while the ArgInfo class instance is
+     * in scope. If you need a long-lived string make a copy
+     * with copy_name().
+     *
+     * \return  C-style char * string */
     const char *get_name() const { return name.c_str(); }
+    
     char *copy_name();
 
   private: