From d4ed957cb6562938a434d268f062238647f9f9fb Mon Sep 17 00:00:00 2001
From: William Deegan <bill@baddogconsulting.com>
Date: Mon, 15 Aug 2022 21:13:04 -0700
Subject: Address doc and docstring feedback from mwichmann

---
 SCons/Script/Main.py  | 10 +++++++++-
 SCons/Script/Main.xml | 16 ++++++++++------
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/SCons/Script/Main.py b/SCons/Script/Main.py
index 3516e90..442ee56 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 ace1799..efec64f 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)
-- 
cgit v0.12