fix documentation typos (#275)

* fix documentation typos * fix shuffle params
cieslarmichal · Nov 18, 2023 · eacfd8f · eacfd8f
1 parent c0cb543
commit eacfd8f
Show file tree

Hide file tree

Showing 31 changed files with 138 additions and 86 deletions.
diff --git a/.clang-format-ignore b/.clang-format-ignore
@@ -0,0 +1 @@
+CMakeLists.txt
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -9,13 +9,13 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 option(BUILD_FAKER_TESTS DEFAULT ON)
 
-if(MSVC)
+if (MSVC)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /std:c++20 /permissive- /bigobj")
-else()
+else ()
     set(CMAKE_CXX_FLAGS
         "${CMAKE_CXX_FLAGS} -Wall -Wextra -Wpedantic -Wconversion -Wformat -Werror"
-    )
-endif()
+        )
+endif ()
 
 set(LIBRARY_NAME faker-cxx)
 
@@ -28,6 +28,7 @@ set(FAKER_SOURCES
     src/modules/datatype/Datatype.cpp
     src/modules/date/Date.cpp
     src/modules/finance/Finance.cpp
+    src/modules/food/Food.cpp
     src/modules/helper/Helper.cpp
     src/modules/internet/Internet.cpp
     src/modules/location/Location.cpp
@@ -64,6 +65,7 @@ set(FAKER_UT_SOURCES
     src/modules/datatype/DatatypeTest.cpp
     src/modules/date/DateTest.cpp
     src/modules/finance/FinanceTest.cpp
+    src/modules/food/FoodTest.cpp
     src/modules/internet/InternetTest.cpp
     src/modules/location/LocationTest.cpp
     src/modules/lorem/LoremTest.cpp
@@ -104,7 +106,7 @@ set(FMT_INCLUDE_DIR "${CMAKE_SOURCE_DIR}/externals/fmt/include")
 
 target_link_libraries(${LIBRARY_NAME} PRIVATE fmt)
 
-if(BUILD_FAKER_TESTS)
+if (BUILD_FAKER_TESTS)
     add_subdirectory(externals/googletest)
 
     set(GTEST_INCLUDE_DIR
@@ -123,17 +125,17 @@ if(BUILD_FAKER_TESTS)
     add_executable(${LIBRARY_NAME}-UT ${FAKER_UT_SOURCES})
 
     target_link_libraries(${LIBRARY_NAME}-UT PRIVATE gtest_main gmock_main
-                                                     faker-cxx)
+        faker-cxx)
 
     target_include_directories(
         ${LIBRARY_NAME}-UT
         PRIVATE ${FMT_INCLUDE_DIR} ${GTEST_INCLUDE_DIR} ${GMOCK_INCLUDE_DIR}
-                ${CMAKE_CURRENT_LIST_DIR})
+        ${CMAKE_CURRENT_LIST_DIR})
 
     add_test(
         NAME ${LIBRARY_NAME}-UT
         COMMAND ${LIBRARY_NAME}-UT
         WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR})
 
     target_code_coverage(${LIBRARY_NAME}-UT ALL)
-endif()
+endif ()
diff --git a/include/faker-cxx/Airline.h b/include/faker-cxx/Airline.h
@@ -15,13 +15,14 @@ class Airline
         Widebody,
     };
 
-    /*
+    /**
      * @brief Get a random aircraft type
      *
      * @return a random aircraft type
      *
      * @code
      * Airline::aircraftType // "narrowbody"
+     * @endcode
      */
     static std::string aircraftType();
 
@@ -31,7 +32,7 @@ class Airline
         std::string iataTypeCode;
     };
 
-    /*
+    /**
      * @brief Get a random airplane
      *
      * @return a random airplane and its iataTypeCode
@@ -48,7 +49,7 @@ class Airline
         std::string iataCode;
     };
 
-    /*
+    /**
      * @brief Get a random airline
      *
      * @return a random airline and its iataCode
@@ -65,7 +66,7 @@ class Airline
         std::string iataCode;
     };
 
-    /*
+    /**
      * @brief Get a random airport
      *
      * @return a random airport and its iataCode
@@ -76,7 +77,7 @@ class Airline
      */
     static Airport airport();
 
-    /*
+    /**
      * @brief Get a random seat by aircraft type
      *
      * @param aircraftType the aircraft type
@@ -89,7 +90,7 @@ class Airline
      */
     static std::string seat(AircraftType aircraftType);
 
