docs: improve doxygen docs (#952)

cieslarmichal · Oct 9, 2024 · 98cfadc · 98cfadc
1 parent f8fa805
commit 98cfadc
Show file tree

Hide file tree

Showing 42 changed files with 12,767 additions and 9,254 deletions.
diff --git a/include/faker-cxx/book.h b/include/faker-cxx/book.h
@@ -23,6 +23,8 @@ FAKER_CXX_EXPORT std::string_view title(Locale locale = Locale::en_US);
 /**
  * @brief Returns a random book genre.
  *
+ * @param locale The locale. Defaults to `Locale::en_US`.
+ *
  * @returns Book genre.
  *
  * @code
@@ -34,6 +36,8 @@ FAKER_CXX_EXPORT std::string_view genre(Locale locale = Locale::en_US);
 /**
  * @brief Returns a random book author.
  *
+ * @param locale The locale. Defaults to `Locale::en_US`.
+ *
  * @returns Book author.
  *
  * @code
@@ -45,6 +49,8 @@ FAKER_CXX_EXPORT std::string_view author(Locale locale = Locale::en_US);
 /**
  * @brief Returns a random book publisher.
  *
+ * @param locale The locale. Defaults to `Locale::en_US`.
+ *
  * @returns Book publisher.
  *
  * @code
@@ -56,6 +62,8 @@ FAKER_CXX_EXPORT std::string_view publisher(Locale locale = Locale::en_US);
 /**
  * @brief Returns format of book
  *
+ * @param locale The locale. Defaults to `Locale::en_US`.
+ *
  * @returns BookFormat format of book
  *
  * @code
@@ -67,6 +75,8 @@ FAKER_CXX_EXPORT std::string_view format(Locale locale = Locale::en_US);
 /**
  * @brief returns a random book series
  *
+ * @param locale The locale. Defaults to `Locale::en_US`.
+ *
  * @returns std::string_view book series
  *
  * @code

diff --git a/include/faker-cxx/color.h b/include/faker-cxx/color.h
@@ -57,7 +57,9 @@ FAKER_CXX_EXPORT std::string hex(HexCasing casing = HexCasing::Lower, HexPrefix
  * @brief Returns an HSL color.
  *
  * @param includeAlpha Adds an alpha value to the color (HSLA). Defaults to `false`.
+ *
  * @returns HSL color formatted with hsl(X,X,X) or hsla(X,X,X,X).
+ *
  * @code
  * faker::color::hsl() // "hsl(0, 20, 100)"
  * faker::color::hsl(true) // "hsla(0, 0, 100, 0.50)"
@@ -69,7 +71,9 @@ FAKER_CXX_EXPORT std::string hsl(bool includeAlpha = false);
  * @brief Returns an LCH color.
  *
  * @param includeAlpha Adds an alpha value to the color (LCHA). Defaults to `false`.
+ *
  * @returns LCH color formatted with lch(X,X,X) or lcha(X,X,X,X).
+ *
  * @code
  * faker::color::lch() // "lch(0, 20, 100)"
  * faker::color::lch(true) // "lcha(0, 0, 100, 0.50)"
@@ -81,6 +85,7 @@ FAKER_CXX_EXPORT std::string lch(bool includeAlpha = false);
  * @brief Return a CMYK color
  *
  * @returns CMYK color formatted with cmyk(X,X,X,X)
+ *
  * @code
  * faker::color::cmyk() // "cmyk(0.72, 0.88, 0.00, 0.06)"
  * @endcode
@@ -91,6 +96,7 @@ FAKER_CXX_EXPORT std::string cmyk();
  * @brief Return a LAB color
  *
  * @returns LAB color formatted with lab(X,X,X)
+ *
  * @code
  * faker::color::lab() // "lab(98.74, 2.18, -2.35)"
  * @endcode
@@ -101,6 +107,7 @@ FAKER_CXX_EXPORT std::string lab();
  * @brief Return a HSB color
  *
  * @returns HSB color formatted with hsb(X,X,X)
+ *
  * @code
  * faker::color::hsb() // "hsb(37, 82, 50)"
  * @endcode
@@ -111,6 +118,7 @@ FAKER_CXX_EXPORT std::string hsb();
  * @brief Return a HSV color
  *
  * @returns HSV color formatted with hsv(X,X,X)
+ *
  * @code
  * faker::color::hsv() // "hsv(21, 67, 39)"
  * @endcode
@@ -121,6 +129,7 @@ FAKER_CXX_EXPORT std::string hsv();
  * @brief Return a HWB color
  *
  * @returns HWB color formatted with hwb(X,X,X)
+ *
  * @code
  * faker::color::hwb() // "hwb(34, 67, 90)"
  * @endcode
@@ -131,6 +140,7 @@ FAKER_CXX_EXPORT std::string hwb();
  * @brief Return a YUV color
  *
  * @returns YUV color formatted with yuv(X,X,X)
+ *
  * @code
  * faker::color::yuv() // "yuv(42, 234, 109)"
  * @endcode

diff --git a/include/faker-cxx/commerce.h b/include/faker-cxx/commerce.h
@@ -77,7 +77,7 @@ FAKER_CXX_EXPORT std::string productFullName();
 /**
  * @brief Returns a random valid ean13 code.
  *
- * @returns Ean13 code.
+ * @returns EAN13 code.
  *
  * @code
  * faker::commerce::EAN13() // "1234567890128"
@@ -88,7 +88,7 @@ FAKER_CXX_EXPORT std::string EAN13();
 /**
  * @brief Returns a random valid ean8 code.
  *
- * @returns Ean8 code.
+ * @returns EAN8 code.
  *
  * @code
  * faker::commerce::EAN8() // "90311017"
@@ -99,7 +99,7 @@ FAKER_CXX_EXPORT std::string EAN8();
 /**
  * @brief Returns a random valid isbn13 code.
  *
- * @returns Isbn13 code.
+ * @returns ISBN13 code.
  *
  * @code
  * faker::commerce::ISBN13() // "9781234567897"
@@ -110,7 +110,7 @@ FAKER_CXX_EXPORT std::string ISBN13();
 /**
  * @brief Returns a random valid ISBN10 code.
  *
- * @returns Isbn10 code.
+ * @returns ISBN10 code.
  *
  * @code
  * faker::commerce::ISBN10() // "0200716018"
@@ -121,7 +121,7 @@ FAKER_CXX_EXPORT std::string ISBN10();
 /**
  * @brief Returns a random payment type.
  *
- * @returns paymentType.
+ * @returns Payment type.
  *
  * @code
  * faker::commerce::paymentType() // "Credit Card"
@@ -132,7 +132,7 @@ FAKER_CXX_EXPORT std::string_view paymentType();
 /**
  * @brief Returns a random payment provider.
  *
- * @returns paymentProvider.
+ * @returns Payment provider.
  *
  * @code
  * faker::commerce::paymentProvider() // "Paypal"
@@ -143,7 +143,7 @@ FAKER_CXX_EXPORT std::string_view paymentProvider();
 /**
  * @brief Returns a random product description.
  *
- * @returns productDescription.
+ * @returns Product description.
  *
  * @code
  * faker::commerce::productDescription() // "Elevate your lifestyle with premium quality product."
@@ -154,7 +154,7 @@ FAKER_CXX_EXPORT std::string_view productDescription();
 /**
  * @brief Returns a random product category.
  *
- * @returns productCategory.
+ * @returns Product category.
  *
  * @code
  * faker::commerce::productCategory() // "Electronics"
@@ -165,7 +165,7 @@ FAKER_CXX_EXPORT std::string_view productCategory();
 /**
  * @brief Returns a random product review.
  *
- * @returns productReview.
+ * @returns Product review.
  *
  * @code
  * faker::commerce::productReview() //  "Unfortunately, it broke shortly after I started using it."
@@ -176,7 +176,7 @@ FAKER_CXX_EXPORT std::string_view productReview();
 /**
  * @brief Returns a random discount type.
  *
- * @returns discountType.
+ * @returns Discount type.
  *
  * @code
  * faker::commerce::discountType() // "percentage"
@@ -187,7 +187,7 @@ FAKER_CXX_EXPORT std::string_view discountType();
 /**
  * @brief Returns a random order status.
  *
- * @returns orderStatus.
+ * @returns Order status.
  *
  * @code
  * faker::commerce::orderStatus() // "shipped"
@@ -198,7 +198,7 @@ FAKER_CXX_EXPORT std::string_view orderStatus();
 /**
  * @brief Returns a random shipping carrier.
  *
- * @returns shipping carrier
+ * @returns Shipping carrier.
  *
  * @code
  * faker::commerce::shippingMethod() // "FedEx"

diff --git a/include/faker-cxx/company.h b/include/faker-cxx/company.h
@@ -8,10 +8,18 @@
 
 namespace faker::company
 {
-enum class CompanyNameFormat;
+enum class CompanyNameFormat
+{
+    LastNameSuffix,
+    FirstNameLastNameSuffix,
+    FirstNameLastNameJobAreaSuffix,
+};
+
 /**
  * @brief Returns a random company name.
  *
+ * @param format The optional format of the company name.
+ *
  * @returns Company name.
  *
  * @code
@@ -131,10 +139,4 @@ FAKER_CXX_EXPORT std::string_view catchPhraseDescriptor();
  */
 FAKER_CXX_EXPORT std::string_view catchPhraseNoun();
 
-enum class CompanyNameFormat
-{
-    LastNameSuffix,
-    FirstNameLastNameSuffix,
-    FirstNameLastNameJobAreaSuffix,
-};
 }
