changes as per comments in #3991

contracts/eosiolib/action.hpp

@@ -235,7 +235,7 @@ namespace eosio {
        * Construct a new action object with the given action struct
        *
        * @brief Construct a new action object with the given permission, action receiver, action name, action struct
-       * @tparam T  - Type of action struct
+       * @tparam T  - Type of action struct, must be serializable by `pack(...)`
        * @param auth - The permissions that authorizes this action
        * @param a -  The name of the account this action is intended for (action receiver)
        * @param n - The name of the action
@@ -249,7 +249,7 @@ namespace eosio {
        * Construct a new action object with the given action struct
        *
        * @brief Construct a new action object with the given list of permissions, action receiver, action name, action struct
-       * @tparam T  - Type of action struct
+       * @tparam T  - Type of action struct, must be serializable by `pack(...)`
        * @param auths - The list of permissions that authorize this action
        * @param a -  The name of the account this action is intended for (action receiver)
        * @param n - The name of the action

contracts/eosiolib/chain.h

@@ -25,7 +25,7 @@ extern "C" {
      *  @brief Gets the set of active producers.
      *
      *  @param producers - Pointer to a buffer of account names
-     *  @param datalen - Byte length of buffer
+     *  @param datalen - Byte length of buffer, when passed 0 will return the size required to store full output. 
      *
      *  @return uint32_t - Number of bytes actually populated
      *  @pre `producers` is a pointer to a range of memory at least `datalen` bytes long

contracts/eosiolib/privileged.h

@@ -22,14 +22,14 @@ extern "C" {
     * @brief Set the resource limit of an account
     * Set the resource limit of an account
     * @param account - name of the account whose resource limit to be set
-    * @param ram_bytes - ram limit
-    * @param net_weight - net limit
-    * @param cpu_weight - cput limit
+    * @param ram_bytes - ram limit in absolute bytes
+    * @param net_weight - fractionally proportionate net limit of available resources based on (weight / total_weight_of_all_accounts)
+    * @param cpu_weight - fractionally proportionate cpu limit of available resources based on (weight / total_weight_of_all_accounts)
     */
    void set_resource_limits( account_name account, int64_t ram_bytes, int64_t net_weight, int64_t cpu_weight );
 
    /**
-    * Propose the new active producer schedule
+    * Proposes a schedule change, once the block that contains the proposal becomes irreversible, the schedule is promoted to "pending" automatically. Once the block that promotes the schedule is irreversible, the schedule will become "active"
     * @param producer_data - packed data of produce_keys in the appropriate producer schedule order
     * @param producer_data_size - size of the data buffer
     *

contracts/eosiolib/transaction.h

@@ -51,6 +51,7 @@ extern "C" {
      *  @param payer - Account paying for RAM
      *  @param serialized_transaction - Pointer of serialized transaction to be deferred
      *  @param size - Size to reserve
+     *  @param replace_existing - f this is `0` then if the provided sender_id is already in use by an in-flight transaction from this contract, which will be a failing assert. If `1` then transaction will atomically cancel/replace the inflight transaction
      */
      void send_deferred(const uint128_t& sender_id, account_name payer, const char *serialized_transaction, size_t size, uint32_t replace_existing = 0);
 

contracts/eosiolib/varint.hpp

@@ -15,13 +15,14 @@
 /**
  * Variable Length Unsigned Integer. This provides more efficient serialization of 32-bit unsigned int.
  * It serialuzes a 32-bit unsigned integer in as few bytes as possible
- * 
+ * `varuint32` is unsigned and uses [VLQ or Base-128 encoding](https://en.wikipedia.org/wiki/Variable-length_quantity)
+ *
  * @brief Variable Length Unsigned Integer
  */
 struct unsigned_int {
     /**
      * Construct a new unsigned int object
-     * 
+     *
      * @brief Construct a new unsigned int object
      * @param v - Source
      */
@@ -29,7 +30,7 @@ struct unsigned_int {
 
     /**
      * Construct a new unsigned int object from a type that is convertible to uint32_t
-     * 
+     *
      * @brief Construct a new unsigned int object
      * @tparam T - Type of the source
      * @param v - Source
@@ -52,23 +53,23 @@ struct unsigned_int {
 
     /**
      * Assign 32-bit unsigned integer
-     * 
+     *
      * @brief Assignment operator
      * @param v - Soruce
      * @return unsigned_int& - Reference to this object
      */
     unsigned_int& operator=( uint32_t v ) { value = v; return *this; }
-    
+
     /**
      * Contained value
-     * 
+     *
      * @brief Contained value
      */
     uint32_t value;
 
     /**
      * Check equality between a unsigned_int object and 32-bit unsigned integer
-     * 
+     *
      * @brief Equality Operator
      * @param i - unsigned_int object to compare
      * @param v - 32-bit unsigned integer to compare
@@ -79,10 +80,10 @@ struct unsigned_int {
 
     /**
      * Check equality between 32-bit unsigned integer and  a unsigned_int object
-     * 
+     *
      * @brief Equality Operator
      * @param i - 32-bit unsigned integer to compare
-     * @param v - unsigned_int object to compare 
+     * @param v - unsigned_int object to compare
      * @return true - if equal
      * @return false - otherwise
      */
@@ -90,7 +91,7 @@ struct unsigned_int {
 
     /**
      * Check equality between two unsigned_int objects
-     * 
+     *
      * @brief Equality Operator
      * @param i - First unsigned_int object to compare
      * @param v - Second unsigned_int object to compare
@@ -101,7 +102,7 @@ struct unsigned_int {
 
     /**
      * Check inequality between a unsigned_int object and 32-bit unsigned integer
-     * 
+     *
      * @brief Inequality Operator
      * @param i - unsigned_int object to compare
      * @param v - 32-bit unsigned integer to compare
@@ -112,10 +113,10 @@ struct unsigned_int {
 
     /**
      * Check inequality between 32-bit unsigned integer and  a unsigned_int object
-     * 
+     *
      * @brief Equality Operator
      * @param i - 32-bit unsigned integer to compare
-     * @param v - unsigned_int object to compare 
+     * @param v - unsigned_int object to compare
      * @return true - if unequal
      * @return false - otherwise
      */
@@ -123,7 +124,7 @@ struct unsigned_int {
 
     /**
      * Check inequality between two unsigned_int objects
-     * 
+     *
      * @brief Inequality Operator
      * @param i - First unsigned_int object to compare
      * @param v - Second unsigned_int object to compare
@@ -134,7 +135,7 @@ struct unsigned_int {
 
     /**
      * Check if the given unsigned_int object is less than the given 32-bit unsigned integer
-     * 
+     *
      * @brief Less than Operator
      * @param i - unsigned_int object to compare
      * @param v - 32-bit unsigned integer to compare
@@ -145,10 +146,10 @@ struct unsigned_int {
 
     /**
      * Check if the given 32-bit unsigned integer is less than the given unsigned_int object
-     * 
+     *
      * @brief Less than Operator
      * @param i - 32-bit unsigned integer to compare
-     * @param v - unsigned_int object to compare 
+     * @param v - unsigned_int object to compare
      * @return true -  if i less than v
      * @return false - otherwise
      */
@@ -156,7 +157,7 @@ struct unsigned_int {
 
     /**
      * Check if the first given unsigned_int is less than the second given unsigned_int object
-     * 
+     *
      * @brief Less than Operator
      * @param i - First unsigned_int object to compare
      * @param v - Second unsigned_int object to compare
@@ -167,7 +168,7 @@ struct unsigned_int {
 
     /**
      * Check if the given unsigned_int object is greater or equal to the given 32-bit unsigned integer
-     * 
+     *
      * @brief Greater or Equal to Operator
      * @param i - unsigned_int object to compare
      * @param v - 32-bit unsigned integer to compare
@@ -178,7 +179,7 @@ struct unsigned_int {
 
     /**
      * Check if the given 32-bit unsigned integer is greater or equal to the given unsigned_int object
-     * 
+     *
      * @brief Greater or Equal to Operator
      * @param i - 32-bit unsigned integer to compare
      * @param v - unsigned_int object to compare
@@ -189,7 +190,7 @@ struct unsigned_int {
 
     /**
      * Check if the first given unsigned_int is greater or equal to the second given unsigned_int object
-     * 
+     *
      * @brief Greater or Equal to Operator
      * @param i - First unsigned_int object to compare
      * @param v - Second unsigned_int object to compare
@@ -200,11 +201,11 @@ struct unsigned_int {
 
     /**
      *  Serialize an unsigned_int object with as few bytes as possible
-     * 
+     *
      *  @brief Serialize an unsigned_int object with as few bytes as possible
      *  @param ds - The stream to write
      *  @param v - The value to serialize
-     *  @tparam DataStream - Type of datastream 
+     *  @tparam DataStream - Type of datastream
      *  @return DataStream& - Reference to the datastream
      */
     template<typename DataStream>
@@ -221,7 +222,7 @@ struct unsigned_int {
 
     /**
      *  Deserialize an unsigned_int object
-     * 
+     *
      *  @brief Deserialize an unsigned_int object
      *  @param ds - The stream to read
      *  @param vi - The destination for deserialized value
@@ -243,15 +244,15 @@ struct unsigned_int {
 
 /**
  * Variable Length Signed Integer. This provides more efficient serialization of 32-bit signed int.
- * It serialuzes a 32-bit signed integer in as few bytes as possible.
- * It uses the google protobuf algorithm for seralizing signed numbers
- * 
+ * It serializes a 32-bit signed integer in as few bytes as possible.
+ * `varint32' is signed and uses [Zig-Zag encoding](https://developers.google.com/protocol-buffers/docs/encoding#signed-integers)
+ *
  * @brief Variable Length Signed Integer
  */
 struct signed_int {
     /**
      * Construct a new signed int object
-     * 
+     *
      * @brief Construct a new signed int object
      * @param v - Source
      */
@@ -260,7 +261,7 @@ struct signed_int {
     /**
      * Convert signed_int to primitive 32-bit signed integer
      * @brief Conversion operator
-     * 
+     *
      * @return int32_t - The converted result
      */
     operator int32_t()const { return value; }
@@ -268,7 +269,7 @@ struct signed_int {
 
     /**
      * Assign an object that is convertible to int32_t
-     * 
+     *
      * @brief Assignment operator
      * @tparam T - Type of the assignment object
      * @param v - Source
@@ -279,7 +280,7 @@ struct signed_int {
 
     /**
      * Increment operator
-     * 
+     *
      * @brief Increment operator
      * @return signed_int - New signed_int with value incremented from the current object's value
      */
@@ -287,7 +288,7 @@ struct signed_int {
 
     /**
      * Increment operator
-     * 
+     *
      * @brief Increment operator
      * @return signed_int - Reference to current object
      */
@@ -295,14 +296,14 @@ struct signed_int {
 
     /**
      * Contained value
-     * 
+     *
      * @brief Contained value
      */
     int32_t value;
 
     /**
      * Check equality between a signed_int object and 32-bit integer
-     * 
+     *
      * @brief Equality Operator
      * @param i - signed_int object to compare
      * @param v - 32-bit integer to compare
@@ -313,10 +314,10 @@ struct signed_int {
 
     /**
      * Check equality between 32-bit integer and  a signed_int object
-     * 
+     *
      * @brief Equality Operator
      * @param i - 32-bit integer to compare
-     * @param v - signed_int object to compare 
+     * @param v - signed_int object to compare
      * @return true - if equal
      * @return false - otherwise
      */
@@ -324,7 +325,7 @@ struct signed_int {
 
     /**
      * Check equality between two signed_int objects
-     * 
+     *
      * @brief Equality Operator
      * @param i - First signed_int object to compare
      * @param v - Second signed_int object to compare
@@ -336,7 +337,7 @@ struct signed_int {
 
     /**
      * Check inequality between a signed_int object and 32-bit integer
-     * 
+     *
      * @brief Inequality Operator
      * @param i - signed_int object to compare
      * @param v - 32-bit integer to compare
@@ -347,10 +348,10 @@ struct signed_int {
 
     /**
      * Check inequality between 32-bit integer and  a signed_int object
-     * 
+     *
      * @brief Equality Operator
      * @param i - 32-bit integer to compare
-     * @param v - signed_int object to compare 
+     * @param v - signed_int object to compare
      * @return true - if unequal
      * @return false - otherwise
      */
@@ -358,7 +359,7 @@ struct signed_int {
 
     /**
      * Check inequality between two signed_int objects
-     * 
+     *
      * @brief Inequality Operator
      * @param i - First signed_int object to compare
      * @param v - Second signed_int object to compare
@@ -369,7 +370,7 @@ struct signed_int {
 
     /**
      * Check if the given signed_int object is less than the given 32-bit integer
-     * 
+     *
      * @brief Less than Operator
      * @param i - signed_int object to compare
      * @param v - 32-bit integer to compare
@@ -380,10 +381,10 @@ struct signed_int {
 
     /**
      * Check if the given 32-bit integer is less than the given signed_int object
-     * 
+     *
      * @brief Less than Operator
      * @param i - 32-bit integer to compare
-     * @param v - signed_int object to compare 
+     * @param v - signed_int object to compare
      * @return true -  if i less than v
      * @return false - otherwise
      */
@@ -391,7 +392,7 @@ struct signed_int {
 
     /**
      * Check if the first given signed_int is less than the second given signed_int object
-     * 
+     *
      * @brief Less than Operator
      * @param i - First signed_int object to compare
      * @param v - Second signed_int object to compare
@@ -403,7 +404,7 @@ struct signed_int {
 
     /**
      * Check if the given signed_int object is greater or equal to the given 32-bit integer
-     * 
+     *
      * @brief Greater or Equal to Operator
      * @param i - signed_int object to compare
      * @param v - 32-bit integer to compare
@@ -414,7 +415,7 @@ struct signed_int {
 
     /**
      * Check if the given 32-bit integer is greater or equal to the given signed_int object
-     * 
+     *
      * @brief Greater or Equal to Operator
      * @param i - 32-bit integer to compare
      * @param v - signed_int object to compare
@@ -425,7 +426,7 @@ struct signed_int {
 
     /**
      * Check if the first given signed_int is greater or equal to the second given signed_int object
-     * 
+     *
      * @brief Greater or Equal to Operator
      * @param i - First signed_int object to compare
      * @param v - Second signed_int object to compare
@@ -437,11 +438,11 @@ struct signed_int {
 
     /**
      *  Serialize an signed_int object with as few bytes as possible
-     * 
+     *
      *  @brief Serialize an signed_int object with as few bytes as possible
      *  @param ds - The stream to write
      *  @param v - The value to serialize
-     *  @tparam DataStream - Type of datastream 
+     *  @tparam DataStream - Type of datastream
      *  @return DataStream& - Reference to the datastream
      */
     template<typename DataStream>
@@ -458,7 +459,7 @@ struct signed_int {
 
     /**
      *  Deserialize an signed_int object
-     * 
+     *
      *  @brief Deserialize an signed_int object
      *  @param ds - The stream to read
      *  @param vi - The destination for deserialized value