-    /*
+    /**
      * @brief Get a random record location
      *
      * @return a random record location
@@ -101,7 +102,7 @@ class Airline
      */
     static std::string recordLocator(bool allowNumerics = false);
 
-    /*
+    /**
      * @brief Get a random flight number from given length
      *
      * @param addLeadingZeros whether to add leading zeros
@@ -123,7 +124,8 @@ class Airline
         unsigned int min;
         unsigned int max;
     };
-    /*
+
+    /**
      * @brief Get a random flight number from given length
      *
      * @param addLeadingZeros whether to add leading zeros

diff --git a/include/faker-cxx/Date.h b/include/faker-cxx/Date.h
@@ -15,8 +15,8 @@ class Date
      * @returns ISO formatted string.
      *
      * @code
-     * Date::past() // "2023-12-08T19:31:32Z"
-     * Date::past(5) // "2020-06-16T15:24:09Z"
+     * Date::pastDate() // "2023-12-08T19:31:32Z"
+     * Date::pastDate(5) // "2020-06-16T15:24:09Z"
      * @endcode
      */
     static std::string pastDate(int years = 1);
@@ -29,8 +29,8 @@ class Date
      * @returns ISO formatted string.
      *
      * @code
-     * Date::future() // "2023-09-27T09:47:46Z"
-     * Date::future(5) // "2024-06-11T19:46:29Z"
+     * Date::futureDate() // "2023-09-27T09:47:46Z"
+     * Date::futureDate(5) // "2024-06-11T19:46:29Z"
      * @endcode
      */
     static std::string futureDate(int years = 1);
@@ -43,8 +43,8 @@ class Date
      * @returns ISO formatted string.
      *
      * @code
-     * Date::recent() // "2023-07-05T14:12:40Z"
-     * Date::recent(10) // "2023-06-29T18:24:12Z"
+     * Date::recentDate() // "2023-07-05T14:12:40Z"
+     * Date::recentDate(10) // "2023-06-29T18:24:12Z"
      * @endcode
      */
     static std::string recentDate(int days = 3);
@@ -57,8 +57,8 @@ class Date
      * @returns ISO formatted string.
      *
      * @code
-     * Date::soon() // "2023-07-07T18:19:12Z"
-     * Date::soon(10) // "2023-07-15T09:59:11Z"
+     * Date::soonDate() // "2023-07-07T18:19:12Z"
+     * Date::soonDate(10) // "2023-07-15T09:59:11Z"
      * @endcode
      */
     static std::string soonDate(int days = 3);
@@ -82,7 +82,7 @@ class Date
      * @brief Generates a random birthdate by year.
      *
      * @param minYear The minimum year to generate a birthdate. Defaults to `1920`.
-     * @param maxAge The maximum year to generate a birthdate. Defaults to `2000`.
+     * @param maxYear The maximum year to generate a birthdate. Defaults to `2000`.
      *
      * @returns ISO formatted string.
      *

diff --git a/include/faker-cxx/Helper.h b/include/faker-cxx/Helper.h
@@ -41,6 +41,19 @@ class Helper
         return data[index];
     }
 
+    /**
+     * @brief Get a random element from a vector.
+     *
+     * @tparam T an element type of the vector.
+     *
+     * @param data vector of elements.
+     *
+     * @return T a random element from the vector.
+     *
+     * @code
+     * Helper::arrayElement<std::string>(std::vector<std::string>{{"hello"}, {"world"}}) // "hello"
+     * @endcode
+     */
     template <class T>
     static T arrayElement(const std::vector<T>& data)
     {
@@ -61,6 +74,20 @@ class Helper
         T value;
     };
 
+    /**
+     * @brief Get a random element by weight from a vector.
+     *
+     * @tparam T an element type of the weighted element.
+     *
+     * @param data vector of weighted elements.
+     *
+     * @return T a weighted element value from the vector.
+     *
+     * @code
+     * Helper::weightedArrayElement<std::string>(std::vector<Helper::WeightedElement<std::string>>{{1, "value1"}, {10,
+     * "value2"}}) // "hello2"
+     * @endcode
+     */
     template <class T>
     static T weightedArrayElement(const std::vector<WeightedElement<T>>& data)
     {
@@ -96,16 +123,16 @@ class Helper
     }
 
     /**
-     * @brief Returns shuffled STL container.
+     * @brief Returns shuffled vector.
      *
-     * @tparam T an element type of the container.
+     * @tparam T an element type of the vector.
      *
-     * @param data The container.
+     * @param data The vector.
      *
-     * @return Container with shuffled elements.
+     * @return Vector with shuffled elements.
      *
      * @code
-     * Helper::arrayElement<char>(std::string{"abcd"}) // "dcba"
+     * Helper::shuffle<std::string>(std::vector<std::string>{{"hello"}, {"world"}}) // {{"world"}, {"hello"}}
      * @endcode
      */
     template <class T>
