Add Doxygen comments to opentime (#1866)

* Add Doxygen comments

Signed-off-by: Darby Johnston <[email protected]>

Author: darbyjohnston

doxygen/config/dox_config

@@ -494,7 +494,7 @@ EXTRACT_ALL            = NO
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = YES
+EXTRACT_PRIVATE        = NO
 
 # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual
 # methods of a class will be included in the documentation.
@@ -520,7 +520,7 @@ EXTRACT_STATIC         = NO
 # for Java sources.
 # The default value is: YES.
 
-EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_CLASSES  = NO
 
 # This flag is only useful for Objective-C code. If set to YES, local methods,
 # which are defined in the implementation section but not in the interface are
@@ -643,7 +643,7 @@ INLINE_INFO            = YES
 # name. If set to NO, the members will appear in declaration order.
 # The default value is: YES.
 
-SORT_MEMBER_DOCS       = YES
+SORT_MEMBER_DOCS       = NO # Keep the same order as the header files
 
 # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
 # descriptions of file, namespace and class members alphabetically by member
@@ -867,7 +867,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../src/opentimelineio/ ../README.md 
+INPUT                  = ../src/opentime ../src/opentimelineio/ ../README.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

src/opentime/errorStatus.h

@@ -8,8 +8,10 @@
 
 namespace opentime { namespace OPENTIME_VERSION {
 
+/// @brief This struct represents the return status of a function.
 struct ErrorStatus
 {
+    /// @brief This enumeration represents the possible outcomes.
     enum Outcome
     {
         OK = 0,
@@ -21,34 +23,41 @@ struct ErrorStatus
         INVALID_RATE_FOR_DROP_FRAME_TIMECODE,
     };
 
+    /// @brief Construct a new status with no error.
     ErrorStatus()
         : outcome{ OK }
     {}
 
+    /// @brief Construct a new status with the given outcome.
     ErrorStatus(Outcome in_outcome)
         : outcome{ in_outcome }
         , details{ outcome_to_string(in_outcome) }
     {}
 
+    /// @brief Construct a new status with the given outcome and details.
     ErrorStatus(Outcome in_outcome, std::string const& in_details)
         : outcome{ in_outcome }
         , details{ in_details }
     {}
 
-    Outcome     outcome;
+    /// @brief The outcome of the function.
+    Outcome outcome;
+
+    /// @brief A human readable string that provides details about the outcome.
     std::string details;
 
+    ///! @brief Return a human readable string for the given outcome.
     static std::string outcome_to_string(Outcome);
 };
 
-// Check whether the given ErrorStatus is an error.
+///! @brief Check whether the given ErrorStatus is an error.
 constexpr bool
 is_error(const ErrorStatus& es) noexcept
 {
     return ErrorStatus::Outcome::OK != es.outcome;
 }
 
-// Check whether the given ErrorStatus is non-null and an error.
+///! @brief Check whether the given ErrorStatus is non-null and an error.
 constexpr bool
 is_error(const ErrorStatus* es) noexcept
 {

src/opentime/rationalTime.h

@@ -93,7 +93,7 @@ class RationalTime
         return value_rescaled_to(rt._rate);
     }
 
-    /// @brief Returns whether time is almost equal to another time.
+    /// @brief Returns whether this time is almost equal to another time.
     ///
     /// @param other The other time for comparison.
     /// @param delta The tolerance used for the comparison.
@@ -103,10 +103,10 @@ class RationalTime
         return fabs(value_rescaled_to(other._rate) - other._value) <= delta;
     }
 
-    /// @brief Returns whether the value and rate are equal to another time.
+    /// @brief Returns whether this value and rate are exactly equal to another time.
     ///
-    /// This is different from the operator "==" that rescales the time before
-    /// comparison.
+    /// Note that this is different from the equality operator that rescales the time
+    /// before comparison.
     constexpr bool strictly_equal(RationalTime other) const noexcept
     {
         return _value == other._value && _rate == other._rate;

src/opentime/stringPrintf.h

@@ -10,6 +10,7 @@
 
 namespace opentime { namespace OPENTIME_VERSION {
 
+/// @brief This provides printf style functionality for std::string.
 template <typename... Args>
 std::string
 string_printf(char const* format, Args... args)