document Pointers class and LAMMPS_NS namespace

doc/doxygen/Doxyfile.in

@@ -416,6 +416,7 @@ INPUT                  = @LAMMPS_SOURCE_DIR@/utils.cpp                 \
                          @LAMMPS_SOURCE_DIR@/library.h                 \
                          @LAMMPS_SOURCE_DIR@/lammps.cpp                \
                          @LAMMPS_SOURCE_DIR@/lammps.h                  \
+                         @LAMMPS_SOURCE_DIR@/pointers.h                \
                          @LAMMPS_SOURCE_DIR@/lmptype.h                 \
                          @LAMMPS_SOURCE_DIR@/atom.cpp                  \
                          @LAMMPS_SOURCE_DIR@/atom.h                    \

doc/src/pg_lammps.rst

@@ -14,9 +14,20 @@ C-library interface, or the :py:class:`lammps.lammps` class constructor
 of the Python module, or the :f:func:`lammps` constructor of the Fortran
 module.
 
+In order to avoid clashes of function names, all of the core code in
+LAMMPS is placed into the ``LAMMPS_NS`` namespace.  Functions or variables
+outside of that namespace must be "static", i.e.  visible only to the
+scope of the file/object they are defined in.  Code in packages or the
+libraries in the ``lib`` folder may not adhere to this as some of them
+are adapted from legacy code or consist of external libraries with their
+own requirements and policies.
+
 --------------------
 
 .. doxygenclass:: LAMMPS_NS::LAMMPS
    :project: progguide
    :members:
 
+.. doxygenclass:: LAMMPS_NS::Pointers
+   :project: progguide
+

src/pointers.h

@@ -48,6 +48,20 @@ enum ExecutionSpace{Host,Device};
 template <class T> class MyPoolChunk;
 template <class T> class MyPage;
 
+/** \class LAMMPS_NS::Pointers
+ * \brief Base class for LAMMPS features
+ *
+ * The Pointers class contains references to many of the pointers
+ * and members of the LAMMPS_NS::LAMMPS class. Derived classes thus
+ * gain access to the constituent class instances in the LAMMPS
+ * composite class and thus to the core functionality of LAMMPS.
+ *
+ * This kind of construct is needed, since the LAMMPS constructor
+ * should only be run once per LAMMPS instance and thus classes
+ * cannot be derived from LAMMPS itself. The Pointers class
+ * constructor instead only initializes the references to the
+ * LAMMPS class members it provides access to. */
+
 class Pointers {
  public:
   Pointers(LAMMPS *ptr) :