Merge pull request #2324 from bitshares/fix-doxygen-warnings

Fix Doxygen warnings, remove some unused code

Doxyfile

@@ -758,7 +758,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = README.md doc/main.dox libraries
+INPUT                  = README.md libraries
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1558,7 +1558,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

libraries/app/application_impl.hxx

@@ -56,7 +56,9 @@ class application_impl : public net::node_delegate
       /**
        * @brief allows the application to validate an item prior to broadcasting to peers.
        *
+       * @param blk_msg the message which contains the block
        * @param sync_mode true if the message was fetched through the sync process, false during normal operation
+       * @param contained_transaction_message_ids container for the transactions to write back into
        * @returns true if this message caused the blockchain to switch forks, false if it did not
        *
        * @throws exception if error validating the item, otherwise the item is safe to broadcast on.

libraries/app/include/graphene/app/api.hpp

@@ -127,38 +127,38 @@ namespace graphene { namespace app {
 
          /**
           * @brief Get operations relevant to the specificed account
-          * @param account_id_or_name The account ID or name whose history should be queried
+          * @param account_name_or_id The account name or ID whose history should be queried
           * @param stop ID of the earliest operation to retrieve
           * @param limit Maximum number of operations to retrieve (must not exceed 100)
           * @param start ID of the most recent operation to retrieve
           * @return A list of operations performed by account, ordered from most recent to oldest.
           */
          vector<operation_history_object> get_account_history(
-            const std::string account_id_or_name,
+            const std::string account_name_or_id,
             operation_history_id_type stop = operation_history_id_type(),
             unsigned limit = 100,
             operation_history_id_type start = operation_history_id_type()
          )const;
 
          /**
           * @brief Get operations relevant to the specified account filtering by operation type
-          * @param account_id_or_name The account ID or name whose history should be queried
+          * @param account_name_or_id The account name or ID whose history should be queried
           * @param operation_types The IDs of the operation we want to get operations in the account
           * ( 0 = transfer , 1 = limit order create, ...)
           * @param start the sequence number where to start looping back throw the history
           * @param limit the max number of entries to return (from start number)
           * @return history_operation_detail
           */
          history_operation_detail get_account_history_by_operations(
-            const std::string account_id_or_name,
+            const std::string account_name_or_id,
             flat_set<uint16_t> operation_types,
             uint32_t start,
             unsigned limit
          )const;
 
          /**
           * @brief Get only asked operations relevant to the specified account
-          * @param account_id_or_name The account ID or name whose history should be queried
+          * @param account_name_or_id The account name or ID whose history should be queried
           * @param operation_type The type of the operation we want to get operations in the account
           * ( 0 = transfer , 1 = limit order create, ...)
           * @param stop ID of the earliest operation to retrieve
@@ -167,7 +167,7 @@ namespace graphene { namespace app {
           * @return A list of operations performed by account, ordered from most recent to oldest.
           */
          vector<operation_history_object> get_account_history_operations(
-            const std::string account_id_or_name,
+            const std::string account_name_or_id,
             int operation_type,
             operation_history_id_type start = operation_history_id_type(),
             operation_history_id_type stop = operation_history_id_type(),
@@ -178,15 +178,15 @@ namespace graphene { namespace app {
           * @brief Get operations relevant to the specified account referenced
           * by an event numbering specific to the account. The current number of operations
           * for the account can be found in the account statistics (or use 0 for start).
-          * @param account_id_or_name The account ID or name whose history should be queried
+          * @param account_name_or_id The account name or ID whose history should be queried
           * @param stop Sequence number of earliest operation. 0 is default and will
           * query 'limit' number of operations.
           * @param limit Maximum number of operations to retrieve (must not exceed 100)
           * @param start Sequence number of the most recent operation to retrieve.
           * 0 is default, which will start querying from the most recent operation.
           * @return A list of operations performed by account, ordered from most recent to oldest.
           */
-         vector<operation_history_object> get_relative_account_history( const std::string account_id_or_name,
+         vector<operation_history_object> get_relative_account_history( const std::string account_name_or_id,
                                                                         uint64_t stop = 0,
                                                                         unsigned limit = 100,
                                                                         uint64_t start = 0) const;
@@ -562,8 +562,8 @@ namespace graphene { namespace app {
          /**
           * @brief Get grouped limit orders in given market.
           *
-          * @param base_asset ID or symbol of asset being sold
-          * @param quote_asset ID or symbol of asset being purchased
+          * @param base_asset symbol or ID of asset being sold
+          * @param quote_asset symbol or ID of asset being purchased
           * @param group Maximum price diff within each order group, have to be one of configured values
           * @param start Optional price to indicate the first order group to retrieve
           * @param limit Maximum number of order groups to retrieve (must not exceed 101)
@@ -593,12 +593,12 @@ namespace graphene { namespace app {
          /**
           * @brief Get all stored objects of an account in a particular catalog
           *
-          * @param account The account ID or name to get info from
+          * @param account_name_or_id The account name or ID to get info from
           * @param catalog Category classification. Each account can store multiple catalogs.
           *
           * @return The vector of objects of the account or empty
           */
-         vector<account_storage_object> get_storage_info(std::string account_id_or_name, std::string catalog)const;
+         vector<account_storage_object> get_storage_info(std::string account_name_or_id, std::string catalog)const;
 
    private:
          application& _app;

libraries/app/include/graphene/app/api_objects.hpp

@@ -191,18 +191,18 @@ FC_REFLECT( graphene::app::full_account,
             (more_data_available)
           )
 
-FC_REFLECT( graphene::app::order, (price)(quote)(base) );
-FC_REFLECT( graphene::app::order_book, (base)(quote)(bids)(asks) );
+FC_REFLECT( graphene::app::order, (price)(quote)(base) )
+FC_REFLECT( graphene::app::order_book, (base)(quote)(bids)(asks) )
 FC_REFLECT( graphene::app::market_ticker,
             (time)(base)(quote)(latest)(lowest_ask)(lowest_ask_base_size)(lowest_ask_quote_size)
-            (highest_bid)(highest_bid_base_size)(highest_bid_quote_size)(percent_change)(base_volume)(quote_volume)(mto_id) );
-FC_REFLECT( graphene::app::market_volume, (time)(base)(quote)(base_volume)(quote_volume) );
+            (highest_bid)(highest_bid_base_size)(highest_bid_quote_size)(percent_change)(base_volume)(quote_volume)(mto_id) )
+FC_REFLECT( graphene::app::market_volume, (time)(base)(quote)(base_volume)(quote_volume) )
 FC_REFLECT( graphene::app::market_trade, (sequence)(date)(price)(amount)(value)(type)
-            (side1_account_id)(side2_account_id));
+            (side1_account_id)(side2_account_id) )
 
 FC_REFLECT_DERIVED( graphene::app::extended_asset_object, (graphene::chain::asset_object),
-                    (total_in_collateral)(total_backing_collateral) );
+                    (total_in_collateral)(total_backing_collateral) )
 
 FC_REFLECT_DERIVED( graphene::app::extended_liquidity_pool_object, (graphene::chain::liquidity_pool_object),
-                    (statistics) );
+                    (statistics) )
 

libraries/app/include/graphene/app/plugin.hpp

@@ -42,7 +42,7 @@ class abstract_plugin
        *
        * Plugins MUST supply a method initialize() which will be called early in the application startup. This method
        * should contain early setup code such as initializing variables, adding indexes to the database, registering
-       * callback methods from the database, adding APIs, etc., as well as applying any options in the @ref options map
+       * callback methods from the database, adding APIs, etc., as well as applying any options in the @p options map
        *
        * This method is called BEFORE the database is open, therefore any routines which require any chain state MUST
        * NOT be called by this method. These routines should be performed in startup() instead.
@@ -120,7 +120,7 @@ class plugin : public abstract_plugin
       application* _app = nullptr;
 };
 
-/// @group Some useful tools for boost::program_options arguments using vectors of JSON strings
+/// @ingroup Some useful tools for boost::program_options arguments using vectors of JSON strings
 /// @{
 template<typename T>
 T dejsonify(const string& s, uint32_t max_depth)

libraries/chain/include/graphene/chain/asset_object.hpp

@@ -34,7 +34,7 @@
  * A prediction market is a specialized BitAsset such that total debt and total collateral are always equal amounts
  * (although asset IDs differ). No margin calls or force settlements may be performed on a prediction market asset. A
  * prediction market is globally settled by the issuer after the event being predicted resolves, thus a prediction
- * market must always have the @ref global_settle permission enabled. The maximum price for global settlement or short
+ * market must always have the @c global_settle permission enabled. The maximum price for global settlement or short
  * sale of a prediction market asset is 1-to-1.
  */
 

libraries/chain/include/graphene/chain/database.hpp

@@ -109,6 +109,7 @@ namespace graphene { namespace chain {
 
          /**
           * @brief Rebuild object graph from block history and open detabase
+          * @param data_dir the path to store the database
           *
           * This method may be called after or instead of @ref database::open, and will rebuild the object graph by
           * replaying blockchain history. When this method exits successfully, the database will be open.
@@ -117,6 +118,7 @@ namespace graphene { namespace chain {
 
          /**
           * @brief wipe Delete database from disk, and potentially the raw chain as well.
+          * @param data_dir the path to store the database
           * @param include_blocks If true, delete the raw chain as well as the database.
           *
           * Will close the database before wiping. Database will be closed when this function returns.
@@ -330,7 +332,7 @@ namespace graphene { namespace chain {
          void deposit_market_fee_vesting_balance(const account_id_type &account_id, const asset &delta);
         /**
           * @brief Retrieve a particular account's market fee vesting balance in a given asset
-          * @param owner Account whose balance should be retrieved
+          * @param account_id Account whose balance should be retrieved
           * @param asset_id ID of the asset to get balance in
           * @return owner's balance in asset
           */
@@ -370,7 +372,8 @@ namespace graphene { namespace chain {
 
          //////////////////// db_market.cpp ////////////////////
 
-         /// @{ @group Market Helpers
+         /// @ingroup Market Helpers
+         /// @{
          void globally_settle_asset( const asset_object& bitasset, const price& settle_price );
          void cancel_settle_order(const force_settlement_object& order, bool create_virtual_op = true);
          void cancel_limit_order(const limit_order_object& order, bool create_virtual_op = true, bool skip_cancel_fee = false);
@@ -387,7 +390,8 @@ namespace graphene { namespace chain {
       public:
          /**
           * @brief Process a new limit order through the markets
-          * @param order The new order to process
+          * @param new_order_object The new order to process
+          * @param allow_black_swan whether to allow a black swan event
           * @return true if order was completely filled; false otherwise
           *
           * This function takes a new limit order, and runs the markets attempting to match it with existing orders
@@ -686,23 +690,4 @@ namespace graphene { namespace chain {
          ///@}
    };
 
-   namespace detail
-   {
-       template<int... Is>
-       struct seq { };
-
-       template<int N, int... Is>
-       struct gen_seq : gen_seq<N - 1, N - 1, Is...> { };
-
-       template<int... Is>
-       struct gen_seq<0, Is...> : seq<Is...> { };
-
-       template<typename T, int... Is>
-       void for_each(T&& t, const account_object& a, seq<Is...>)
-       {
-           auto l = { (std::get<Is>(t)(a), 0)... };
-           (void)l;
-       }
-   }
-
 } }

libraries/chain/include/graphene/chain/withdraw_permission_object.hpp

@@ -36,7 +36,8 @@ namespace graphene { namespace chain {
    * @brief Grants another account authority to withdraw a limited amount of funds per interval
    *
    * The primary purpose of this object is to enable recurring payments on the blockchain. An account which wishes to
-   * process a recurring payment may use a @ref withdraw_permission_claim_operation to reference an object of this type
+   * process a recurring payment may use a @ref graphene::protocol::withdraw_permission_claim_operation
+   * to reference an object of this type
    * and withdraw up to @ref withdrawal_limit from @ref withdraw_from_account. Only @ref authorized_account may do
    * this. Any number of withdrawals may be made so long as the total amount withdrawn per period does not exceed the
    * limit for any given period.

libraries/chain/include/graphene/chain/worker_object.hpp

@@ -48,8 +48,8 @@ class database;
   * To create a new worker type, define a my_new_worker_type struct with a pay_worker method which updates the
   * my_new_worker_type object and/or the database. Create a my_new_worker_type::initializer struct with an init
   * method and any data members necessary to create a new worker of this type. Reflect my_new_worker_type and
-  * my_new_worker_type::initializer into FC's type system, and add them to @ref worker_type and @ref
-  * worker_initializer respectively. Make sure the order of types in @ref worker_type and @ref worker_initializer
+  * my_new_worker_type::initializer into FC's type system, and add them to @ref worker_type and @c
+  * worker_initializer respectively. Make sure the order of types in @ref worker_type and @c worker_initializer
   * remains the same.
   * @{
   */

libraries/net/include/graphene/net/node.hpp

@@ -71,7 +71,9 @@ namespace graphene { namespace net {
          /**
           *  @brief Called when a new block comes in from the network
           *
+          *  @param blk_msg the message which contains the block
           *  @param sync_mode true if the message was fetched through the sync process, false during normal operation
+          *  @param contained_transaction_message_ids container for the transactions to write back into
           *  @returns true if this message caused the blockchain to switch forks, false if it did not
           *
           *  @throws exception if error validating the item, otherwise the item is

libraries/net/include/graphene/net/peer_connection.hpp

@@ -339,4 +339,4 @@ FC_REFLECT_ENUM(graphene::net::peer_connection::connection_negotiation_status, (
                                                                           (closing)
                                                                           (closed) )
 
-FC_REFLECT( graphene::net::peer_connection::timestamped_item_id, (item)(timestamp));
+FC_REFLECT( graphene::net::peer_connection::timestamped_item_id, (item)(timestamp) )

libraries/protocol/account.cpp

@@ -29,20 +29,24 @@ namespace graphene { namespace protocol {
 
 /**
  * Names must comply with the following grammar (RFC 1035):
+ * @code
  * <domain> ::= <subdomain> | " "
  * <subdomain> ::= <label> | <subdomain> "." <label>
  * <label> ::= <letter> [ [ <ldh-str> ] <let-dig> ]
  * <ldh-str> ::= <let-dig-hyp> | <let-dig-hyp> <ldh-str>
  * <let-dig-hyp> ::= <let-dig> | "-"
  * <let-dig> ::= <letter> | <digit>
+ * @endcode
  *
  * Which is equivalent to the following:
  *
+ * @code
  * <domain> ::= <subdomain> | " "
  * <subdomain> ::= <label> ("." <label>)*
  * <label> ::= <letter> [ [ <let-dig-hyp>+ ] <let-dig> ]
  * <let-dig-hyp> ::= <let-dig> | "-"
  * <let-dig> ::= <letter> | <digit>
+ * @endcode
  *
  * I.e. a valid name consists of a dot-separated sequence
  * of one or more labels consisting of the following rules:

libraries/protocol/include/graphene/protocol/account.hpp

@@ -129,8 +129,9 @@ namespace graphene { namespace protocol {
     * @ingroup operations
     * @brief Update an existing account
     *
-    * This operation is used to update an existing account. It can be used to update the authorities, or adjust the options on the account.
-    * See @ref account_object::options for the options which may be updated.
+    * This operation is used to update an existing account. It can be used to update the authorities,
+    * or adjust the options on the account.
+    * See @ref graphene::chain::account_object::options for the options which may be updated.
     */
    struct account_update_operation : public base_operation
    {