From bbf6e9195c7a227c5b1ca99367e9d6c1f5f6ffbc Mon Sep 17 00:00:00 2001
From: "Christopher J. Brody" <chris.brody+brodybits@gmail.com>
Date: Tue, 9 Jan 2024 02:07:54 -0500
Subject: [PATCH] improve some high-level help text & documentation

---
 README.rst         | 12 +++++++++---
 mutmut/__init__.py |  2 +-
 mutmut/__main__.py | 35 ++++++++++++++++++++++++++++++++++-
 3 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/README.rst b/README.rst
index 2bad7e56..5a10faed 100644
--- a/README.rst
+++ b/README.rst
@@ -48,11 +48,17 @@ You can get started with a simple:
 
 This will by default run pytest (or unittest if pytest is unavailable)
 on tests in the "tests" or "test" folder and
-it will try to figure out where the code to mutate lies. Run
+it will try to figure out where the code to mutate lies.
+
+NOTE that mutmut will apply the mutations directly, one at a time;
+it is **highly** recommended to add all changes to source control
+before running.
+
+Enter
 
 .. code-block:: console
 
-    mutmut --help
+    mutmut run --help
 
 for the available flags, to use other runners, etc. The recommended way to use
 mutmut if the defaults aren't working for you is to add a
@@ -96,11 +102,11 @@ grouped by file. You can now look at a specific mutant diff with ``mutmut show 3
 all mutants for a specific file with ``mutmut show path/to/file.py`` or all mutants
 with ``mutmut show all``.
 
-
 You can also write a mutant to disk with ``mutmut apply 3``. You should **REALLY**
 have the file you mutate under source code control and committed before you apply
 a mutant!
 
+To generate a HTML report for a web browser: ``mutmut html``
 
 Whitelisting
 ------------
diff --git a/mutmut/__init__.py b/mutmut/__init__.py
index c4d59fca..66f1cf0f 100644
--- a/mutmut/__init__.py
+++ b/mutmut/__init__.py
@@ -1286,7 +1286,7 @@ def compute_exit_code(
 ) -> int:
     """Compute an exit code for mutmut mutation testing
 
-    The following exit codes are available for mutmut:
+    The following exit codes are available for mutmut (as documented for the CLI run command):
      * 0 if all mutants were killed (OK_KILLED)
      * 1 if a fatal error occurred
      * 2 if one or more mutants survived (BAD_SURVIVED)
diff --git a/mutmut/__main__.py b/mutmut/__main__.py
index 276896c2..89b9ec4a 100644
--- a/mutmut/__main__.py
+++ b/mutmut/__main__.py
@@ -80,6 +80,16 @@ def do_apply(mutation_pk: str, dict_synonyms: List[str], backup: bool):
 def climain():
     """
     Mutation testing system for Python.
+
+    Getting started:
+
+    To run with pytest in test or tests folder: mutmut run
+
+    For more options: mutmut run --help
+
+    To show the results: mutmut results
+
+    To generate HTML report: mutmut html
     """
     pass
 
@@ -128,6 +138,29 @@ def run(argument, paths_to_mutate, disable_mutation_types, enable_mutation_types
         simple_output, no_progress, ci, rerun_all):
     """
     Runs mutmut. You probably want to start with just trying this. If you supply a mutation ID mutmut will check just this mutant.
+
+    Runs pytest by default (or unittest if pytest is unavailable) on tests in the “tests” or “test” folder.
+
+    It is recommended to configure any non-default options needed in setup.cfg or pyproject.toml, as described in the documentation.
+
+    Exit codes:
+
+     * 0 - all mutants were killed
+
+    Otherwise any or sum of any of the following exit codes:
+
+     * 1 - if a fatal error occurred
+
+     * 2 - if one or more mutants survived
+
+     * 4 - if one or more mutants timed out
+
+     * 8 - if one or more mutants caused tests to take twice as long
+
+    (This is equivalent to a bit-OR combination of the exit codes that may apply.)
+
+    With --CI flag enabled, the exit code will always be
+    1 for a fatal error or 0 for any other case.
     """
     if test_time_base is None:  # click sets the default=0.0 to None
         test_time_base = 0.0
@@ -255,7 +288,7 @@ def do_run(
 ) -> int:
     """return exit code, after performing an mutation test run.
 
-    :return: the exit code from executing the mutation tests
+    :return: the exit code from executing the mutation tests for run command
     """
     if use_coverage and use_patch_file:
         raise click.BadArgumentUsage("You can't combine --use-coverage and --use-patch")