update documentation for writing plugins

doc/src/Developer_plugins.rst

@@ -68,24 +68,25 @@ Members of ``lammpsplugin_t``
    * - author
      - String with the name and email of the author
    * - creator.v1
-     - Pointer to factory function for pair, bond, angle, dihedral, improper, kspace, or command styles
+     - Pointer to factory function for pair, bond, angle, dihedral, improper, kspace, command, or minimize styles
    * - creator.v2
-     - Pointer to factory function for compute, fix, or region styles
+     - Pointer to factory function for compute, fix, region, or run styles
    * - handle
      - Pointer to the open DSO file handle
 
 Only one of the two alternate creator entries can be used at a time and
 which of those is determined by the style of plugin. The "creator.v1"
 element is for factory functions of supported styles computing forces
-(i.e. pair, bond, angle, dihedral, or improper styles) or command styles
-and the function takes as single argument the pointer to the LAMMPS
-instance. The factory function is cast to the ``lammpsplugin_factory1``
-type before assignment.  The "creator.v2" element is for factory
-functions creating an instance of a fix, compute, or region style and
-takes three arguments: a pointer to the LAMMPS instance, an integer with
-the length of the argument list and a ``char **`` pointer to the list of
-arguments. The factory function pointer needs to be cast to the
-``lammpsplugin_factory2`` type before assignment.
+(i.e. pair, bond, angle, dihedral, or improper styles), command styles,
+or minimize styles and the function takes as single argument the pointer
+to the LAMMPS instance. The factory function is cast to the
+``lammpsplugin_factory1`` type before assignment.  The "creator.v2"
+element is for factory functions creating an instance of a fix, compute,
+region, or run style and takes three arguments: a pointer to the LAMMPS
+instance, an integer with the length of the argument list and a ``char
+**`` pointer to the list of arguments. The factory function pointer
+needs to be cast to the ``lammpsplugin_factory2`` type before
+assignment.
 
 Pair style example
 ^^^^^^^^^^^^^^^^^^
@@ -247,8 +248,8 @@ DSO handle.  The registration function is called with a pointer to the address
 of this struct and the pointer of the LAMMPS class.  The registration function
 will then add the factory function of the plugin style to the respective
 style map under the provided name.  It will also make a copy of the struct
-in a list of all loaded plugins and update the reference counter for loaded
-plugins from this specific DSO file.
+in a global list of all loaded plugins and update the reference counter for
+loaded plugins from this specific DSO file.
 
 The pair style itself (i.e. the PairMorse2 class in this example) can be
 written just like any other pair style that is included in LAMMPS.  For
@@ -263,6 +264,21 @@ the plugin will override the existing code.  This can be used to modify
 the behavior of existing styles or to debug new versions of them without
 having to re-compile or re-install all of LAMMPS.
 
+.. versionupdated:: 12Jun2025
+
+When using the :doc:`clear <clear>` command, plugins are not unloaded
+but restored to their respective style maps.  This also applies when
+multiple LAMMPS instances are created and deleted through the library
+interface.  The :doc:`plugin load <plugin>` load command may be issued
+again, but for existing plugins they will be skipped.  To replace
+plugins they must be explicitly unloaded with :doc:`plugin unload
+<plugin>`.  When multiple LAMMPS instances are created concurrently, any
+loaded plugins will be added to the global list of plugins, but are not
+immediately available to any LAMMPS instance that was created before
+loading the plugin.  To "import" such plugins, the :doc:`plugin restore
+<plugin>` may be used.  Plugins are only removed when they are explicitly
+unloaded or the LAMMPS interface is "finalized".
+
 Compiling plugins
 ^^^^^^^^^^^^^^^^^
 

doc/src/plugin.rst

@@ -77,7 +77,7 @@ styles and names.
 
 The *clear* command will unload all currently loaded plugins.
 
-.. versionadded:: TBD
+.. versionadded:: 12Jun2025
 
 The *restore* command will restore all currently loaded plugins.
 This allows to "import" plugins into a different LAMMPS instance.