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] 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,
   };