Merge pull request #74 from neogeek/feature/updated-comments

[feat] Added and updated method comments.

Author: neogeek

include/RhythmGameUtilities/Audio.hpp

@@ -13,6 +13,16 @@ namespace RhythmGameUtilities
 
 extern "C"
 {
+    /**
+     * Converts samples from an audio file into data used to display a waveform.
+     *
+     * @param samples Array of sample data from an audio file.
+     * @param size Length of the array.
+     * @param width Width of the waveform.
+     * @param height Height of the waveform.
+     * @public
+     */
+
     PACKAGE_API int **ConvertSamplesToWaveform(float *samples, int size,
                                                int width, int height)
     {
@@ -57,14 +67,23 @@ extern "C"
         return waveform;
     }
 
+    /**
+     * Free data returned from the ConvertSamplesToWaveform function.
+     *
+     * @param waveform Waveform multidimensional array.
+     * @param width Width of the waveform.
+     * @public
+     */
+
     PACKAGE_API void FreeWaveform(int **waveform, int width)
     {
         if (waveform != nullptr)
         {
-            for (int x = 0; x < width; x++)
+            for (int x = 0; x < width; x += 1)
             {
                 delete[] waveform[x];
             }
+
             delete[] waveform;
         }
     }

include/RhythmGameUtilities/Common.hpp

@@ -15,22 +15,55 @@ namespace RhythmGameUtilities
 
 extern "C"
 {
+    /**
+     * Calculates the linear interpolation between two values.
+     *
+     * @param a The start value.
+     * @param b The end value.
+     * @param t The value used for interpolation.
+     * @public
+     */
 
     PACKAGE_API float Lerp(float a, float b, float t)
     {
         return (1 - t) * a + b * t;
     }
 
+    /**
+     * Calculates the fraction, based on a value between two values.
+     *
+     * @param a The start value.
+     * @param b The end value.
+     * @param v The value in the middle.
+     * @public
+     */
+
     PACKAGE_API float InverseLerp(float a, float b, float v)
     {
         return std::clamp(((v - a) / (b - a)), 0.0f, 1.0f);
     }
 }
+
+/**
+ * Trims a string value.
+ *
+ * @param contents The string to trim.
+ * @private
+ */
+
 std::string Trim(const char *contents)
 {
     return std::regex_replace(contents, std::regex("^\\s+|\\s+$"), "");
 }
 
+/**
+ * Splits a string into an array based on a delimiter.
+ *
+ * @param contents The string to split.
+ * @param delimiter The delimiter to split on.
+ * @private
+ */
+
 std::vector<std::string> Split(const char *contents, const char delimiter)
 {
     auto parts = std::vector<std::string>();

include/RhythmGameUtilities/File.hpp

@@ -7,6 +7,13 @@
 namespace RhythmGameUtilities
 {
 
+/**
+ * Reads the entire contents of a file.
+ *
+ * @param path The path of the file to read.
+ * @public
+ */
+
 std::string ReadFromFile(const char *path)
 {
     std::ifstream file(path);

include/RhythmGameUtilities/Utilities.hpp

@@ -26,6 +26,7 @@ const float SECONDS_PER_MINUTE = 60.0f;
  * @param seconds The seconds to generate ticks with.
  * @param resolution The resolution of the song.
  * @param bpmChanges All BPM changes within the song.
+ * @public
  */
 
 int ConvertSecondsToTicks(float seconds, int resolution,
@@ -61,6 +62,13 @@ int ConvertSecondsToTicks(float seconds, int resolution,
     return totalTicks;
 }
 
+/**
+ * Takes a map of key/value pairs and returns a list of adjacent key pairs.
+ *
+ * @param keyValuePairs Key/value pairs map.
+ * @public
+ */
+
 std::vector<std::tuple<int, int>>
 GenerateAdjacentKeyPairs(std::map<int, int> keyValuePairs)
 {
@@ -148,6 +156,7 @@ extern "C"
      *
      * @param tick The tick.
      * @param resolution The resolution of the song.
+     * @public
      */
 
     PACKAGE_API float ConvertTickToPosition(float tick, int resolution)
@@ -160,6 +169,7 @@ extern "C"
      *
      * @param bpm The base BPM for a song.
      * @param currentTime A timestamp to compare to the BPM.
+     * @public
      */
 
     PACKAGE_API bool IsOnTheBeat(float bpm, float currentTime)
@@ -175,11 +185,29 @@ extern "C"
         return result;
     }
 
+    /**
+     * Rounds a value up the nearest multiplier.
+     *
+     * @param value The value to round.
+     * @param multiplier The multiplier to round using.
+     * @public
+     */
+
     PACKAGE_API int RoundUpToTheNearestMultiplier(int value, int multiplier)
     {
         return (int)std::ceil((float)value / multiplier) * multiplier;
     }
 
+    /**
+     * Calculated the accuracy ratio of the current position against a static
+     * position.
+     *
+     * @param position The position to test against.
+     * @param currentPosition The current position.
+     * @param delta The plus/minus delta to test the current position against.
+     * @public
+     */
+
     PACKAGE_API float CalculateAccuracyRatio(int position, int currentPosition,
                                              int delta = 50)
     {