Docs and whitespace cleanup

libraries/chain/include/eos/chain/protocol/transaction.hpp

@@ -32,56 +32,60 @@ namespace eos { namespace chain {
    /**
     * @defgroup transactions Transactions
     *
-    * All transactions are sets of messages that must be applied atomically (all succeed or all fail). 
-    * Transactions must refer to a recent block that defines the context of the operation so that they 
-    * assert a known state-precondition assumed by the transaction signers.
+    * All transactions are sets of messages that must be applied atomically (all succeed or all fail). Transactions
+    * must refer to a recent block that defines the context of the operation so that they assert a known
+    * state-precondition assumed by the transaction signers.
     *
-    * Rather than specify a full block number, we only specify the lower 16 bits of the block number 
-    * which means you can reference any block within the last 65,536 blocks which is 2.2 days with 
-    * a 3 second block interval.
+    * Rather than specify a full block number, we only specify the lower 16 bits of the block number which means you
+    * can reference any block within the last 65,536 blocks which is 2.2 days with a 3 second block interval.
     *
-    * All transactions must expire so that the network does not have to maintain a 
-    * permanent record of all transactions ever published.  A transaction may not have an 
-    * expiration date too far in the future because this would require keeping too much 
-    * transaction history in memory.
+    * All transactions must expire so that the network does not have to maintain a permanent record of all transactions
+    * ever published. A transaction may not have an expiration date too far in the future because this would require
+    * keeping too much transaction history in memory.
     *
     * The block prefix is the first 4 bytes of the block hash of the reference block number, which is the second 4
     * bytes of the @ref block_id_type (the first 4 bytes of the block ID are the block number)
     *
-    * Note: A transaction which selects a reference block cannot be migrated between forks outside the period of
-    * ref_block_num.time to (ref_block_num.time + rel_exp * interval). This fact can be used to protect market orders
-    * which should specify a relatively short re-org window of perhaps less than 1 minute. Normal payments should
-    * probably have a longer re-org window to ensure their transaction can still go through in the event of a momentary
-    * disruption in service.
-    *
     * @note It is not recommended to set the @ref ref_block_num, @ref ref_block_prefix, and @ref expiration
-    * fields manually. Call the appropriate overload of @ref set_expiration instead.
+    * fields manually. Call @ref set_expiration instead.
     *
     * @{
     */
 
    /**
-    *  @brief groups operations that should be applied atomically
+    * @brief A transaction is a group of messages that should be applied atomically
+    *
+    * All interactions the wider world has with the blockchain take place through transactions. To interact with the
+    * blockchain, a transaction is created containing messages. The messages specify the changes to be made to the
+    * blockchain, and the authorization required to execute the transaction is determined by the messages it contains.
+    * All messages in a transaction are executed in order and atomically; i.e. if any message in a transaction is
+    * processed, all are, in order, without any other actions taking place between adjacent messages.
+    *
+    * In practice, unrelated transactions and messages may be evaluated in parallel, but it is guaranteed that this
+    * will not be done with transactions which interact with eachother or the same accounts.
     */
    struct transaction
    {
       /**
-       * Least significant 16 bits from the reference block number.
+       * Least significant 16 bits from the reference block's number
        */
       uint16_t ref_block_num = 0;
       /**
-       * The first non-block-number 32-bits of the reference block ID. Recall that block IDs have 32 bits of block
+       * The first non-block-number 32-bits of the reference block's ID
+       *
+       * Recall that block IDs have 32 bits of block
        * number followed by the actual block hash, so this field should be set using the second 32 bits in the
        * @ref block_id_type
        */
       uint32_t ref_block_prefix = 0;
-
       /**
-       * This field specifies the absolute expiration for this transaction.
+       * This field specifies the absolute expiration time for this transaction
        */
       fc::time_point_sec expiration;
 
-      /// The messages in this transaction
+      /**
+       * The messages in this transaction
+       */
       vector<message> messages;
 
       /// Calculate the digest for a transaction
@@ -89,10 +93,10 @@ namespace eos { namespace chain {
       transaction_id_type id()const;
       void                validate() const;
       /// Calculate the digest used for signature validation
-      digest_type         sig_digest( const chain_id_type& chain_id )const;
+      digest_type         sig_digest(const chain_id_type& chain_id)const;
 
-      void set_expiration( fc::time_point_sec expiration_time );
-      void set_reference_block( const block_id_type& reference_block );
+      void set_expiration(fc::time_point_sec expiration_time);
+      void set_reference_block(const block_id_type& reference_block);
    };
 
    /**
@@ -113,24 +117,27 @@ namespace eos { namespace chain {
       /// The account authorizing the transaction
       account_name authorizing_account;
       /// The privileges being invoked to authorize the transaction
-      privilege_class level;
+      privilege_class privileges;
    };
 
    /**
-    *  @brief adds a signature to a transaction
+    * @brief A transaction with signatures
+    *
+    * signed_transaction is a transaction with an additional manifest of authorizations included with the transaction,
+    * and the signatures backing those authorizations.
     */
    struct signed_transaction : public transaction
    {
-      signed_transaction( const transaction& trx = transaction() )
+      signed_transaction(const transaction& trx = transaction())
          : transaction(trx){}
 
       /** signs and appends to signatures */
-      const signature_type& sign( const private_key_type& key, const chain_id_type& chain_id );
+      const signature_type& sign(const private_key_type& key, const chain_id_type& chain_id);
 
       /** returns signature but does not append */
-      signature_type sign( const private_key_type& key, const chain_id_type& chain_id )const;
+      signature_type sign(const private_key_type& key, const chain_id_type& chain_id)const;
 
-      flat_set<public_key_type> get_signature_keys( const chain_id_type& chain_id )const;
+      flat_set<public_key_type> get_signature_keys(const chain_id_type& chain_id)const;
 
       /**
        * @brief This is the list of signatures that are provided for this transaction
@@ -149,8 +156,10 @@ namespace eos { namespace chain {
        */
       vector<authorization> provided_authorizations;
 
-      /// Removes all messages and signatures
-      void clear() { messages.clear(); signatures.clear(); }
+      /**
+       * Removes all messages, signatures, and authorizations
+       */
+      void clear() { messages.clear(); signatures.clear(); provided_authorizations.clear(); }
 
       digest_type merkle_digest()const;
    };
@@ -159,5 +168,6 @@ namespace eos { namespace chain {
 
 } } // eos::chain
 
-FC_REFLECT( eos::chain::transaction, (ref_block_num)(ref_block_prefix)(expiration)(messages) )
-FC_REFLECT_DERIVED( eos::chain::signed_transaction, (eos::chain::transaction), (signatures) )
+FC_REFLECT(eos::chain::transaction, (ref_block_num)(ref_block_prefix)(expiration)(messages))
+FC_REFLECT(eos::chain::authorization, (authorizing_account)(privileges))
+FC_REFLECT_DERIVED(eos::chain::signed_transaction, (eos::chain::transaction), (signatures))

libraries/chain/protocol/transaction.cpp

@@ -75,7 +75,7 @@ signature_type eos::chain::signed_transaction::sign(const private_key_type& key,
 
 void transaction::set_expiration( fc::time_point_sec expiration_time )
 {
-    expiration = expiration_time;
+   expiration = expiration_time;
 }
 
 void transaction::set_reference_block( const block_id_type& reference_block )