docs(*): fix params, throws

include/basen/base58.hpp

@@ -13,39 +13,72 @@ namespace base58
     extern const char digits[59];
     extern const uint8_t map[256];
 
+    /**
+     * @return checks what contains only alphabet chars
+     * @warning doesn't validate checksum, use decodeCheck instead
+     */
     bool isValid(const char *str, size_t str_size) noexcept;
+    /**
+     * @param str string or string_view which you want to decode
+     * @return checks what contains only alphabet chars
+     * @warning doesn't validate checksum, use decodeCheck instead
+     */
     bool isValid(std::string_view str) noexcept;
 
     /**
-     * @throw basen::Exception(OVERFLOW) if there is an overflow
+     * @param data vector or span of data which you want to encode
+     * @return estimated size after encoding (for non-powers of two it is obviously larger)
+     * @throw basen::Exception(OVERFLOW) from baseN::sizeEncoded
      */
     size_t sizeEncoded(std::span<const uint8_t> data);
+    /**
+     * @param str string or string_view which you want to decode
+     * @return estimated size after decoding (for non-powers of two it is obviously larger)
+     */
     size_t sizeDecoded(std::string_view str) noexcept;
 
     /**
+     * @param data [in] pointer to data which you want encode
+     * @param str [out] pointer to string for encoded data output
      * @return number of leading chars, which should be trimmed
+     * @throw basen::Exception(OVERFLOW) from base58::sizeEncoded
      * @warning contain leading zeros, returns count of them
      */
     size_t encode(const uint8_t *data, size_t data_size, char *str, size_t str_size);
+    /**
+     * @param data vector or span of data which you want to encode
+     * @return encoded string
+     * @throw basen::Exception(OVERFLOW) from base58::sizeEncoded
+     */
     std::string encode(std::span<const uint8_t> data);
 
     /**
+     * @param str [in] pointer to string which you want decode
+     * @param data [out] pointer to data for encoded string output
      * @return number of leading chars, which should be trimmed
+     * @throw basen::Exception(OUT_OF_ALPH) from baseN::decode
      * @warning contain leading zeros, returns count of them
      */
     size_t decode(const char *str, size_t str_size, uint8_t *data, size_t data_size);
+    /**
+     * @param str string or string_view which you want to decode
+     * @return decoded data
+     * @throw basen::Exception(OUT_OF_ALPH) from baseN::decode
+     */
     std::vector<uint8_t> decode(std::string_view str);
 
     /**
      * @param data vector or span of data which you want to encode
      * @return encoded string + 4 first bytes of double sha256
+     * @throw basen::Exception(OVERFLOW) from base58::encode
      */
     std::string encodeCheck(std::span<const uint8_t> data);
     /**
-     * @param str string or string_view which you want to decode
+     * @param str encoded string or string_view + 4 first bytes of double sha256
      * @return decoded data without 4 first bytes of double sha256
+     * @throw basen::Exception(OUT_OF_ALPH) from base58::decode
      * @throw basen::Exception(PADDING) if str size < 4
-     * @throw basen::Exception(CHECKSUM) checksum incorrect
+     * @throw basen::Exception(CHECKSUM) if checksum incorrect
      */
     std::vector<uint8_t> decodeCheck(std::string_view str);
 }

include/basen/base64.hpp

@@ -10,28 +10,57 @@ namespace base64
     extern const char digits[65];
     extern const uint8_t map[256];
 
+    /**
+     * @return checks what contains only alphabet chars and ends with no more than two '=' chars
+     */
     bool isValid(const char *str, size_t str_size) noexcept;
+    /**
+     * @param str string or string_view which you want to decode
+     * @return checks what contains only alphabet chars and ends with no more than two '=' chars
+     */
     bool isValid(std::string_view str) noexcept;
 
     /**
+     * @param data vector or span of data which you want to encode
+     * @return exact size after encoding
      * @throw basen::Exception(OVERFLOW) if there is an overflow
      */
     size_t sizeEncoded(std::span<const uint8_t> data);
+    /**
+     * @param str string or string_view which you want to decode
+     * @return exact size after decoding
+     */
     size_t sizeDecoded(std::string_view str) noexcept;
 
     /**
+     * @param data [in] pointer to data which you want encode
+     * @param str [out] pointer to string for encoded data output
+     * @throw basen::Exception(OVERFLOW) from base64::sizeEncoded
      * @throw basen::Exception(LENGTH) if not enough allocated length
-     * @warning contain leading zeros, returns count of them
      */
     void encode(const uint8_t *data, size_t data_size, char *str, size_t str_size);
+    /**
+     * @param data vector or span of data which you want to encode
+     * @return encoded string
+     * @throw basen::Exception(OVERFLOW) from base64::sizeEncoded
+     * @throw basen::Exception(LENGTH) if not enough allocated length
+     */
     std::string encode(std::span<const uint8_t> data);
 
     /**
+     * @param str [in] pointer to string which you want decode
+     * @param data [out] pointer to data for encoded string output
      * @throw basen::Exception(LENGTH) if not enough allocated length
      * @throw basen::Exception(OUT_OF_ALPH) if out of digits map
      * @throw basen::Exception(PADDING) if incorrect padding
-     * @warning contain leading zeros, returns count of them
      */
     void decode(const char *str, size_t str_size, uint8_t *data, size_t data_size);
+    /**
+     * @param str string or string_view which you want to decode
+     * @return decoded data
+     * @throw basen::Exception(LENGTH) if not enough allocated length
+     * @throw basen::Exception(OUT_OF_ALPH) if out of digits map
+     * @throw basen::Exception(PADDING) if incorrect padding
+     */
     std::vector<uint8_t> decode(std::string_view str);
 }

include/basen/baseN.hpp

@@ -8,38 +8,36 @@
 namespace baseN
 {
     /**
-     * @param digits char[base] array of digits
+     * @param digits [in] alphabet of encoding
-     * @param digits_size size of digits array. Equals to base
      * @param map [out] uint8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. 255 if there is no symbol
+     * @return map of alphabet of encoding
      * @throw basen::Exception(ALPH_COLLISION) if alphabet contain same chars
      */
     void digitsMap(const char *digits, uint8_t digits_size, uint8_t *map);
     /**
-     * @param str [in] pointer to string
+     * @param map map of alphabet of encoding, which is returned by baseN::digitsMap
-     * @param str_size
+     * @return checks what contains only alphabet chars
-     * @param map uint8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. 255 if there is no symbol
-     * @return that string doesn't contain unnecessary symbols
      */
     bool isValid(const char *str, size_t str_size, const uint8_t *map) noexcept;
     /**
      * @param str string or string_view which you want to decode
-     * @param map uint8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. 255 if there is no symbol
+     * @param map map of alphabet of encoding, which is returned by baseN::digitsMap
-     * @return that string doesn't contain unnecessary symbols
+     * @return checks what contains only alphabet chars
      */
     bool isValid(std::string_view str, const uint8_t *map) noexcept;
 
     /**
      * @param data vector or span of data which you want to encode
-     * @param base from 1 to 255
+     * @param base radix of encoding from [2 to 254]
-     * @return estimated size after encoding
+     * @return estimated size after encoding (obviously larger)
      * @throw basen::Exception(BASE) if base < 2 || base > 254
      */
     size_t sizeEncoded(std::span<const uint8_t> data, uint8_t base);
     /**
      * @param str string or string_view which you want to decode
-     * @param base from 1 to 255
+     * @param base radix of encoding from [2 to 254]
-     * @param digits char[base] array of digits
+     * @param digits alphabet of encoding
-     * @return estimated size after decoding
+     * @return estimated size after decoding (obviously larger)
      * @throw basen::Exception(BASE) if base < 2 || base > 254
      * @throw basen::Exception(OVERFLOW) if if there is an overflow
      */
@@ -47,19 +45,9 @@ namespace baseN
 
     /**
      * @param data [in] pointer to data which you want encode
-     * @param data_size
      * @param str [out] pointer to string for encoded data output
-     * @param str_size
+     * @param base radix of encoding from [2 to 254]
-     * @param base from 1 to 255
+     * @param digits alphabet of encoding
-     * @param digits char[base] array of digits
-     * @code{cpp}
-     * std::vector<uint8_t> data;
-     * std::string str(baseN::sizeEncoded(data, 58), ' ');
-     *
-     * auto offset = baseN::encode(data.data(), data.size(), str.data(), str.size(), 58, base58::digits);
-     * // deleting leading zeroes
-     * str.erase(str.begin(), str.begin() + offset);
-     * @endcode
      * @return number of leading chars, which should be trimmed
      * @throw basen::Exception(BASE) if base < 2 || base > 254
      * @warning contain leading zeros, returns count of them
@@ -67,32 +55,19 @@ namespace baseN
     size_t encode(const uint8_t *data, size_t data_size, char *str, size_t str_size, uint8_t base, const char *digits);
     /**
      * @param data vector or span of data which you want to encode
-     * @param base from 1 to 255
+     * @param base radix of encoding from [2 to 254]
-     * @param digits char[base] array of digits
+     * @param digits alphabet of encoding
-     * @code{cpp}
-     * std::vector<uint8_t> data;
-     * auto str = baseN::encode(data, 58, base58::digits);
-     * @endcode
      * @return encoded string
+     * @throw basen::Exception(BASE) if base < 2 || base > 254
      */
     std::string encode(std::span<const uint8_t> data, uint8_t base, const char *digits);
 
     /**
      * @param str [in] pointer to string which you want decode
-     * @param str_size
      * @param data [out] pointer to data for encoded string output
-     * @param data_size
+     * @param base radix of encoding from [2 to 254]
-     * @param base from 1 to 255
+     * @param digits alphabet of encoding
-     * @param digits char[base] array of digits
+     * @param map map of alphabet of encoding, which is returned by baseN::digitsMap
-     * @param map uint8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. 255 if there is no symbol
-     * @code{cpp}
-     * std::string str;
-     * std::vector<uint8_t> data(baseN::sizeDecoded(str, 58));
-     *
-     * auto offset = baseN::decode(str.data(), str.size(), data.data(), data.size(), 58, base58::digits, base58::map);
-     * // deleting leading zeroes
-     * data.erase(data.begin(), data.begin() + offset);
-     * @endcode
      * @return number of leading chars, which should be trimmed
      * @throw basen::Exception(BASE) if base < 2 || base > 254
      * @throw basen::Exception(OUT_OF_ALPH) if out of alphabet
@@ -101,14 +76,12 @@ namespace baseN
     size_t decode(const char *str, size_t str_size, uint8_t *data, size_t data_size, uint8_t base, const char *digits, const uint8_t *map);
     /**
      * @param str string or string_view which you want to decode
-     * @param base from 1 to 255
+     * @param base radix of encoding from [2 to 254]
-     * @param digits char[base] array of digits
+     * @param digits alphabet of encoding
-     * @param map uint8_t[256] array, where at an index equal to the value of the symbol is the index of this symbol in the digits array. 255 if there is no symbol
+     * @param map map of alphabet of encoding, which is returned by baseN::digitsMap
-     * @code{cpp}
-     * std::string str;
-     * auto data = baseN::decode(str, 58, base58::digits, base58::map);
-     * @endcode
      * @return decoded data
+     * @throw basen::Exception(BASE) if base < 2 || base > 254
+     * @throw basen::Exception(OUT_OF_ALPH) if out of alphabet
      */
     std::vector<uint8_t> decode(std::string_view str, uint8_t base, const char *digits, const uint8_t *map);
 }

include/basen/hex.hpp

@@ -7,31 +7,62 @@
 
 namespace hex
 {
+    /**
+     * @brief lower case chars
+     */
     extern const char digits[17];
     extern const uint8_t map[256];
 
+    /**
+     * @return checks what contains only alphabet chars
+     */
     bool isValid(const char *str, size_t str_size) noexcept;
+    /**
+     * @param str string or string_view which you want to decode
+     * @return checks what contains only alphabet chars
+     */
     bool isValid(std::string_view str) noexcept;
 
     /**
+     * @param data vector or span of data which you want to encode
+     * @return exact size after encoding
      * @throw basen::Exception(OVERFLOW) if there is an overflow
      */
     size_t sizeEncoded(std::span<const uint8_t> data);
+    /**
+     * @param str string or string_view which you want to decode
+     * @return exact size after decoding
+     */
     size_t sizeDecoded(std::string_view str) noexcept;
 
     /**
+     * @param data [in] pointer to data which you want encode
+     * @param str [out] pointer to string for encoded data output
+     * @throw basen::Exception(OVERFLOW) from hex::sizeEncoded
      * @throw basen::Exception(LENGTH) if not enough allocated length
-     * @warning contain leading zeros, returns count of them
      */
     void encode(const uint8_t *data, size_t data_size, char *str, size_t str_size);
+    /**
+     * @param data vector or span of data which you want to encode
+     * @return encoded string
+     * @throw basen::Exception(OVERFLOW) from hex::sizeEncoded
+     * @throw basen::Exception(LENGTH) if not enough allocated length
+     */
     std::string encode(std::span<const uint8_t> data);
 
     /**
+     * @param str [in] pointer to string which you want decode
+     * @param data [out] pointer to data for encoded string output
      * @throw basen::Exception(LENGTH) if not enough allocated length
      * @throw basen::Exception(OUT_OF_ALPH) if out of digits map
      * @throw basen::Exception(PADDING) if str_size %2 != 0 (isn't hex)
-     * @warning contain leading zeros, returns count of them
      */
     void decode(const char *str, size_t str_size, uint8_t *data, size_t data_size);
+    /**
+     * @param str string or string_view which you want to decode
+     * @throw basen::Exception(LENGTH) if not enough allocated length
+     * @throw basen::Exception(OUT_OF_ALPH) if out of digits map
+     * @throw basen::Exception(PADDING) if str_size %2 != 0 (isn't hex)
+     */
     std::vector<uint8_t> decode(std::string_view str);
 }