Fix incorrect docstring, resolve #506.

changelog.txt

@@ -26,6 +26,11 @@ Deprecated
 
  - ``doc_filter`` arguments, which are replaced by namespaced filters. Due to their long history, ``doc_filter`` arguments will still be accepted in signac 2.0 and will only be removed in 3.0.
 
+Fixed
++++++
+
+ - Corrected docstrings for ``Job.update_statepoint`` and ``Project.update_statepoint`` (#506, #563).
+
 
 [1.6.0] -- 2020-01-24
 ---------------------

signac/contrib/job.py

@@ -410,25 +410,25 @@ def update_statepoint(self, update, overwrite=False):
 
         .. warning::
 
-            While appending to a job's state point is generally safe,
-            modifying existing parameters may lead to data
-            inconsistency. Use the overwrite argument with caution!
+            While appending to a job's state point is generally safe, modifying
+            existing parameters may lead to data inconsistency. Use the
+            ``overwrite`` argument with caution!
 
         Parameters
         ----------
         update : dict
             A mapping used for the state point update.
         overwrite : bool, optional
-            If True, this method will set all existing and new parameters
-            to a job's statepoint, making it equivalent to
-            :meth:`~.reset_statepoint`. Use with caution!
-            (Default value = False).
+            If False, an error will be raised if the update modifies the values
+            of existing keys in the state point. If True, any existing keys will
+            be overwritten in the same way as :meth:`dict.update`. Use with
+            caution! (Default value = False).
 
         Raises
         ------
         KeyError
-            If the update contains keys, which are already part of the job's
-            state point and overwrite is False.
+            If the update contains keys which are already part of the job's
+            state point and ``overwrite`` is False.
         :class:`~signac.errors.DestinationExistsError`
             If a job associated with the new state point is already initialized.
         OSError

signac/contrib/project.py

@@ -1545,9 +1545,9 @@ def update_statepoint(self, job, update, overwrite=False):
 
         .. warning::
 
-            While appending to a job's state point is generally safe,
-            modifying existing parameters may lead to data
-            inconsistency. Use the overwrite argument with caution!
+            While appending to a job's state point is generally safe, modifying
+            existing parameters may lead to data inconsistency. Use the
+            ``overwrite`` argument with caution!
 
         Parameters
         ----------
@@ -1556,16 +1556,16 @@ def update_statepoint(self, job, update, overwrite=False):
         update : mapping
             A mapping used for the state point update.
         overwrite : bool, optional
-            If True, this method will set all existing and new parameters
-            to a job's statepoint, making it equivalent to
-            :meth:`~.reset_statepoint`. Use with caution!
-            (Default value = False).
+            If False, an error will be raised if the update modifies the values
+            of existing keys in the state point. If True, any existing keys will
+            be overwritten in the same way as :meth:`dict.update`. Use with
+            caution! (Default value = False).
 
         Raises
         ------
         KeyError
-            If the update contains keys, which are already part of the job's
-            state point and overwrite is False.
+            If the update contains keys which are already part of the job's
+            state point and ``overwrite`` is False.
         :class:`~signac.errors.DestinationExistsError`
             If a job associated with the new state point is already initialized.
         OSError