@@ -116,12 +143,13 @@ class Helper
         return data;
     }
 
+    // TODO: remove methods below from helper API, move to src/common
+
     /**
      * @brief Returns the given string parsed symbol by symbol and replaced the placeholders with digits ("0" - "9").
      * "!" will be replaced by digits >=2 ("2" - "9").
      *
      * @param str The template to parse string.
-     *
      * @param symbol The symbol to replace with digits. Defaults to '#'.
      *
      * @return The string replaced symbols with digits.
@@ -141,7 +169,6 @@ class Helper
      * `L` will be replaced with the appropriate Luhn checksum.
      *
      * @param inputString TThe credit card format pattern. Defaults to "6453-####-####-####-###L".
-     *
      * @param symbol The symbol to replace with a digit. Defaults to '#'.
      *
      * @return The string replaced symbols with digits.
@@ -220,7 +247,7 @@ class Helper
      * @tparam TResult The type of result of the given callback.
      *
      * @param callback The callback to that will be invoked if the probability check was successful.
-     * @param options.probability The probability (`[0.00, 1.00]`) of the callback being invoked. Defaults to `0.5`.
+     * @param probability The probability (`[0.00, 1.00]`) of the callback being invoked. Defaults to `0.5`.
      *
      * @return The result of the callback if the probability check was successful, otherwise empty string.
      *

diff --git a/include/faker-cxx/Location.h b/include/faker-cxx/Location.h
@@ -134,7 +134,7 @@ class Location
      * Location::latitude() // "-30.9501"
      * @endcode
      */
-    static std::string latitude(Precision = Precision::FourDp);
+    static std::string latitude(Precision precision = Precision::FourDp);
 
     /**
      * @brief Generates a random longitude.
@@ -147,7 +147,7 @@ class Location
      * Location::longitude() // "-30.9501"
      * @endcode
      */
-    static std::string longitude(Precision = Precision::FourDp);
+    static std::string longitude(Precision precision = Precision::FourDp);
 
     /**
      * @brief Generates a random direction from cardinal and ordinal directions.

diff --git a/include/faker-cxx/Lorem.h b/include/faker-cxx/Lorem.h
@@ -48,8 +48,8 @@ class Lorem
     /**
      * @brief Returns a random lorem sentences.
      *
-     * @param minWordCount The minimum number of sentences to generate. Defaults to `2`.
-     * @param maxWordCount The maximum number of sentences to generate. Defaults to `6`.
+     * @param minNumberOfSentences The minimum number of sentences to generate. Defaults to `2`.
+     * @param maxNumberOfSentences The maximum number of sentences to generate. Defaults to `6`.
      *
      * @returns Lorem sentences separated with spaces.
      *

diff --git a/include/faker-cxx/Medicine.h b/include/faker-cxx/Medicine.h
@@ -16,7 +16,6 @@ class Medicine
      * @code
      * Medicine::condition() // "AIDS"
      * @endcode
-     *
      */
     static std::string condition();
 
@@ -28,18 +27,17 @@ class Medicine
      * @code
      * Medicine::medicalTest() // "pulmonary auscultation"
      * @endcode
-     *
      */
     static std::string medicalTest();
 
     /**
      * @brief Returns a random Medical specialty
      *
      * @returns Medical specialty.
+     *
      * @code
      * Medicine::specialty() // "Cardiology"
      * @endcode
-     *
      */
 
     static std::string specialty();

diff --git a/include/faker-cxx/Number.h b/include/faker-cxx/Number.h
@@ -65,7 +65,6 @@ class Number
      *
      * @param min The minimum value of the range.
      * @param max The maximum value of the range.
-     * @param distribution The distribution to use.
      *
      * @throws std::invalid_argument if min is greater than max.
      *