Fix generate_api_documentation.pl to properly parse DoxyDocs and restore full help text in cli wallet

prandnum commented

2022-09-08 04:06:27 +00:00

(Migrated from gitlab.com)

Currently the help on get_son_wallet_by_time_point command doesn't give an example of the time format to be used. Please provide some examples in the "gethelp get_son_wallet_by_time_point" output for all the supported date time formats.

unlocked >>> gethelp get_son_wallet_by_time_point
gethelp get_son_wallet_by_time_point



Returns
    SON wallet object, for the wallet that was active for a given time
	point

unlocked >>>

Currently the help on get_son_wallet_by_time_point command doesn't give an example of the time format to be used. Please provide some examples in the "gethelp get_son_wallet_by_time_point" output for all the supported date time formats. ``` unlocked >>> gethelp get_son_wallet_by_time_point gethelp get_son_wallet_by_time_point Returns SON wallet object, for the wallet that was active for a given time point unlocked >>> ```

prandnum commented

2022-09-08 04:06:44 +00:00

(Migrated from gitlab.com)

@bobinson @serkixenos

CC: @tai.sama

@bobinson @serkixenos CC: @tai.sama

serkixenos commented

2022-09-12 21:49:58 +00:00

(Migrated from gitlab.com)

The cli wallet help is generated from doxygen comments in the source file.

Doxygen config file
https://gitlab.com/PBSA/peerplays/-/blob/develop/libraries/wallet/Doxyfile.in

Script to parse doxygen comments and create api_documenatation.cpp containing help text for cli wallet
https://gitlab.com/PBSA/peerplays/-/blob/develop/libraries/wallet/generate_api_documentation.pl

Intermediate file created by doxygen
DoxyDocs.pm

api_documentation.cpp created by running generate_api_documentation.pl on wallet.hpp
api_documentation.cpp

The cli wallet help is generated from doxygen comments in the source file. Related files: Source code file with doxygen comments https://gitlab.com/PBSA/peerplays/-/blob/develop/libraries/wallet/include/graphene/wallet/wallet.hpp Doxygen config file https://gitlab.com/PBSA/peerplays/-/blob/develop/libraries/wallet/Doxyfile.in Script to parse doxygen comments and create api_documenatation.cpp containing help text for cli wallet https://gitlab.com/PBSA/peerplays/-/blob/develop/libraries/wallet/generate_api_documentation.pl Intermediate file created by doxygen [DoxyDocs.pm](/uploads/d2ffc0479df72bc48647401837e7461f/DoxyDocs.pm) api_documentation.cpp created by running generate_api_documentation.pl on wallet.hpp [api_documentation.cpp](/uploads/5e086c8678053ac6a30c2426c7f6bb48/api_documentation.cpp)

serkixenos commented

2022-09-12 21:54:26 +00:00

(Migrated from gitlab.com)

As visible from api_documentation.cpp, the section with parameter descriptions are absent, in each and every data structure. This indicates that generate_api_documentation.pl does not parse DoxyDocs.pm as expected, probably due to the DoxyDocs.pm format change at some point in time (eg after doxygen was updated).

generate_api_documentation.pl should be fixed, to pickup the parameter description and add them to a function description.

As visible from api_documentation.cpp, the section with parameter descriptions are absent, in each and every data structure. This indicates that generate_api_documentation.pl does not parse DoxyDocs.pm as expected, probably due to the DoxyDocs.pm format change at some point in time (eg after doxygen was updated). generate_api_documentation.pl should be fixed, to pickup the parameter description and add them to a function description.

serkixenos commented

2022-09-12 21:55:42 +00:00

(Migrated from gitlab.com)

assigned to @timur.5

serkixenos commented

2022-09-13 22:53:07 +00:00

(Migrated from gitlab.com)

mentioned in issue #430

serkixenos commented

2022-09-13 22:58:11 +00:00

(Migrated from gitlab.com)

Renamed to reflect the actual problem causing missing help text from cli wallet

serkixenos commented

2022-09-13 22:59:35 +00:00

(Migrated from gitlab.com)

changed title from {-improve the get_son_wallet_by_time_point command documentation-} to {+Fix generate_api_documentation.pl to properly parse DoxyDocs and restore full help text in cli wallet+}

changed title from **{-improve the get_son_wallet_by_time_point command documentation-}** to **{+Fix generate_api_documentation.pl to properly parse DoxyDocs and restore full help text in cli wallet+}**

