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: