Address doc and docstring feedback from mwichmannadd_api_to_check_for_invalid_options_issue_4187

2 files changed, 19 insertions, 7 deletions

diff --git a/SCons/Script/Main.py b/SCons/Script/Main.py
index 3516e90c8..442ee56e2 100644
--- a/SCons/Script/Main.py
+++ b/SCons/Script/Main.py
@@ -494,11 +494,19 @@ def SetOption(name, value):
 
 
 def ValidateOptions(throw_exception=False):
-    """
+    """Validate options passed to SCons on the command line.
+
     If you call this after you set all your command line options with AddOption(),
     it will verify that all command line options are valid.
     So if you added an option --xyz and you call SCons with --xyy you can cause
     SCons to issue an error message and exit by calling this function.
+
+    args:
+        throw_exception (bool): Should this function raise an error if there's an
+                                invalid option, or issue a message and exit with error status.
+
+    Raises:
+            SConsBadOptionError
     """
 
     OptionsParser.raise_exception_on_error = throw_exception
diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml
index ace17991c..efec64f37 100644
--- a/SCons/Script/Main.xml
+++ b/SCons/Script/Main.xml
@@ -956,12 +956,7 @@ SetOption('max_drift', 0)
         <summary>
             <para>
                 Check that all the options specified on the command line are either defined by SCons itself
-                or defined by &f-link-AddOption;.
-            </para>
-            <para>
-                If <parameter>throw_exception</parameter> is True, &f-ValidateOptions; will raise a
-                <literal>SConsBadOptionError</literal>
-                exception instead of printing an error message and exiting with an error status.
+                or defined by calls to &f-link-AddOption;.
             </para>
             <para>
                 If there are any command line options not defined.
@@ -969,6 +964,13 @@ SetOption('max_drift', 0)
                 status.
             </para>
             <para>
+                If optional <parameter>throw_exception</parameter> is True, &f-ValidateOptions; will raise a
+                <exceptionname>SConsBadOptionError</exceptionname>
+                exception instead of printing an error message and exiting with an error status.  Then the calling
+                &SConscript; logic can catch that exception and handle invalid options itself.
+            </para>
+
+            <para>
                 This function should only be called after the last &f-link-AddOption; call in your &SConscript;
                 logic.
             </para>
@@ -982,6 +984,8 @@ SetOption('max_drift', 0)
             </para>
 
 <example_commands>
+try:
+    ValidateOptions(throw_exception=True)
 except SConsBadOptionError as e:
     print("Parser is SConsOptionParser:%s" % (isinstance(e.parser, SConsOptionParser)))
     print("Message is :%s" % e.opt_str)