timur.5 commented

2022-09-15 13:32:56 +00:00

(Migrated from gitlab.com)

added #437 as child task

timur.5 commented

2022-09-15 13:34:50 +00:00

(Migrated from gitlab.com)

added #438 as child task

timur.5 commented

2022-09-15 13:35:05 +00:00

(Migrated from gitlab.com)

added #439 as child task

timur.5 commented

2022-09-15 13:35:11 +00:00

(Migrated from gitlab.com)

removed child task #439

timur.5 commented

2022-09-15 13:35:38 +00:00

(Migrated from gitlab.com)

added #440 as child task

timur.5 commented

2022-09-15 13:36:08 +00:00

(Migrated from gitlab.com)

added #441 as child task

timur.5 commented

2022-09-15 13:36:39 +00:00

(Migrated from gitlab.com)

added #442 as child task

timur.5 commented

2022-09-15 13:36:46 +00:00

(Migrated from gitlab.com)

added #443 as child task

timur.5 commented

2022-09-15 13:38:02 +00:00

(Migrated from gitlab.com)

added #444 as child task

timur.5 commented

2022-09-15 13:38:36 +00:00

(Migrated from gitlab.com)

added #445 as child task

timur.5 commented

2022-09-15 13:38:40 +00:00

(Migrated from gitlab.com)

removed child task #445

timur.5 commented

2022-09-15 13:38:52 +00:00

(Migrated from gitlab.com)

added #446 as child task

timur.5 commented

2022-09-15 14:13:59 +00:00

(Migrated from gitlab.com)

Now it'll be:

new >>> gethelp list_accounts
gethelp list_accounts

Lists all accounts registered in the blockchain. This returns a list of all account names and their account ids, sorted by account name.

Use the 'lowerbound' and limit parameters to page through the list. To
retrieve all accounts, start by setting 'lowerbound' to the empty string
'""', and then each iteration, pass the last account name returned as the
'lowerbound' for the next 'list_accounts()' call.

Command:
    list_accounts lowerbound limit

Parameters:
    lowerbound (string): the name of the first account to return. If the
        named account does not exist, the list will start at the account
        that comes after 'lowerbound'
    limit (integer): the maximum number of accounts to return (max: 1000)

Returns:
    a list of accounts mapping account names to account ids

Now it'll be: ``` new >>> gethelp list_accounts gethelp list_accounts Lists all accounts registered in the blockchain. This returns a list of all account names and their account ids, sorted by account name. Use the 'lowerbound' and limit parameters to page through the list. To retrieve all accounts, start by setting 'lowerbound' to the empty string '""', and then each iteration, pass the last account name returned as the 'lowerbound' for the next 'list_accounts()' call. Command: list_accounts lowerbound limit Parameters: lowerbound (string): the name of the first account to return. If the named account does not exist, the list will start at the account that comes after 'lowerbound' limit (integer): the maximum number of accounts to return (max: 1000) Returns: a list of accounts mapping account names to account ids ```

timur.5 commented

2022-09-15 14:47:19 +00:00

(Migrated from gitlab.com)

Generating neat docs requires
that the first comment line (most vital, depicting API purpose)
be followed by a blank line:

Good:

      /** Returns the block chain's rapidly-changing properties.
       *
       * The returned object contains information that changes every block interval
       * such as the head block number, the next witness, etc.

Bad:

      /** Returns the block chain's rapidly-changing properties.
       * The returned object contains information that changes every block interval
       * such as the head block number, the next witness, etc.

However, it is even better to use explicit '@brief' label instead of separation:

      /**
       * @brief Get SON wallet that was active for a given time point
       * Blah-blah.
       * Blah-blah.
       * @param time_point Time point
       ...
       */
      optional<son_wallet_object> get_son_wallet_by_time_point(time_point_sec time_point);

Generating neat docs requires that the first comment line (most vital, depicting API purpose) be followed by a blank line: Good: ``` /** Returns the block chain's rapidly-changing properties. * * The returned object contains information that changes every block interval * such as the head block number, the next witness, etc. ``` Bad: ``` /** Returns the block chain's rapidly-changing properties. * The returned object contains information that changes every block interval * such as the head block number, the next witness, etc. ``` However, it is even better to use explicit '@brief' label instead of separation: ``` /** * @brief Get SON wallet that was active for a given time point * Blah-blah. * Blah-blah. * @param time_point Time point ... */ optional<son_wallet_object> get_son_wallet_by_time_point(time_point_sec time_point); ```

serkixenos commented

2022-09-15 15:09:57 +00:00

(Migrated from gitlab.com)

assigned to @serkixenos

serkixenos commented

2022-09-16 02:44:40 +00:00

(Migrated from gitlab.com)

assigned to @prandnum

serkixenos commented

2022-09-16 02:44:53 +00:00

(Migrated from gitlab.com)

assigned to @wsalloum

serkixenos commented

2022-09-16 02:45:01 +00:00

(Migrated from gitlab.com)

removed child task #446

serkixenos commented

2022-09-16 02:45:04 +00:00

(Migrated from gitlab.com)

removed child task #444

serkixenos commented

2022-09-16 02:45:07 +00:00

(Migrated from gitlab.com)

added #444 as child task

serkixenos commented

2022-09-16 02:45:07 +00:00

(Migrated from gitlab.com)

added #446 as child task

timur.5 commented

2022-09-16 10:46:43 +00:00

(Migrated from gitlab.com)

Test instructions:

Just try "gethelp" on as many API's as possible
and see if the help text is understandable and formatted well.

Test instructions: Just try "gethelp" on as many API's as possible and see if the help text is understandable and formatted well.

wsalloum commented

2022-09-20 10:44:12 +00:00

(Migrated from gitlab.com)

List of the commands that are not well formatted

create_account_role
create_bid
create_custom_permission
create_worker
create_account_with_brain_key
create_lottery
create_asset
create_custom_account_authority
create_offer
update_asset_feed_producers
update_account_role
update_custom_account_authority
update_custom_permission
transfer
list_buy_offers
list_event_groups
list_offer_history
list_betting_market_groups
list_committee_members
list_events_in_group
list_offers
list_sports
list_betting_markets
list_core_accounts
list_sell_offers
get_events_containing_sub_string
get_global_betting_statistics
get_key_label
get_account_lotteries
get_account_roles_by_owner
get_limit_orders
get_active_custom_account_authorities_by_operation
get_lotteries
get_lottery_balance
get_total_matched_bet_amount_for_betting_market_group
get_market_history
get_matched_bets_for_bettor
get_tournaments
get_all_matched_bets_for_bettor
get_tournaments_by_state
get_all_unmatched_bets_for_bettor
get_offer_history_by_bidder
get_offer_history_by_issuer
get_offer_history_by_item
get_unmatched_bets_for_bettor
get_offers_by_issuer
get_offers_by_item
get_block
get_order_book
get_blocks
get_private_key
get_call_orders
get_custom_account_authorities
get_public_key
get_custom_account_authorities_by_permission_id
get_custom_account_authorities_by_permission_name
get_settle_orders
get_custom_permission_by_name
get_custom_permissions
set_key_label
set_fees_on_builder_transaction
set_password
settle_asset
sign_builder_transaction

List of the commands that are not well formatted ``` create_account_role create_bid create_custom_permission create_worker create_account_with_brain_key create_lottery create_asset create_custom_account_authority create_offer update_asset_feed_producers update_account_role update_custom_account_authority update_custom_permission transfer list_buy_offers list_event_groups list_offer_history list_betting_market_groups list_committee_members list_events_in_group list_offers list_sports list_betting_markets list_core_accounts list_sell_offers get_events_containing_sub_string get_global_betting_statistics get_key_label get_account_lotteries get_account_roles_by_owner get_limit_orders get_active_custom_account_authorities_by_operation get_lotteries get_lottery_balance get_total_matched_bet_amount_for_betting_market_group get_market_history get_matched_bets_for_bettor get_tournaments get_all_matched_bets_for_bettor get_tournaments_by_state get_all_unmatched_bets_for_bettor get_offer_history_by_bidder get_offer_history_by_issuer get_offer_history_by_item get_unmatched_bets_for_bettor get_offers_by_issuer get_offers_by_item get_block get_order_book get_blocks get_private_key get_call_orders get_custom_account_authorities get_public_key get_custom_account_authorities_by_permission_id get_custom_account_authorities_by_permission_name get_settle_orders get_custom_permission_by_name get_custom_permissions set_key_label set_fees_on_builder_transaction set_password settle_asset sign_builder_transaction ```

wsalloum (Migrated from gitlab.com) closed this issue

2022-09-20 14:23:45 +00:00

Fix generate_api_documentation.pl to properly parse DoxyDocs and restore full help text in cli wallet #432