Adding/Updating comments in public header files.

include/libeosio/WIF.hpp

@@ -28,10 +28,19 @@
 
 namespace libeosio {
 
+/**
+ * Encode an EC private key to WIF String.
+ */
 std::string wif_priv_encode(ec_privkey_t priv);
 
+/**
+ * Encode an EC public key to WIF String.
+ */
 std::string wif_pub_encode(ec_pubkey_t pub);
 
+/**
+ * Prints an EC keypair in WIF format to standard out.
+ */
 void wif_print_key(const struct ec_keypair *key);
 
 } // namespace libeosio

include/libeosio/base58.hpp

@@ -29,16 +29,29 @@
 
 namespace libeosio {
 
+/**
+ * Base58 Encoding functions.
+ */
 std::string base58_encode(const std::string& str);
 std::string base58_encode(const std::vector<unsigned char>& vch);
 std::string base58_encode(const unsigned char* pbegin, const unsigned char* pend);
 
+/**
+ * Returns true if `ch` is a base58 character, false otherwise.
+ */
 bool is_base58(char ch);
 
-// Returns std::string::npos if the string contains only base58 characters
-// Otherwise the position of the first non base58 character is returned.
+/**
+ * Returns std::string::npos if the string contains only base58 characters
+ * Otherwise the position of the first non base58 character is returned.
+ */
 size_t is_base58(const std::string& str);
 
+/**
+ * Strips all non-base58 characters from `str`.
+ * The string is modified in place and the same string is
+ * returned without non-base58 chars.
+ */
 std::string& base58_strip(std::string& str);
 
 } //namespace eoskeygen

include/libeosio/checksum.hpp

@@ -31,10 +31,22 @@
 
 namespace libeosio {
 
+/**
+ * Checksum size (in bytes)
+ */
 #define CHECKSUM_SIZE 4
 
+/**
+ * Checksum datatype
+ */
 typedef std::array<unsigned char, CHECKSUM_SIZE> checksum_t;
 
+/**
+ * Checksum template function.
+ * Template arguments:
+ *  - T: Hash type.
+ *  - F: Hash calculation function, should have the signature `T* F(const unsigned char *, std::size_t, T*)`
+ */
 template <typename T, T* (*F)(const unsigned char *, std::size_t, T*)>
 inline checksum_t checksum(const unsigned char* data, std::size_t len) {
 	checksum_t crc;
@@ -45,6 +57,9 @@ inline checksum_t checksum(const unsigned char* data, std::size_t len) {
 	return crc;
 }
 
+/**
+ * Checksum implementations.
+ */
 #define checksum_sha256 checksum<sha256_t, sha256>
 #define checksum_sha256d checksum<sha256_t, sha256d>
 #define checksum_ripemd160 checksum<ripemd160_t, ripemd160>

include/libeosio/hash.hpp

@@ -29,11 +29,25 @@
 
 namespace libeosio {
 
+/**
+ * sha256 hashing function.
+ * Hashes the content in `data` up to `len` bytes. result is stored in `out`.
+ * Returns the sampe pointer as `out`.
+ */
 sha256_t* sha256(const unsigned char *data, std::size_t len, sha256_t* out);
 
-// sha256 double.
+/**
+ * sha256 double hashing function.
+ * Hashes the content in `data` up to `len` bytes. result is stored in `out`.
+ * Returns the sampe pointer as `out`.
+ */
 sha256_t* sha256d(const unsigned char *data, std::size_t len, sha256_t* out);
 
+/**
+ * RipeMD160 hashing function.
+ * Hashes the content in `data` up to `len` bytes. result is stored in `out`.
+ * Returns the sampe pointer as `out`.
+ */
 ripemd160_t* ripemd160(const unsigned char *data, std::size_t len, ripemd160_t* out);
 
 } // namespace libeosio

include/libeosio/types.hpp

@@ -28,25 +28,36 @@
 
 namespace libeosio {
 
+/**
+ * Elliptic curve private key size (in bytes)
+ */
 #define EC_PRIVKEY_SIZE 32
 
-/*
- * Compressed format!
- * z||x, where byte z specifies which (of the 2) solutions of the quadratic equation y is.
- * Each cordinate is 32 bytes.
+/**
+ * Elliptic curve public key size (in bytes)
+ *
+ * Compressed format: z||x, where byte z specifies which (of the 2) solutions
+ * of the quadratic equation y is. Each cordinate is 32 bytes.
  */
 #define EC_PUBKEY_SIZE (32 + 1)
 
+/**
+ * Elliptic curve priv/pub key datastructures.
+ */
 typedef std::array<unsigned char, EC_PRIVKEY_SIZE> ec_privkey_t;
 typedef std::array<unsigned char, EC_PUBKEY_SIZE> ec_pubkey_t;
 
+/**
+ * Elliptic curve keypair (public + private)
+ */
 struct ec_keypair {
 	ec_privkey_t secret;
 	ec_pubkey_t pub;
 };
 
-// Hashes.
-
+/**
+ * Hashes
+ */
 typedef struct { unsigned char data[20]; } ripemd160_t;
 typedef struct { unsigned char data[32]; } sha256_t;