Add Doxygen comments to the C++ API

[darbyjohnston]

Required:

---

[ ] I believe this isn't a duplicate topic
[x ] This report is not related to an adapter

Select One:

[ ] Build problem
[ ] Incorrect Functionality or bug
[x ] New feature or functionality

Description

As a follow up to #708, this issue covers adding Doxygen style comments to the C++ API. Specifically:

• All public C++ API should be documented (e.g., classes, structs, enumerations, member functions, etc.)
• C++ style comments are used:

  /// @brief Returns the time value converted to a new rate.
  constexpr double value_rescaled_to(double new_rate) const noexcept;

• Comments should always have an explicit brief section; detailed descriptions, parameter strings, and return strings are optional for shorter functions:

  /// @brief Returns the time value converted to a new rate.
  constexpr double value_rescaled_to(double new_rate) const noexcept;

  /// @brief Parse a string in the form "hours:minutes:seconds".
  ///
  /// The string may have a leading negative sign. Seconds may have up to microsecond precision.
  ///
  /// @param time_string The time string.
  /// @param rate The time rate.
  /// @param error_status Optional error status.
  static RationalTime from_timecode(
      std::string const& timecode,
      double rate,
      ErrorStatus* error_status = nullptr);

• Given the amount of work involved, it should probably be broken into multiple PRs.

Example of the Doxygen HTML documentation:

Example Doxygen tooltip in Visual Studio:

Example Doxygen tooltip in Xcode: