Skip to content

Commit f81ced2

Browse files
authored
Reformat Common++ documentation to use triple slash. (seladb#1647)
* Reformatted Common++ to use triple slash /// instead of /** for documentation. * Fixed potentially undefined `size_t`. * Fixed string include. * Reverted std::size_t to size_t.
1 parent 3d0717b commit f81ced2

13 files changed

+803
-1390
lines changed

Common++/header/GeneralUtils.h

Lines changed: 34 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -6,56 +6,46 @@
66

77
/// @file
88

9-
/**
10-
* \namespace pcpp
11-
* \brief The main namespace for the PcapPlusPlus lib
12-
*/
9+
/// @namespace pcpp
10+
/// @brief The main namespace for the PcapPlusPlus lib
1311
namespace pcpp
1412
{
15-
/**
16-
* Convert a byte array into a string of hex characters. For example: for the array { 0xaa, 0x2b, 0x10 } the string
17-
* "aa2b10" will be returned
18-
* @param[in] byteArr A byte array
19-
* @param[in] byteArrSize The size of the byte array [in bytes]
20-
* @param[in] stringSizeLimit An optional parameter that enables to limit the returned string size. If set to a
21-
* positive integer value the returned string size will be equal or less than this value. If the string
22-
* representation of the whole array is longer than this size then only part of the array will be read. The default
23-
* value is -1 which means no string size limitation
24-
* @return A string of hex characters representing the byte array
25-
*/
13+
/// Convert a byte array into a string of hex characters. For example: for the array { 0xaa, 0x2b, 0x10 } the string
14+
/// "aa2b10" will be returned
15+
/// @param[in] byteArr A byte array
16+
/// @param[in] byteArrSize The size of the byte array [in bytes]
17+
/// @param[in] stringSizeLimit An optional parameter that enables to limit the returned string size. If set to a
18+
/// positive integer value the returned string size will be equal or less than this value. If the string
19+
/// representation of the whole array is longer than this size then only part of the array will be read. The default
20+
/// value is -1 which means no string size limitation
21+
/// @return A string of hex characters representing the byte array
2622
std::string byteArrayToHexString(const uint8_t* byteArr, size_t byteArrSize, int stringSizeLimit = -1);
2723

28-
/**
29-
* Convert a string of hex characters into a byte array. For example: for the string "aa2b10" an array of values
30-
* { 0xaa, 0x2b, 0x10 } will be returned
31-
* @param[in] hexString A string of hex characters
32-
* @param[out] resultByteArr A pre-allocated byte array where the result will be written to
33-
* @param[in] resultByteArrSize The size of the pre-allocated byte array
34-
* @return The size of the result array. If the string represents an array that is longer than the pre-allocated
35-
* size (resultByteArrSize) then the result array will contain only the part of the string that managed to fit into
36-
* the array, and the returned size will be resultByteArrSize. However if the string represents an array that is
37-
* shorter than the pre-allocated size then some of the cells will remain empty and contain zeros, and the returned
38-
* size will be the part of the array that contain data. If the input is an illegal hex string 0 will be returned.
39-
* Illegal hex string means odd number of characters or a string that contains non-hex characters
40-
*/
24+
/// Convert a string of hex characters into a byte array. For example: for the string "aa2b10" an array of values
25+
/// { 0xaa, 0x2b, 0x10 } will be returned
26+
/// @param[in] hexString A string of hex characters
27+
/// @param[out] resultByteArr A pre-allocated byte array where the result will be written to
28+
/// @param[in] resultByteArrSize The size of the pre-allocated byte array
29+
/// @return The size of the result array. If the string represents an array that is longer than the pre-allocated
30+
/// size (resultByteArrSize) then the result array will contain only the part of the string that managed to fit into
31+
/// the array, and the returned size will be resultByteArrSize. However if the string represents an array that is
32+
/// shorter than the pre-allocated size then some of the cells will remain empty and contain zeros, and the returned
33+
/// size will be the part of the array that contain data. If the input is an illegal hex string 0 will be returned.
34+
/// Illegal hex string means odd number of characters or a string that contains non-hex characters
4135
size_t hexStringToByteArray(const std::string& hexString, uint8_t* resultByteArr, size_t resultByteArrSize);
4236

43-
/**
44-
* This is a cross platform version of memmem (https://man7.org/linux/man-pages/man3/memmem.3.html) which is not
45-
* supported on all platforms.
46-
* @param[in] haystack A pointer to the buffer to be searched
47-
* @param[in] haystackLen Length of the haystack buffer
48-
* @param[in] needle A pointer to a buffer that will be searched for
49-
* @param[in] needleLen Length of the needle buffer
50-
* @return A pointer to the beginning of the substring, or nullptr if the substring is not found
51-
*/
37+
/// This is a cross platform version of memmem (https://man7.org/linux/man-pages/man3/memmem.3.html) which is not
38+
/// supported on all platforms.
39+
/// @param[in] haystack A pointer to the buffer to be searched
40+
/// @param[in] haystackLen Length of the haystack buffer
41+
/// @param[in] needle A pointer to a buffer that will be searched for
42+
/// @param[in] needleLen Length of the needle buffer
43+
/// @return A pointer to the beginning of the substring, or nullptr if the substring is not found
5244
char* cross_platform_memmem(const char* haystack, size_t haystackLen, const char* needle, size_t needleLen);
5345

54-
/**
55-
* Calculates alignment.
56-
* @param[in] number Given number
57-
* @return The aligned number
58-
*/
46+
/// Calculates alignment.
47+
/// @param[in] number Given number
48+
/// @return The aligned number
5949
template <int alignment> static int align(int number)
6050
{
6151
// Only works for alignment with power of 2
@@ -65,10 +55,8 @@ namespace pcpp
6555
return (number + mask) & ~mask;
6656
}
6757

68-
/**
69-
* A template class to calculate enum class hash
70-
* @tparam EnumClass
71-
*/
58+
/// A template class to calculate enum class hash
59+
/// @tparam EnumClass
7260
template <typename EnumClass, typename std::enable_if<std::is_enum<EnumClass>::value, bool>::type = false>
7361
struct EnumClassHash
7462
{

0 commit comments

Comments
 (0)