From 89506efd2371dff4d5340747fc92e059a722f14a Mon Sep 17 00:00:00 2001
From: Axel Kohlmeyer <akohlmey@gmail.com>
Date: Sat, 19 Sep 2020 11:16:44 -0400
Subject: [PATCH] document Pointers class and LAMMPS_NS namespace

---
 doc/doxygen/Doxyfile.in |  1 +
 doc/src/pg_lammps.rst   | 11 +++++++++++
 src/pointers.h          | 14 ++++++++++++++
 3 files changed, 26 insertions(+)

diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in
index 22fe2a0b43..f8a5bc6cdb 100644
--- a/doc/doxygen/Doxyfile.in
+++ b/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                    \
diff --git a/doc/src/pg_lammps.rst b/doc/src/pg_lammps.rst
index efa282e33a..dd6798d9a1 100644
--- a/doc/src/pg_lammps.rst
+++ b/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
+
diff --git a/src/pointers.h b/src/pointers.h
index 04f682f045..ad0dfaf6aa 100644
--- a/src/pointers.h
+++ b/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) :