diff --git a/include/faker-cxx/computer.h b/include/faker-cxx/computer.h
@@ -9,7 +9,7 @@ namespace faker::computer
 /**
  * @brief Returns a random computer type.
  *
- * @returns computer type
+ * @returns Computer type.
  *
  * @code
  * faker::computer::type() // Laptop
@@ -20,7 +20,7 @@ FAKER_CXX_EXPORT std::string_view type();
 /**
  * @brief Returns a random computer manufacture name.
  *
- * @returns manufacture name
+ * @returns Manufacture name.
  *
  * @code
  * faker::computer::manufacture() // HP
@@ -31,7 +31,7 @@ FAKER_CXX_EXPORT std::string_view manufacture();
 /**
  * @brief Returns a random computer model.
  *
- * @returns computer model
+ * @returns Computer model.
  *
  * @code
  * faker::computer::model() // MacBook Air
@@ -42,7 +42,7 @@ FAKER_CXX_EXPORT std::string_view model();
 /**
  * @brief Returns a random CPU manufacture name.
  *
- * @returns CPU manufacture name
+ * @returns CPU manufacture name.
  *
  * @code
  * faker::computer::cpuManufacture() // Intel
@@ -53,7 +53,7 @@ FAKER_CXX_EXPORT std::string_view cpuManufacture();
 /**
  * @brief Returns a random CPU type.
  *
- * @returns CPU type
+ * @returns CPU type.
  *
  * @code
  * faker::computer::cpuType() // x86
@@ -64,7 +64,7 @@ FAKER_CXX_EXPORT std::string_view cpuType();
 /**
  * @brief Returns a random CPU model.
  *
- * @returns computer CPU model
+ * @returns Computer CPU model.
  *
  * @code
  * faker::computer::cpuModel() // Core i9-11900k
@@ -75,7 +75,7 @@ FAKER_CXX_EXPORT std::string_view cpuModel();
 /**
  * @brief Returns a random GPU manufacture name.
  *
- * @returns GPU manufacture name
+ * @returns GPU manufacture name.
  *
  * @code
  * faker::computer::gpuManufacture() // NVIDIA
@@ -86,7 +86,7 @@ FAKER_CXX_EXPORT std::string_view gpuManufacture();
 /**
  * @brief Returns a random GPU type.
  *
- * @returns GPU type
+ * @returns GPU type.
  *
  * @code
  * faker::computer::gpuType() // Integrated
@@ -97,7 +97,7 @@ FAKER_CXX_EXPORT std::string_view gpuType();
 /**
  * @brief Returns a random GPU model.
  *
- * @returns computer GPU model
+ * @returns Computer GPU model.
  *
  * @code
  * faker::computer::gpuModel() // NVIDIA GeForce RTX 3080