From 22e88a5b6a0dcb9e5f5e982264a4ebc015754926 Mon Sep 17 00:00:00 2001
From: rdb <git@rdb.name>
Date: Sat, 2 Nov 2019 19:41:11 +0100
Subject: [PATCH 1/5] direct: a few improvements to API documentation

---
 direct/src/fsm/FSM.py                 | 12 +++++-------
 direct/src/gui/DirectButton.py        |  6 +++++-
 direct/src/gui/DirectCheckButton.py   |  6 +++++-
 direct/src/gui/DirectDialog.py        |  6 +++++-
 direct/src/gui/DirectEntry.py         |  6 +++++-
 direct/src/gui/DirectFrame.py         |  3 +++
 direct/src/gui/DirectLabel.py         |  6 +++++-
 direct/src/gui/DirectOptionMenu.py    |  6 +++++-
 direct/src/gui/DirectRadioButton.py   |  6 +++++-
 direct/src/gui/DirectScrollBar.py     |  6 +++++-
 direct/src/gui/DirectScrolledFrame.py |  9 ++++++++-
 direct/src/gui/DirectScrolledList.py  |  6 +++++-
 direct/src/gui/DirectSlider.py        |  6 +++++-
 direct/src/gui/DirectWaitBar.py       |  6 +++++-
 14 files changed, 71 insertions(+), 19 deletions(-)

diff --git a/direct/src/fsm/FSM.py b/direct/src/fsm/FSM.py
index bae5dc094b..eb67f55c0a 100644
--- a/direct/src/fsm/FSM.py
+++ b/direct/src/fsm/FSM.py
@@ -117,7 +117,7 @@ class FSM(DirectObject):
     at construction time; it is simply in Off already by convention.
     If you need to call code in enterOff() to initialize your FSM
     properly, call it explicitly in the constructor.  Similarly, when
-    cleanup() is called or the FSM is destructed, the FSM transitions
+    `cleanup()` is called or the FSM is destructed, the FSM transitions
     back to 'Off' by convention.  (It does call enterOff() at this
     point, but does not call exitOff().)
 
@@ -261,9 +261,9 @@ class FSM(DirectObject):
     def demand(self, request, *args):
         """Requests a state transition, by code that does not expect
         the request to be denied.  If the request is denied, raises a
-        RequestDenied exception.
+        `RequestDenied` exception.
 
-        Unlike request(), this method allows a new request to be made
+        Unlike `request()`, this method allows a new request to be made
         while the FSM is currently in transition.  In this case, the
         request is queued up and will be executed when the current
         transition finishes.  Multiple requests will queue up in
@@ -290,7 +290,7 @@ class FSM(DirectObject):
         """Requests a state transition (or other behavior).  The
         request may be denied by the FSM's filter function.  If it is
         denied, the filter function may either raise an exception
-        (RequestDenied), or it may simply return None, without
+        (`RequestDenied`), or it may simply return None, without
         changing the FSM's state.
 
         The request parameter should be a string.  The request, along
@@ -305,7 +305,7 @@ class FSM(DirectObject):
 
         If the FSM is currently in transition (i.e. in the middle of
         executing an enterState or exitState function), an
