bpo-40561: Add docstrings for webbrowser open functions (GH-19999)

Co-authored-by: Brad Solomon <brsolomon@deloitte.com>
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
(cherry picked from commit ef7973a981ff8f4687ef3fdb85a69fa15aa11fe5)

Co-authored-by: Brad Solomon <brad.solomon.1124@gmail.com>

diff --git a/Lib/webbrowser.py b/Lib/webbrowser.py
index e052e51cdec5aea8acde54bfb421f887cb8bc0cf..34b86a505c2468e26d31f554e9df7b0e51d49c2d 100755 (executable)
--- a/Lib/webbrowser.py
+++ b/Lib/webbrowser.py
@@ -69,6 +69,14 @@ def get(using=None):
 # instead of "from webbrowser import *".
 
 def open(url, new=0, autoraise=True):
+    """Display url using the default browser.
+
+    If possible, open url in a location determined by new.
+    - 0: the same browser window (the default).
+    - 1: a new browser window.
+    - 2: a new browser page ("tab").
+    If possible, autoraise raises the window (the default) or not.
+    """
     if _tryorder is None:
         with _lock:
             if _tryorder is None:
@@ -80,9 +88,17 @@ def open(url, new=0, autoraise=True):
     return False
 
 def open_new(url):
+    """Open url in a new window of the default browser.
+
+    If not possible, then open url in the only browser window.
+    """
     return open(url, 1)
 
 def open_new_tab(url):
+    """Open url in a new page ("tab") of the default browser.
+
+    If not possible, then the behavior becomes equivalent to open_new().
+    """
     return open(url, 2)
 
 

diff --git a/Misc/NEWS.d/next/Documentation/2020-05-08-08-39-40.bpo-40561.ZMB_2i.rst b/Misc/NEWS.d/next/Documentation/2020-05-08-08-39-40.bpo-40561.ZMB_2i.rst
new file mode 100644 (file)
index 0000000..bda2471
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2020-05-08-08-39-40.bpo-40561.ZMB_2i.rst
@@ -0,0 +1 @@
+Provide docstrings for webbrowser open functions.