Apply suggestions from code review

Co-authored-by: Brigitta Sipőcz <[email protected]>

Author: seberg

README.rst

@@ -41,8 +41,8 @@ providing the following features:
 * optional inclusion of ``*.rst`` files for doctests (see `Setup and Configuration`_)
 * optional inclusion of doctests in docstrings of Numpy ufuncs
 
-Further, `pytest-doctestplus` supports editing files to fix incorrect docstrings
-(See `Fixing Existing Docstrings`).
+Further, ``pytest-doctestplus`` supports editing files to fix incorrect docstrings
+(See `Fixing Existing Docstrings`_).
 
 .. _pytest-remotedata: https://github.com/astropy/pytest-remotedata
 
@@ -386,13 +386,13 @@ Without further options, this will print out a diff and a list of files that
 would be modified.  Using ``--doctest-plus-generate-diff=overwrite`` will
 modify the files in-place, so it is recommended to run the check first to
 verify the paths.
-You may wish to use e.g. ``git commit -p`` to review changes manually.
+You may wish to review changes manually and only commit some patches e.g. using ``git commit --patch``.
 
-The current diff generation is not very smart, so it does not account for
+The current diff generation is still very basic, for example, it does not account for
 existing ``...``.  By default a diff is only generated for *failing* doctests.
 
 In general, a mass edit may wish to focus on a specific change and
-possibly include passing tests.  So you can hook into the behavior by
+possibly include passing tests.  So you can opt-in into the behavior by
 adding a hook to your ``conftest.py``::
 
     @pytest.hookimpl

pytest_doctestplus/plugin.py

@@ -125,14 +125,14 @@ def pytest_addoption(parser):
 
     parser.addoption("--doctest-plus-generate-diff",
                      help=(
-                         "Generate a diff for where expected output and real "
+                         "Generate a diff where expected output and actual "
                          "output differ.  "
                          "The diff is printed to stdout if not using "
                          "`--doctest-plus-generate-diff=overwrite` which "
                          "causes editing of the original files.\n"
                          "NOTE: Unless an in-pace build is picked up, python "
                          "file paths may point to unexpected places. "
-                         "If inplace is not used, will create a temporary "
+                         "If `"overwrite"` is not used, will create a temporary "
                          "folder and use `git diff -p` to generate a diff."),
                      choices=["diff", "overwrite"],
                      action="store", nargs="?", default=False, const="diff")
@@ -886,7 +886,7 @@ class DebugRunnerPlus(doctest.DebugRunner):
 
     def __init__(self, checker=None, verbose=None, optionflags=0,
                  continue_on_failure=True, generate_diff=False):
-        # generated_diff is False, "diff", or "inplace" (only need truthiness)
+        # generated_diff is False, "diff", or "overwrite" (only need truthiness)
         DebugRunnerPlus._generate_diff = generate_diff
 
         super().__init__(checker=checker, verbose=verbose, optionflags=optionflags)