Marks as private several functions in our header files. (#600)

* Marks as private several functions in our header files.

* format

Author: lemire

include/ada/character_sets-inl.h

@@ -9,6 +9,11 @@
 
 #include "ada/character_sets.h"
 
+/**
+ * These functions are not part of our public API and may
+ * change at any time.
+ * @private
+ */
 namespace ada::character_sets {
 
 constexpr char hex[1024] =

include/ada/character_sets.h

@@ -11,6 +11,9 @@
 #include <cstdint>
 
 /**
+ * These functions are not part of our public API and may
+ * change at any time.
+ * @private
  * @namespace ada::character_sets
  * @brief Includes the definitions for unicode character sets.
  */

include/ada/checkers.h

@@ -11,19 +11,24 @@
 #include <cstring>
 
 /**
+ * These functions are not part of our public API and may
+ * change at any time.
+ * @private
  * @namespace ada::checkers
  * @brief Includes the definitions for validation functions
  */
 namespace ada::checkers {
 
 /**
+ * @private
  * Assuming that x is an ASCII letter, this function returns the lower case
  * equivalent.
  * @details More likely to be inlined by the compiler and constexpr.
  */
 constexpr char to_lower(char x) noexcept;
 
 /**
+ * @private
  * Returns true if the character is an ASCII letter. Equivalent to std::isalpha
  * but more likely to be inlined by the compiler.
  *
@@ -32,24 +37,28 @@ constexpr char to_lower(char x) noexcept;
 constexpr bool is_alpha(char x) noexcept;
 
 /**
+ * @private
  * Check whether a string starts with 0x or 0X. The function is only
  * safe if input.size() >=2.
  *
  * @see has_hex_prefix
  */
 inline bool has_hex_prefix_unsafe(std::string_view input);
 /**
+ * @private
  * Check whether a string starts with 0x or 0X.
  */
 inline bool has_hex_prefix(std::string_view input);
 
 /**
+ * @private
  * Check whether x is an ASCII digit. More likely to be inlined than
  * std::isdigit.
  */
 constexpr bool is_digit(char x) noexcept;
 
 /**
+ * @private
  * @details A string starts with a Windows drive letter if all of the following
  * are true:
  *
@@ -63,26 +72,30 @@ constexpr bool is_digit(char x) noexcept;
 inline constexpr bool is_windows_drive_letter(std::string_view input) noexcept;
 
 /**
+ * @private
  * @details A normalized Windows drive letter is a Windows drive letter of which
  * the second code point is U+003A (:).
  */
 inline constexpr bool is_normalized_windows_drive_letter(
     std::string_view input) noexcept;
 
 /**
+ * @private
  * @warning Will be removed when Ada requires C++20.
  */
 ada_really_inline bool begins_with(std::string_view view,
                                    std::string_view prefix);
 
 /**
+ * @private
  * Returns true if an input is an ipv4 address. It is assumed that the string
  * does not contain uppercase ASCII characters (the input should have been
  * lowered cased before calling this function) and is not empty.
  */
 ada_really_inline ada_constexpr bool is_ipv4(std::string_view view) noexcept;
 
 /**
+ * @private
  * Returns a bitset. If the first bit is set, then at least one character needs
  * percent encoding. If the second bit is set, a \\ is found. If the third bit
  * is set then we have a dot. If the fourth bit is set, then we have a percent
@@ -92,6 +105,7 @@ ada_really_inline constexpr uint8_t path_signature(
     std::string_view input) noexcept;
 
 /**
+ * @private
  * Returns true if the length of the domain name and its labels are according to
  * the specifications. The length of the domain must be 255 octets (253
  * characters not including the last 2 which are the empty label reserved at the

include/ada/helpers.h

@@ -13,6 +13,9 @@
 #include <optional>
 
 /**
+ * These functions are not part of our public API and may
+ * change at any time.
+ *
  * @private
  * @namespace ada::helpers
  * @brief Includes the definitions for helper functions
@@ -175,6 +178,7 @@ inline void inner_concat(std::string& buffer, T t, Args... args) {
 }
 
 /**
+ * @private
  * Concatenate the arguments and return a string.
  * @returns a string
  */
@@ -186,6 +190,7 @@ std::string concat(Args... args) {
 }
 
 /**
+ * @private
  * @return Number of leading zeroes.
  */
 inline int leading_zeroes(uint32_t input_num) noexcept {
@@ -199,6 +204,7 @@ inline int leading_zeroes(uint32_t input_num) noexcept {
 }
 
 /**
+ * @private
  * Counts the number of decimal digits necessary to represent x.
  * faster than std::to_string(x).size().
  * @return digit count

include/ada/unicode-inl.h

@@ -8,6 +8,10 @@
 #include "ada/unicode.h"
 
 /**
+ * Unicode operations. These functions are not part of our public API and may
+ * change at any time.
+ *
+ * private
  * @namespace ada::unicode
  * @brief Includes the declarations for unicode operations
  */

include/ada/unicode.h

@@ -12,12 +12,17 @@
 #include <optional>
 
 /**
+ * Unicode operations. These functions are not part of our public API and may
+ * change at any time.
+ *
+ * @private
  * @namespace ada::unicode
  * @brief Includes the definitions for unicode operations
  */
 namespace ada::unicode {
 
 /**
+ * @private
  * We receive a UTF-8 string representing a domain name.
  * If the string is percent encoded, we apply percent decoding.
  *
@@ -61,11 +66,13 @@ bool to_ascii(std::optional<std::string>& out, std::string_view plain,
               size_t first_percent);
 
 /**
+ * @private
  * @see https://www.unicode.org/reports/tr46/#ToUnicode
  */
 std::string to_unicode(std::string_view input);
 
 /**
+ * @private
  * Checks if the input has tab or newline characters.
  *
  * @attention The has_tabs_or_newline function is a bottleneck and it is simple
@@ -75,19 +82,22 @@ ada_really_inline bool has_tabs_or_newline(
     std::string_view user_input) noexcept;
 
 /**
+ * @private
  * Checks if the input is a forbidden host code point.
  * @see https://url.spec.whatwg.org/#forbidden-host-code-point
  */
 ada_really_inline constexpr bool is_forbidden_host_code_point(char c) noexcept;
 
 /**
+ * @private
  * Checks if the input contains a forbidden domain code point.
  * @see https://url.spec.whatwg.org/#forbidden-domain-code-point
  */
 ada_really_inline constexpr bool contains_forbidden_domain_code_point(
     const char* input, size_t length) noexcept;
 
 /**
+ * @private
  * Checks if the input contains a forbidden domain code point in which case
  * the first bit is set to 1. If the input contains an upper case ASCII letter,
  * then the second bit is set to 1.
@@ -98,18 +108,21 @@ contains_forbidden_domain_code_point_or_upper(const char* input,
                                               size_t length) noexcept;
 
 /**
+ * @private
  * Checks if the input is a forbidden domain code point.
  * @see https://url.spec.whatwg.org/#forbidden-domain-code-point
  */
 ada_really_inline constexpr bool is_forbidden_domain_code_point(
     char c) noexcept;
 
 /**
+ * @private
  * Checks if the input is alphanumeric, '+', '-' or '.'
  */
 ada_really_inline constexpr bool is_alnum_plus(char c) noexcept;
 
 /**
+ * @private
  * @details An ASCII hex digit is an ASCII upper hex digit or ASCII lower hex
  * digit. An ASCII upper hex digit is an ASCII digit or a code point in the
  * range U+0041 (A) to U+0046 (F), inclusive. An ASCII lower hex digit is an
@@ -118,6 +131,7 @@ ada_really_inline constexpr bool is_alnum_plus(char c) noexcept;
 ada_really_inline constexpr bool is_ascii_hex_digit(char c) noexcept;
 
 /**
+ * @private
  * Checks if the input is a C0 control or space character.
  *
  * @details A C0 control or space is a C0 control or U+0020 SPACE.
@@ -127,38 +141,44 @@ ada_really_inline constexpr bool is_ascii_hex_digit(char c) noexcept;
 ada_really_inline constexpr bool is_c0_control_or_space(char c) noexcept;
 
 /**
+ * @private
  * Checks if the input is a ASCII tab or newline character.
  *
  * @details An ASCII tab or newline is U+0009 TAB, U+000A LF, or U+000D CR.
  */
 ada_really_inline constexpr bool is_ascii_tab_or_newline(char c) noexcept;
 
 /**
+ * @private
  * @details A double-dot path segment must be ".." or an ASCII case-insensitive
  * match for ".%2e", "%2e.", or "%2e%2e".
  */
 ada_really_inline ada_constexpr bool is_double_dot_path_segment(
     std::string_view input) noexcept;
 
 /**
+ * @private
  * @details A single-dot path segment must be "." or an ASCII case-insensitive
  * match for "%2e".
  */
 ada_really_inline constexpr bool is_single_dot_path_segment(
     std::string_view input) noexcept;
 
 /**
+ * @private
  * @details ipv4 character might contain 0-9 or a-f character ranges.
  */
 ada_really_inline constexpr bool is_lowercase_hex(char c) noexcept;
 
 /**
+ * @private
  * @details Convert hex to binary. Caller is responsible to ensure that
  * the parameter is an hexadecimal digit (0-9, A-F, a-f).
  */
 ada_really_inline unsigned constexpr convert_hex_to_binary(char c) noexcept;
 
 /**
+ * @private
  * first_percent should be  = input.find('%')
  *
  * @todo It would be faster as noexcept maybe, but it could be unsafe since.
@@ -169,19 +189,22 @@ ada_really_inline unsigned constexpr convert_hex_to_binary(char c) noexcept;
 std::string percent_decode(std::string_view input, size_t first_percent);
 
 /**
+ * @private
  * Returns a percent-encoding string whether percent encoding was needed or not.
  * @see https://github.com/nodejs/node/blob/main/src/node_url.cc#L226
  */
 std::string percent_encode(std::string_view input,
                            const uint8_t character_set[]);
 /**
+ * @private
  * Returns a percent-encoded string version of input, while starting the percent
  * encoding at the provided index.
  * @see https://github.com/nodejs/node/blob/main/src/node_url.cc#L226
  */
 std::string percent_encode(std::string_view input,
                            const uint8_t character_set[], size_t index);
 /**
+ * @private
  * Returns true if percent encoding was needed, in which case, we store
  * the percent-encoded content in 'out'. If the boolean 'append' is set to
  * true, the content is appended to 'out'.
@@ -192,12 +215,14 @@ template <bool append>
 bool percent_encode(std::string_view input, const uint8_t character_set[],
                     std::string& out);
 /**
+ * @private
  * Returns the index at which percent encoding should start, or (equivalently),
  * the length of the prefix that does not require percent encoding.
  */
 ada_really_inline size_t percent_encode_index(std::string_view input,
                                               const uint8_t character_set[]);
 /**
+ * @private
  * Lowers the string in-place, assuming that the content is ASCII.
  * Return true if the content was ASCII.
  */