-        AlreadyInTransition exception is raised (but see demand(),
+        `AlreadyInTransition` exception is raised (but see `demand()`,
         which will queue these requests up and apply when the
         transition is complete)."""
 
@@ -401,7 +401,6 @@ class FSM(DirectObject):
             return (request,) + args
         return self.defaultFilter(request, args)
 
-
     def setStateArray(self, stateArray):
         """array of unique states to iterate through"""
         self.fsmLock.acquire()
@@ -410,7 +409,6 @@ class FSM(DirectObject):
         finally:
             self.fsmLock.release()
 
-
     def requestNext(self, *args):
         """Request the 'next' state in the predefined state array."""
         self.fsmLock.acquire()
diff --git a/direct/src/gui/DirectButton.py b/direct/src/gui/DirectButton.py
index e6111af710..5cf8a91e9e 100644
--- a/direct/src/gui/DirectButton.py
+++ b/direct/src/gui/DirectButton.py
@@ -1,4 +1,8 @@
-"""This module contains the DirectButton class."""
+"""This module contains the DirectButton class.
+
+See the :ref:`directbutton` page in the programming manual for a more
+in-depth explanation and an example of how to use this class.
+"""
 
 __all__ = ['DirectButton']
 
diff --git a/direct/src/gui/DirectCheckButton.py b/direct/src/gui/DirectCheckButton.py
index f353f3d989..ed74c3eef7 100644
--- a/direct/src/gui/DirectCheckButton.py
+++ b/direct/src/gui/DirectCheckButton.py
@@ -1,6 +1,10 @@
 """A DirectCheckButton is a type of button that toggles between two states
 when clicked.  It also has a separate indicator that can be modified
-separately."""
+separately.
+
+See the :ref:`directcheckbutton` page in the programming manual for a more
+in-depth explanation and an example of how to use this class.
+"""
 
 __all__ = ['DirectCheckButton']
 
diff --git a/direct/src/gui/DirectDialog.py b/direct/src/gui/DirectDialog.py
index 8dd4bc51af..b6401c7a7a 100644
--- a/direct/src/gui/DirectDialog.py
+++ b/direct/src/gui/DirectDialog.py
@@ -1,4 +1,8 @@
-"""This module defines various dialog windows for the DirectGUI system."""
+"""This module defines various dialog windows for the DirectGUI system.
+
+See the :ref:`directdialog` page in the programming manual for a more
+in-depth explanation and an example of how to use this class.
+"""
 
 __all__ = [
     'findDialog', 'cleanupDialog', 'DirectDialog', 'OkDialog',
diff --git a/direct/src/gui/DirectEntry.py b/direct/src/gui/DirectEntry.py
index d614a3825a..d870bf0c7e 100644
--- a/direct/src/gui/DirectEntry.py
+++ b/direct/src/gui/DirectEntry.py
@@ -1,5 +1,9 @@
 """Contains the DirectEntry class, a type of DirectGUI widget that accepts
-text entered using the keyboard."""
+text entered using the keyboard.
+
+See the :ref:`directentry` page in the programming manual for a more in-depth
+explanation and an example of how to use this class.
+"""
 
 __all__ = ['DirectEntry']
 
diff --git a/direct/src/gui/DirectFrame.py b/direct/src/gui/DirectFrame.py
index 684fda005c..19e8717ba6 100644
--- a/direct/src/gui/DirectFrame.py
+++ b/direct/src/gui/DirectFrame.py
@@ -11,6 +11,9 @@ A DirectFrame can have:
 Each of these has 1 or more states.  The same object can be used for
 all states or each state can have a different text/geom/image (for
 radio button and check button indicators, for example).
+
+See the :ref:`directframe` page in the programming manual for a more in-depth
+explanation and an example of how to use this class.
 """
 
 __all__ = ['DirectFrame']
diff --git a/direct/src/gui/DirectLabel.py b/direct/src/gui/DirectLabel.py
index bc1328ded7..aa965bbe61 100644
--- a/direct/src/gui/DirectLabel.py
+++ b/direct/src/gui/DirectLabel.py
@@ -1,4 +1,8 @@
-"""Contains the DirectLabel class."""
+"""Contains the DirectLabel class.
+
+See the :ref:`directlabel` page in the programming manual for a more in-depth
+explanation and an example of how to use this class.
+"""
 
 __all__ = ['DirectLabel']
 
diff --git a/direct/src/gui/DirectOptionMenu.py b/direct/src/gui/DirectOptionMenu.py
index cbf3a2974e..818cc3f896 100644
--- a/direct/src/gui/DirectOptionMenu.py
+++ b/direct/src/gui/DirectOptionMenu.py
@@ -1,4 +1,8 @@
-"""Implements a pop-up menu containing multiple clickable options."""
+"""Implements a pop-up menu containing multiple clickable options.
+
+See the :ref:`directoptionmenu` page in the programming manual for a more
+in-depth explanation and an example of how to use this class.
+"""
 
 __all__ = ['DirectOptionMenu']
 
diff --git a/direct/src/gui/DirectRadioButton.py b/direct/src/gui/DirectRadioButton.py
index f6543d1e8f..c679eff334 100755
--- a/direct/src/gui/DirectRadioButton.py
+++ b/direct/src/gui/DirectRadioButton.py
@@ -1,7 +1,11 @@
 """A DirectRadioButton is a type of button that, similar to a
 DirectCheckButton, has a separate indicator and can be toggled between
 two states.  However, only one DirectRadioButton in a group can be enabled
-at a particular time."""
+at a particular time.
+
+See the :ref:`directradiobutton` page in the programming manual for a more
+in-depth explanation and an example of how to use this class.
+"""
 
 __all__ = ['DirectRadioButton']
 
diff --git a/direct/src/gui/DirectScrollBar.py b/direct/src/gui/DirectScrollBar.py
index d56385163b..a873924456 100644
--- a/direct/src/gui/DirectScrollBar.py
+++ b/direct/src/gui/DirectScrollBar.py
@@ -1,4 +1,8 @@
-"""Defines the DirectScrollBar class."""
+"""Defines the DirectScrollBar class.
+
+See the :ref:`directscrollbar` page in the programming manual for a more
+in-depth explanation and an example of how to use this class.
+"""
 
 __all__ = ['DirectScrollBar']
 
diff --git a/direct/src/gui/DirectScrolledFrame.py b/direct/src/gui/DirectScrolledFrame.py
index 2c60ed950f..7b30ba499e 100644
--- a/direct/src/gui/DirectScrolledFrame.py
+++ b/direct/src/gui/DirectScrolledFrame.py
@@ -1,4 +1,8 @@
-"""Contains the DirectScrolledFrame class."""
+"""Contains the DirectScrolledFrame class.
+
+See the :ref:`directscrolledframe` page in the programming manual for a more
+in-depth explanation and an example of how to use this class.
+"""
 
 __all__ = ['DirectScrolledFrame']
 
@@ -82,6 +86,9 @@ class DirectScrolledFrame(DirectFrame):
         self.guiItem.setVirtualFrame(f[0], f[1], f[2], f[3])
 
     def getCanvas(self):
+        """Returns the NodePath of the virtual canvas.  Nodes parented to this
+        canvas will show inside the scrolled area.
+        """
         return self.canvas
 
     def setManageScrollBars(self):
diff --git a/direct/src/gui/DirectScrolledList.py b/direct/src/gui/DirectScrolledList.py
index ca7551d2c9..5bade6caf9 100644
--- a/direct/src/gui/DirectScrolledList.py
+++ b/direct/src/gui/DirectScrolledList.py
@@ -1,4 +1,8 @@
-"""Contains the DirectScrolledList class."""
+"""Contains the DirectScrolledList class.
+
+See the :ref:`directscrolledlist` page in the programming manual for a more
+in-depth explanation and an example of how to use this class.
+"""
 
 __all__ = ['DirectScrolledListItem', 'DirectScrolledList']
 
diff --git a/direct/src/gui/DirectSlider.py b/direct/src/gui/DirectSlider.py
index 507c13b5a8..ddcd35d05d 100644
--- a/direct/src/gui/DirectSlider.py
+++ b/direct/src/gui/DirectSlider.py
@@ -1,4 +1,8 @@
-"""Defines the DirectSlider class."""
+"""Defines the DirectSlider class.
+
+See the :ref:`directslider` page in the programming manual for a more
+in-depth explanation and an example of how to use this class.
+"""
 
 __all__ = ['DirectSlider']
 
diff --git a/direct/src/gui/DirectWaitBar.py b/direct/src/gui/DirectWaitBar.py
index ff3f554fee..55785152cf 100644
--- a/direct/src/gui/DirectWaitBar.py
+++ b/direct/src/gui/DirectWaitBar.py
@@ -1,4 +1,8 @@
-"""Contains the DirectWaitBar class, a progress bar widget."""
+"""Contains the DirectWaitBar class, a progress bar widget.
+
+See the :ref:`directwaitbar` page in the programming manual for a more
+in-depth explanation and an example of how to use this class.
+"""
 
 __all__ = ['DirectWaitBar']
 

From 39988e4787f707a787b767c96c92e4f6e607f427 Mon Sep 17 00:00:00 2001
From: rdb <git@rdb.name>
Date: Sat, 2 Nov 2019 19:41:56 +0100
Subject: [PATCH 2/5] general: update a few outdated links in API documentation

---
 direct/src/showbase/PythonUtil.py | 2 +-
 panda/src/downloader/httpClient.I | 2 +-
 panda/src/grutil/geoMipTerrain.h  | 2 +-
 panda/src/mathutil/perlinNoise2.h | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/direct/src/showbase/PythonUtil.py b/direct/src/showbase/PythonUtil.py
index 7af79603b3..4c9afa634b 100644
--- a/direct/src/showbase/PythonUtil.py
+++ b/direct/src/showbase/PythonUtil.py
@@ -1172,7 +1172,7 @@ def normalDistrib(a, b, gauss=random.gauss):
     uniformly onto the curve inside [a, b]
 
     ------------------------------------------------------------------------
-    http://www-stat.stanford.edu/~naras/jsm/NormalDensity/NormalDensity.html
+    https://statweb.stanford.edu/~naras/jsm/NormalDensity/NormalDensity.html
 
     The 68-95-99.7% Rule
     ====================
diff --git a/panda/src/downloader/httpClient.I b/panda/src/downloader/httpClient.I
index 33b9432f3d..419083309c 100644
--- a/panda/src/downloader/httpClient.I
+++ b/panda/src/downloader/httpClient.I
@@ -111,7 +111,7 @@ get_verify_ssl() const {
  * Specifies the set of ciphers that are to be made available for SSL
  * connections.  This is a string as described in the ciphers(1) man page of
  * the OpenSSL documentation (or see
- * http://www.openssl.org/docs/apps/ciphers.html ).  If this is not specified,
+ * https://www.openssl.org/docs/apps/ciphers.html ).  If this isn't specified,
  * the default is provided by the Config file.  You may also specify "DEFAULT"
  * to use the built-in OpenSSL default value.
  */
diff --git a/panda/src/grutil/geoMipTerrain.h b/panda/src/grutil/geoMipTerrain.h
index 0d0ce94da0..1075e865de 100644
--- a/panda/src/grutil/geoMipTerrain.h
+++ b/panda/src/grutil/geoMipTerrain.h
@@ -31,7 +31,7 @@
  * GeoMipMapping algorithm, or Geometrical MipMapping, based on the LOD (Level
  * of Detail) algorithm.  For more information about the GeoMipMapping
  * algoritm, see this paper, written by Willem H. de Boer:
- * http://flipcode.com/articles/article_geomipmaps.pdf
+ * https://flipcode.com/articles/article_geomipmaps.pdf
  */
 class EXPCL_PANDA_GRUTIL GeoMipTerrain : public TypedObject {
 PUBLISHED:
diff --git a/panda/src/mathutil/perlinNoise2.h b/panda/src/mathutil/perlinNoise2.h
index d10555e38b..33e46c7b4e 100644
--- a/panda/src/mathutil/perlinNoise2.h
+++ b/panda/src/mathutil/perlinNoise2.h
@@ -20,7 +20,7 @@
 /**
  * This class provides an implementation of Perlin noise for 2 variables.
  * This code is loosely based on the reference implementation at
- * http://mrl.nyu.edu/~perlin/noise/ .
+ * https://mrl.nyu.edu/~perlin/noise/ .
  */
 class EXPCL_PANDA_MATHUTIL PerlinNoise2 : public PerlinNoise {
 PUBLISHED:

From c52db7239bd9baef3c11ac2624be07078b395786 Mon Sep 17 00:00:00 2001
From: rdb <git@rdb.name>
Date: Sat, 2 Nov 2019 19:51:16 +0100
Subject: [PATCH 3/5] makepanda: fix unnecessary re-copy of unmodified direct
 files

---
 makepanda/makepandacore.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/makepanda/makepandacore.py b/makepanda/makepandacore.py
index b45dc511c0..0ba33518e8 100644
--- a/makepanda/makepandacore.py
+++ b/makepanda/makepandacore.py
@@ -3165,7 +3165,7 @@ def CopyPythonTree(dstdir, srcdir, lib2to3_fixers=[], threads=0):
                 if (NeedsBuild([dstpth], [srcpth])):
                     WriteBinaryFile(dstpth, ReadBinaryFile(srcpth))
 
-                    if ext == '.py' and not entry.endswith('-extensions.py'):
+                    if ext == '.py' and not entry.endswith('-extensions.py') and lib2to3 is not None:
                         refactor.append((dstpth, srcpth))
                         lib2to3_args.append(dstpth)
                     else:

From 3bfd994cf81332dcbdd5624d8227e0001a3400d6 Mon Sep 17 00:00:00 2001
From: rdb <git@rdb.name>
Date: Sat, 2 Nov 2019 19:54:15 +0100
Subject: [PATCH 4/5] general: Fix a couple of misformatted docstrings.

---
 panda/src/audio/audioSound.h | 28 ++++++++++++++++-----------
 panda/src/putil/bamEnums.h   | 37 ++++++++++++++++++++----------------
 2 files changed, 38 insertions(+), 27 deletions(-)

diff --git a/panda/src/audio/audioSound.h b/panda/src/audio/audioSound.h
index e348ad4daf..486b0504f3 100644
--- a/panda/src/audio/audioSound.h
+++ b/panda/src/audio/audioSound.h
@@ -42,17 +42,23 @@ PUBLISHED:
   virtual void set_loop_count(unsigned long loop_count=1) = 0;
   virtual unsigned long get_loop_count() const = 0;
 
-/*
- * Control time position within the sound.  This is similar (in concept) to
- * the seek position within a file.  time in seconds: 0 = beginning; length()
- * = end.  inits to 0.0. - The current time position will not change while the
- * sound is playing; you must call play() again to effect the change.  To play
- * the same sound from a time offset a second time, explicitly set the time
- * position again.  When looping, the second and later loops will start from
- * the beginning of the sound.  - If a sound is playing, calling get_time()
- * repeatedly will return different results over time.  e.g.: PN_stdfloat
- * percent_complete = s.get_time()  s.length();
- */
+  /**
+   * Control time position within the sound, in seconds.  This is similar (in
+   * concept) to the seek position within a file.  The value starts at 0.0 (the
+   * default) and ends at the value given by the length() method.
+   *
+   * The current time position will not change while the sound is playing; you
+   * must call play() again to effect the change.  To play the same sound from
+   * a time offset a second time, explicitly set the time position again.  When
+   * looping, the second and later loops will start from the beginning of the
+   * sound.
+   *
+   * If a sound is playing, calling get_time() repeatedly will return different
+   * results over time.  e.g.
+   * @code
+   * PN_stdfloat percent_complete = s.get_time() / s.length();
+   * @endcode
+   */
   virtual void set_time(PN_stdfloat start_time=0.0) = 0;
   virtual PN_stdfloat get_time() const = 0;
 
diff --git a/panda/src/putil/bamEnums.h b/panda/src/putil/bamEnums.h
index 1f5b481c9a..ec395148de 100644
--- a/panda/src/putil/bamEnums.h
+++ b/panda/src/putil/bamEnums.h
@@ -22,12 +22,13 @@
  */
 class EXPCL_PANDA_PUTIL BamEnums {
 PUBLISHED:
-
-  // This defines an enumerated type used to represent the endianness of
-  // certain numeric values stored in a Bam file.  It really has only two
-  // possible values, either BE_bigendian or BE_littleendian; but through a
-  // preprocessor trick we also add BE_native, which is the same numerically
-  // as whichever value the hardware supports natively.
+  /**
+   * This defines an enumerated type used to represent the endianness of
+   * certain numeric values stored in a Bam file.  It really has only two
+   * possible values, either BE_bigendian or BE_littleendian; but through a
+   * preprocessor trick we also add BE_native, which is the same numerically
+   * as whichever value the hardware supports natively.
+   */
   enum BamEndian {
     BE_bigendian = 0,
     BE_littleendian = 1,
@@ -38,21 +39,25 @@ PUBLISHED:
 #endif
   };
 
-/*
- * This is the code written along with each object.  It is used to control
- * object scoping.  A BOC_push includes an object definition, and will always
- * be eventually paired with a BOC_pop (which does not).  A BOC_adjunct
- * includes an object definition but does not push the level; it is associated
- * with the current level.  BOC_remove lists object ID's that have been
- * deallocated on the sender end.  BOC_file_data may appear at any level and
- * indicates the following datagram contains auxiliary file data that may be
- * referenced by a later object.
- */
+  /**
+   * This is the code written along with each object.  It is used to control
+   * object scoping.
+   */
   enum BamObjectCode {
+    // Indicates an object definition, and will always be eventually paired
+    // with a BOC_pop (which does not).
     BOC_push,
     BOC_pop,
+
+    // Includes an object definition but does not push the level; it is
+    // associated with the current level.
     BOC_adjunct,
+
+    // Lists object IDs that have been deallocated on the sender end.
     BOC_remove,
+
+    // May appear at any level and indicates the following datagram contains
+    // auxiliary file data that may be referenced by a later object.
     BOC_file_data,
   };
 

From c611abc6c21464b6d67bdd5f1641c95495793798 Mon Sep 17 00:00:00 2001
From: rdb <git@rdb.name>
Date: Sat, 2 Nov 2019 20:39:29 +0100
Subject: [PATCH 5/5] physx: fix a pair of misformatted docstrings

---
 panda/src/physx/physxContactPair.cxx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/panda/src/physx/physxContactPair.cxx b/panda/src/physx/physxContactPair.cxx
index fdaf22889c..9374709418 100644
--- a/panda/src/physx/physxContactPair.cxx
+++ b/panda/src/physx/physxContactPair.cxx
@@ -73,8 +73,8 @@ is_deleted_b() const {
  * You should set the ContactPairFlag CPF_notify_forces in order to receive
  * this value.
  *
- * @see PhysxScene::set_actor_pair_flag @see
- * PhysxScene::set_actor_group_pair_flag
+ * @see PhysxScene::set_actor_pair_flag
+ * @see PhysxScene::set_actor_group_pair_flag
  */
 LVector3f PhysxContactPair::
 get_sum_normal_force() const {
@@ -88,8 +88,8 @@ get_sum_normal_force() const {
  * You should set the ContactPairFlag CPF_notify_forces in order to receive
  * this value.
  *
- * @see PhysxScene::set_actor_pair_flag @see
- * PhysxScene::set_actor_group_pair_flag
+ * @see PhysxScene::set_actor_pair_flag
+ * @see PhysxScene::set_actor_group_pair_flag
  */
 LVector3f PhysxContactPair::
 get_sum_friction_force() const {