add some cross referencing

src/atom.cpp

@@ -2502,6 +2502,9 @@ length of the data area, and a short description.
      - 1
      - 1 if the particle is a body particle, 0 if not
 
+*See also*
+   :cpp:func:`lammps_extract_atom`
+
 \endverbatim
  *
  * \param  name  string with the keyword of the desired property.

src/library.cpp

@@ -142,6 +142,9 @@ fails a null pointer is returned.
    ``#include "library.h"``.  In that case, you must use the
    :cpp:func:`lammps_open_no_mpi` function.
 
+*See also*
+   :cpp:func:`lammps_open_no_mpi`, :cpp:func:`lammps_open_fortran`
+
 \endverbatim
  *
  * \param  argc  number of command line arguments
@@ -206,6 +209,9 @@ fails a null pointer is returned.
    It should be set to ``NULL`` instead.
 
 
+*See also*
+   :cpp:func:`lammps_open`, :cpp:func:`lammps_open_fortran`
+
 \endverbatim
  *
  * \param  argc  number of command line arguments
@@ -237,6 +243,9 @@ fails a null pointer is returned.
 
 .. versionadded:: 18Sep2020
 
+*See also*
+   :cpp:func:`lammps_open_fortran`, :cpp:func:`lammps_open_no_mpi`
+
 \endverbatim
  *
  * \param  argc   number of command line arguments
@@ -602,8 +611,10 @@ If LAMMPS was compiled with MPI_STUBS, this function returns -1.
 
 .. versionadded:: 18Sep2020
 
+*See also*
+   :cpp:func:`lammps_open_fortran`
+
 \endverbatim
- * \sa lammps_open_fortran
  *
  * \param  handle  pointer to a previously created LAMMPS instance
  * \return         Fortran representation of the LAMMPS world communicator */
@@ -638,6 +649,13 @@ size and dereference it.  The size of that integer (in bytes) can be
 queried by calling :cpp:func:`lammps_extract_setting` to return
 the size of a ``bigint`` integer.
 
+.. versionchanged:: 18Sep2020
+
+   The type of the return value was changed from ``int`` to ``double``
+   to accommodate reporting atom counts for larger systems that would
+   overflow a 32-bit int without having to depend on a 64-bit bit
+   integer type definition.
+
 \endverbatim
  *
  * \param  handle  pointer to a previously created LAMMPS instance
@@ -661,7 +679,7 @@ double lammps_get_natoms(void *handle)
 This function returns the current value of a :doc:`thermo keyword
 <thermo_style>`.  Unlike :cpp:func:`lammps_extract_global` it does not
 give access to the storage of the desired data but returns its value as
-a double, so it can also return information that is computed on-the-fly.
+a ``double``, so it can also return information that is computed on-the-fly.
 
 \endverbatim
  *
@@ -810,7 +828,7 @@ void lammps_reset_box(void *handle, double *boxlo, double *boxhi,
 This function will retrieve or compute global properties. In contrast to
 :cpp:func:`lammps_get_thermo` this function returns an ``int``.  The
 following keywords are currently supported.  If a keyword is not
-recognized, the function returns -1.  Please also see :cpp:func:`lammps_extract_global`.
+recognized, the function returns -1.
 
 .. list-table::
    :header-rows: 1
@@ -854,6 +872,9 @@ recognized, the function returns -1.  Please also see :cpp:func:`lammps_extract_
    * - rmass_flag
      - 1 if the atom style includes per-atom masses, 0 if there are per-type masses. See :doc:`atom_style`.
 
+*See also*
+   :cpp:func:`lammps_extract_global`
+
 \endverbatim
  *
  * \param  handle   pointer to a previously created LAMMPS instance

src/potential_file_reader.cpp

@@ -30,13 +30,17 @@ using namespace LAMMPS_NS;
  * 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.
+\verbatim embed:rst
+
+*See also*
+   :cpp:class:`TextFileReader`
+
+\endverbatim
  *
  * \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 */
+ * \param  auto_convert    Bitmask of supported unit conversions */
 
 PotentialFileReader::PotentialFileReader(LAMMPS *lmp,
                                          const std::string &filename,
@@ -213,9 +217,15 @@ std::string PotentialFileReader::next_string() {
 
 /** Look up and open the potential file
  *
+\verbatim embed:rst
+
+*See also*
+   :cpp:func:`utils::open_potential`,
+   :cpp:class:`TextFileReader`
+
+\endverbatim
  * \param   path  Path of the potential file to open
- * \return        Pointer to TextFileReader object created
- * \sa TextFileReader */
+ * \return        Pointer to TextFileReader object created */
 
 TextFileReader *PotentialFileReader::open_potential(const std::string &path) {
   std::string filepath = utils::get_potential_file_path(path);

src/text_file_reader.cpp

@@ -30,11 +30,15 @@ using namespace LAMMPS_NS;
  * 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.
+\verbatim embed:rst
+
+*See also*
+   :cpp:class:`TextFileReader`
+
+\endverbatim
  *
  * \param  filename  Name of file to be read
- * \param  filetype  Description of file type for error messages
- *
- * \sa PotentialFileReader */
+ * \param  filetype  Description of file type for error messages */
 
 TextFileReader::TextFileReader(const std::string &filename, const std::string &filetype)
   : filename(filename), filetype(filetype), ignore_comments(true)

src/tokenizer.cpp

@@ -37,10 +37,15 @@ TokenizerException::TokenizerException(const std::string & msg, const std::strin
  * This tokenizer will break down a string into sub-strings (i.e words)
  * separated by the given separator characters.
  *
- * \param str         string to be processed
- * \param separators  string with separator characters (default: " \t\r\n\f")
+\verbatim embed:rst
+
+*See also*
+   :cpp:class:`ValueTokenizer`, :cpp:func:`utils::split_words`
+
+\endverbatim
  *
- * \sa ValueTokenizer TokenizerException */
+ * \param str         string to be processed
+ * \param separators  string with separator characters (default: " \t\r\n\f") */
 
 Tokenizer::Tokenizer(const std::string & str, const std::string & separators) :
     text(str), separators(separators), start(0), ntokens(std::string::npos)
@@ -152,10 +157,17 @@ std::vector<std::string> Tokenizer::as_vector() {
 
 /*! Class for reading text with numbers
  *
+\verbatim embed:rst
+
+*See also*
+   :cpp:class:`Tokenizer`
+
+\endverbatim
+ *
  * \param str         String to be processed
  * \param separators  String with separator characters (default: " \t\r\n\f")
  *
- * \sa Tokenizer InvalidIntegerException InvalidFloatException */
+ * \see Tokenizer InvalidIntegerException InvalidFloatException */
 
 ValueTokenizer::ValueTokenizer(const std::string & str, const std::string & separators) : tokens(str, separators) {
 }

src/utils.h

@@ -247,6 +247,13 @@ namespace LAMMPS_NS {
      * command lines and similar text and not for time critical processing.
      * Use a tokenizer class for that.
      *
+\verbatim embed:rst
+
+*See also*
+   :cpp:class:`Tokenizer`, :cpp:class:`ValueTokenizer`
+
+\endverbatim
+     *
      * \param text string that should be split
      * \return STL vector with the words */