{"action":"created","comment":{"url":"https://api.github.com/repos/paritytech/substrate/pulls/comments/264773387","pull_request_review_id":213510044,"id":264773387,"node_id":"MDI0OlB1bGxSZXF1ZXN0UmV2aWV3Q29tbWVudDI2NDc3MzM4Nw==","diff_hunk":"@@ -14,16 +14,131 @@\n // You should have received a copy of the GNU General Public License\n // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.\n \n-//! Balances: Handles setting and retrieval of free balance,\n-//! retrieving total, reserved, and unreserved balances,\n-//! repatriating a reserved balance to a beneficiary account that exists,\n-//! transfering a balance between accounts (when not reserved),\n-//! slashing an account balance, account removal, rewards,\n-//! lookup of an index to reclaim an account (when balance not reserved),\n-//! increasing total stake.\n+//! # Balances Module\n //!\n-//! Implements functions for `Currency`, `LockableCurrency`, `TransferAsset`,\n-//! and `IsDeadAccount` traits.\n+//! ## Overview\n+//!\n+//! The balances module provides functions for:\n+//!\n+//! - Getting and setting free balance\n+//! - Retrieving total, reserved, and unreserved balances\n+//! - Repatriating a reserved balance to a beneficiary account that exists\n+//! - Transfering a balance between accounts (when not reserved)\n+//! - Slashing an account balance\n+//! - Account removal\n+//! - Lookup of an index to reclaim an account\n+//! - Increasing or decreasing total stake\n+//! - Setting and removing locks on chains that implement `LockableCurrency`\n+//!\n+//! ### Terminology\n+//!\n+//! - **Existential Deposit:** The existential deposit is the minimum balance required to create or keep an account open. This prevents \"dust accounts\" from filling storage.\n+//! - **Stake:** The total amount of tokens in existence in a system.\n+//! - **Reaping an account:** The act of removing an account by resetting its nonce, setting its balance to zero, and removing from storage.\n+//! - **Free Balance:** The free balance is the only balance that matters for most operations. When this balance falls below the existential deposit, the account is reaped.\n+//! - **Reserved Balance:** Reserved balance still belongs to the account holder, but is suspended. Reserved balance can still be slashed, but only after all of free balance has been slashed. If the reserved balance falls below the existential deposit then it will be deleted.\n+//! - **Locks:** Locks enable the runtime to lock an account's balance until a specified block number. Only runtimes that implement the `LockableCurrency` trait allow this.\n+//!\n+//! ## Interface\n+//!\n+//! ### Types\n+//!\n+//! - Balance\n+//! - OnFreeBalanceZero\n+//! - OnNewAccount\n+//! - Event\n+//!\n+//! These are [associated types](https://doc.rust-lang.org/book/ch19-03-advanced-traits.html#specifying-placeholder-types-in-trait-definitions-with-associated-types) and must be implemented in your `runtime/src/lib.rs`. For example:\n+//!\n+//! ```ignore\n+//! impl balances::Trait for Runtime {\n+//! \t/// The type for recording an account's balance.\n+//! \ttype Balance = u128;\n+//! \t/// What to do if an account's free balance gets zeroed.\n+//! \ttype OnFreeBalanceZero = ();\n+//! \t/// What to do if a new account is created.\n+//! \ttype OnNewAccount = Indices;\n+//! \t/// The uniquitous event type.\n+//! \ttype Event = Event;\n+//! }\n+//! ```\n+//!\n+//! ### Dispatchable Functions\n+//!\n+//! The `Call` enum is documented here: https://crates.parity.io/srml_balances/enum.Call.html","path":"srml/balances/src/lib.rs","position":62,"original_position":64,"commit_id":"f1b62a48a349e870e9f381156e332e3554e93c9e","original_commit_id":"f1b62a48a349e870e9f381156e332e3554e93c9e","user":{"login":"AmarRSingh","id":25728274,"node_id":"MDQ6VXNlcjI1NzI4Mjc0","avatar_url":"https://avatars2.githubusercontent.com/u/25728274?v=4","gravatar_id":"","url":"https://api.github.com/users/AmarRSingh","html_url":"https://github.com/AmarRSingh","followers_url":"https://api.github.com/users/AmarRSingh/followers","following_url":"https://api.github.com/users/AmarRSingh/following{/other_user}","gists_url":"https://api.github.com/users/AmarRSingh/gists{/gist_id}","starred_url":"https://api.github.com/users/AmarRSingh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/AmarRSingh/subscriptions","organizations_url":"https://api.github.com/users/AmarRSingh/orgs","repos_url":"https://api.github.com/users/AmarRSingh/repos","events_url":"https://api.github.com/users/AmarRSingh/events{/privacy}","received_events_url":"https://api.github.com/users/AmarRSingh/received_events","type":"User","site_admin":false},"body":"It's still markdown so you could've said: [here](https://crates.parity.io/srml_balances/enum.Call.html)","created_at":"2019-03-12T16:40:29Z","updated_at":"2019-03-12T16:40:30Z","html_url":"https://github.com/paritytech/substrate/pull/1943#discussion_r264773387","pull_request_url":"https://api.github.com/repos/paritytech/substrate/pulls/1943","author_association":"NONE","_links":{"self":{"href":"https://api.github.com/repos/paritytech/substrate/pulls/comments/264773387"},"html":{"href":"https://github.com/paritytech/substrate/pull/1943#discussion_r264773387"},"pull_request":{"href":"https://api.github.com/repos/paritytech/substrate/pulls/1943"}}},"pull_request":{"url":"https://api.github.com/repos/paritytech/substrate/pulls/1943","id":259059450,"node_id":"MDExOlB1bGxSZXF1ZXN0MjU5MDU5NDUw","html_url":"https://github.com/paritytech/substrate/pull/1943","diff_url":"https://github.com/paritytech/substrate/pull/1943.diff","patch_url":"https://github.com/paritytech/substrate/pull/1943.patch","issue_url":"https://api.github.com/repos/paritytech/substrate/issues/1943","number":1943,"state":"open","locked":false,"title":"Documentation for balances module","user":{"login":"joepetrowski","id":25483142,"node_id":"MDQ6VXNlcjI1NDgzMTQy","avatar_url":"https://avatars2.githubusercontent.com/u/25483142?v=4","gravatar_id":"","url":"https://api.github.com/users/joepetrowski","html_url":"https://github.com/joepetrowski","followers_url":"https://api.github.com/users/joepetrowski/followers","following_url":"https://api.github.com/users/joepetrowski/following{/other_user}","gists_url":"https://api.github.com/users/joepetrowski/gists{/gist_id}","starred_url":"https://api.github.com/users/joepetrowski/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/joepetrowski/subscriptions","organizations_url":"https://api.github.com/users/joepetrowski/orgs","repos_url":"https://api.github.com/users/joepetrowski/repos","events_url":"https://api.github.com/users/joepetrowski/events{/privacy}","received_events_url":"https://api.github.com/users/joepetrowski/received_events","type":"User","site_admin":false},"body":"First attempt at documentation for the balances module. Besides a general review, this needs:\r\n\r\n1. Particular attention to the \"Usage\" section of the readme. If you have corrections or better examples, please share.\r\n2. Continued discussion on the scope of rustdocs vs higher-level readme. I tried to account for the discussion emerging from https://github.com/paritytech/substrate/pull/1927.\r\n\r\nTODO: Add documentation for tests. There are a lot of them and I'd like better direction on the scope of rustdocs before completing them, so wanted to post for review at this stage.","created_at":"2019-03-07T10:41:05Z","updated_at":"2019-03-12T16:40:30Z","closed_at":null,"merged_at":null,"merge_commit_sha":"c30b8186795449bc5b7797b36e82995167525e5e","assignee":null,"assignees":[],"requested_reviewers":[],"requested_teams":[],"labels":[{"id":746560613,"node_id":"MDU6TGFiZWw3NDY1NjA2MTM=","url":"https://api.github.com/repos/paritytech/substrate/labels/A4-gotissues","name":"A4-gotissues","color":"f9d0c4","default":false},{"id":746560672,"node_id":"MDU6TGFiZWw3NDY1NjA2NzI=","url":"https://api.github.com/repos/paritytech/substrate/labels/M3-docs","name":"M3-docs","color":"fbffe0","default":false}],"milestone":null,"commits_url":"https://api.github.com/repos/paritytech/substrate/pulls/1943/commits","review_comments_url":"https://api.github.com/repos/paritytech/substrate/pulls/1943/comments","review_comment_url":"https://api.github.com/repos/paritytech/substrate/pulls/comments{/number}","comments_url":"https://api.github.com/repos/paritytech/substrate/issues/1943/comments","statuses_url":"https://api.github.com/repos/paritytech/substrate/statuses/f1b62a48a349e870e9f381156e332e3554e93c9e","head":{"label":"paritytech:joe-balances-docs","ref":"joe-balances-docs","sha":"f1b62a48a349e870e9f381156e332e3554e93c9e","user":{"login":"paritytech","id":14176906,"node_id":"MDEyOk9yZ2FuaXphdGlvbjE0MTc2OTA2","avatar_url":"https://avatars2.githubusercontent.com/u/14176906?v=4","gravatar_id":"","url":"https://api.github.com/users/paritytech","html_url":"https://github.com/paritytech","followers_url":"https://api.github.com/users/paritytech/followers","following_url":"https://api.github.com/users/paritytech/following{/other_user}","gists_url":"https://api.github.com/users/paritytech/gists{/gist_id}","starred_url":"https://api.github.com/users/paritytech/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/paritytech/subscriptions","organizations_url":"https://api.github.com/users/paritytech/orgs","repos_url":"https://api.github.com/users/paritytech/repos","events_url":"https://api.github.com/users/paritytech/events{/privacy}","received_events_url":"https://api.github.com/users/paritytech/received_events","type":"Organization","site_admin":false},"repo":{"id":109872620,"node_id":"MDEwOlJlcG9zaXRvcnkxMDk4NzI2MjA=","name":"substrate","full_name":"paritytech/substrate","private":false,"owner":{"login":"paritytech","id":14176906,"node_id":"MDEyOk9yZ2FuaXphdGlvbjE0MTc2OTA2","avatar_url":"https://avatars2.githubusercontent.com/u/14176906?v=4","gravatar_id":"","url":"https://api.github.com/users/paritytech","html_url":"https://github.com/paritytech","followers_url":"https://api.github.com/users/paritytech/followers","following_url":"https://api.github.com/users/paritytech/following{/other_user}","gists_url":"https://api.github.com/users/paritytech/gists{/gist_id}","starred_url":"https://api.github.com/users/paritytech/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/paritytech/subscriptions","organizations_url":"https://api.github.com/users/paritytech/orgs","repos_url":"https://api.github.com/users/paritytech/repos","events_url":"https://api.github.com/users/paritytech/events{/privacy}","received_events_url":"https://api.github.com/users/paritytech/received_events","type":"Organization","site_admin":false},"html_url":"https://github.com/paritytech/substrate","description":"Substrate: The platform for blockchain innovators","fork":false,"url":"https://api.github.com/repos/paritytech/substrate","forks_url":"https://api.github.com/repos/paritytech/substrate/forks","keys_url":"https://api.github.com/repos/paritytech/substrate/keys{/key_id}","collaborators_url":"https://api.github.com/repos/paritytech/substrate/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/paritytech/substrate/teams","hooks_url":"https://api.github.com/repos/paritytech/substrate/hooks","issue_events_url":"https://api.github.com/repos/paritytech/substrate/issues/events{/number}","events_url":"https://api.github.com/repos/paritytech/substrate/events","assignees_url":"https://api.github.com/repos/paritytech/substrate/assignees{/user}","branches_url":"https://api.github.com/repos/paritytech/substrate/branches{/branch}","tags_url":"https://api.github.com/repos/paritytech/substrate/tags","blobs_url":"https://api.github.com/repos/paritytech/substrate/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/paritytech/substrate/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/paritytech/substrate/git/refs{/sha}","trees_url":"https://api.github.com/repos/paritytech/substrate/git/trees{/sha}","statuses_url":"https://api.github.com/repos/paritytech/substrate/statuses/{sha}","languages_url":"https://api.github.com/repos/paritytech/substrate/languages","stargazers_url":"https://api.github.com/repos/paritytech/substrate/stargazers","contributors_url":"https://api.github.com/repos/paritytech/substrate/contributors","subscribers_url":"https://api.github.com/repos/paritytech/substrate/subscribers","subscription_url":"https://api.github.com/repos/paritytech/substrate/subscription","commits_url":"https://api.github.com/repos/paritytech/substrate/commits{/sha}","git_commits_url":"https://api.github.com/repos/paritytech/substrate/git/commits{/sha}","comments_url":"https://api.github.com/repos/paritytech/substrate/comments{/number}","issue_comment_url":"https://api.github.com/repos/paritytech/substrate/issues/comments{/number}","contents_url":"https://api.github.com/repos/paritytech/substrate/contents/{+path}","compare_url":"https://api.github.com/repos/paritytech/substrate/compare/{base}...{head}","merges_url":"https://api.github.com/repos/paritytech/substrate/merges","archive_url":"https://api.github.com/repos/paritytech/substrate/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/paritytech/substrate/downloads","issues_url":"https://api.github.com/repos/paritytech/substrate/issues{/number}","pulls_url":"https://api.github.com/repos/paritytech/substrate/pulls{/number}","milestones_url":"https://api.github.com/repos/paritytech/substrate/milestones{/number}","notifications_url":"https://api.github.com/repos/paritytech/substrate/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/paritytech/substrate/labels{/name}","releases_url":"https://api.github.com/repos/paritytech/substrate/releases{/id}","deployments_url":"https://api.github.com/repos/paritytech/substrate/deployments","created_at":"2017-11-07T18:08:53Z","updated_at":"2019-03-12T14:43:27Z","pushed_at":"2019-03-12T16:29:42Z","git_url":"git://github.com/paritytech/substrate.git","ssh_url":"git@github.com:paritytech/substrate.git","clone_url":"https://github.com/paritytech/substrate.git","svn_url":"https://github.com/paritytech/substrate","homepage":"","size":73014,"stargazers_count":889,"watchers_count":889,"language":"Rust","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":201,"mirror_url":null,"archived":false,"open_issues_count":259,"license":{"key":"other","name":"Other","spdx_id":"NOASSERTION","url":null,"node_id":"MDc6TGljZW5zZTA="},"forks":201,"open_issues":259,"watchers":889,"default_branch":"master"}},"base":{"label":"paritytech:master","ref":"master","sha":"5fa39c4c59df3c8b5cafd885da53912d6fcd97ba","user":{"login":"paritytech","id":14176906,"node_id":"MDEyOk9yZ2FuaXphdGlvbjE0MTc2OTA2","avatar_url":"https://avatars2.githubusercontent.com/u/14176906?v=4","gravatar_id":"","url":"https://api.github.com/users/paritytech","html_url":"https://github.com/paritytech","followers_url":"https://api.github.com/users/paritytech/followers","following_url":"https://api.github.com/users/paritytech/following{/other_user}","gists_url":"https://api.github.com/users/paritytech/gists{/gist_id}","starred_url":"https://api.github.com/users/paritytech/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/paritytech/subscriptions","organizations_url":"https://api.github.com/users/paritytech/orgs","repos_url":"https://api.github.com/users/paritytech/repos","events_url":"https://api.github.com/users/paritytech/events{/privacy}","received_events_url":"https://api.github.com/users/paritytech/received_events","type":"Organization","site_admin":false},"repo":{"id":109872620,"node_id":"MDEwOlJlcG9zaXRvcnkxMDk4NzI2MjA=","name":"substrate","full_name":"paritytech/substrate","private":false,"owner":{"login":"paritytech","id":14176906,"node_id":"MDEyOk9yZ2FuaXphdGlvbjE0MTc2OTA2","avatar_url":"https://avatars2.githubusercontent.com/u/14176906?v=4","gravatar_id":"","url":"https://api.github.com/users/paritytech","html_url":"https://github.com/paritytech","followers_url":"https://api.github.com/users/paritytech/followers","following_url":"https://api.github.com/users/paritytech/following{/other_user}","gists_url":"https://api.github.com/users/paritytech/gists{/gist_id}","starred_url":"https://api.github.com/users/paritytech/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/paritytech/subscriptions","organizations_url":"https://api.github.com/users/paritytech/orgs","repos_url":"https://api.github.com/users/paritytech/repos","events_url":"https://api.github.com/users/paritytech/events{/privacy}","received_events_url":"https://api.github.com/users/paritytech/received_events","type":"Organization","site_admin":false},"html_url":"https://github.com/paritytech/substrate","description":"Substrate: The platform for blockchain innovators","fork":false,"url":"https://api.github.com/repos/paritytech/substrate","forks_url":"https://api.github.com/repos/paritytech/substrate/forks","keys_url":"https://api.github.com/repos/paritytech/substrate/keys{/key_id}","collaborators_url":"https://api.github.com/repos/paritytech/substrate/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/paritytech/substrate/teams","hooks_url":"https://api.github.com/repos/paritytech/substrate/hooks","issue_events_url":"https://api.github.com/repos/paritytech/substrate/issues/events{/number}","events_url":"https://api.github.com/repos/paritytech/substrate/events","assignees_url":"https://api.github.com/repos/paritytech/substrate/assignees{/user}","branches_url":"https://api.github.com/repos/paritytech/substrate/branches{/branch}","tags_url":"https://api.github.com/repos/paritytech/substrate/tags","blobs_url":"https://api.github.com/repos/paritytech/substrate/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/paritytech/substrate/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/paritytech/substrate/git/refs{/sha}","trees_url":"https://api.github.com/repos/paritytech/substrate/git/trees{/sha}","statuses_url":"https://api.github.com/repos/paritytech/substrate/statuses/{sha}","languages_url":"https://api.github.com/repos/paritytech/substrate/languages","stargazers_url":"https://api.github.com/repos/paritytech/substrate/stargazers","contributors_url":"https://api.github.com/repos/paritytech/substrate/contributors","subscribers_url":"https://api.github.com/repos/paritytech/substrate/subscribers","subscription_url":"https://api.github.com/repos/paritytech/substrate/subscription","commits_url":"https://api.github.com/repos/paritytech/substrate/commits{/sha}","git_commits_url":"https://api.github.com/repos/paritytech/substrate/git/commits{/sha}","comments_url":"https://api.github.com/repos/paritytech/substrate/comments{/number}","issue_comment_url":"https://api.github.com/repos/paritytech/substrate/issues/comments{/number}","contents_url":"https://api.github.com/repos/paritytech/substrate/contents/{+path}","compare_url":"https://api.github.com/repos/paritytech/substrate/compare/{base}...{head}","merges_url":"https://api.github.com/repos/paritytech/substrate/merges","archive_url":"https://api.github.com/repos/paritytech/substrate/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/paritytech/substrate/downloads","issues_url":"https://api.github.com/repos/paritytech/substrate/issues{/number}","pulls_url":"https://api.github.com/repos/paritytech/substrate/pulls{/number}","milestones_url":"https://api.github.com/repos/paritytech/substrate/milestones{/number}","notifications_url":"https://api.github.com/repos/paritytech/substrate/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/paritytech/substrate/labels{/name}","releases_url":"https://api.github.com/repos/paritytech/substrate/releases{/id}","deployments_url":"https://api.github.com/repos/paritytech/substrate/deployments","created_at":"2017-11-07T18:08:53Z","updated_at":"2019-03-12T14:43:27Z","pushed_at":"2019-03-12T16:29:42Z","git_url":"git://github.com/paritytech/substrate.git","ssh_url":"git@github.com:paritytech/substrate.git","clone_url":"https://github.com/paritytech/substrate.git","svn_url":"https://github.com/paritytech/substrate","homepage":"","size":73014,"stargazers_count":889,"watchers_count":889,"language":"Rust","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":201,"mirror_url":null,"archived":false,"open_issues_count":259,"license":{"key":"other","name":"Other","spdx_id":"NOASSERTION","url":null,"node_id":"MDc6TGljZW5zZTA="},"forks":201,"open_issues":259,"watchers":889,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/paritytech/substrate/pulls/1943"},"html":{"href":"https://github.com/paritytech/substrate/pull/1943"},"issue":{"href":"https://api.github.com/repos/paritytech/substrate/issues/1943"},"comments":{"href":"https://api.github.com/repos/paritytech/substrate/issues/1943/comments"},"review_comments":{"href":"https://api.github.com/repos/paritytech/substrate/pulls/1943/comments"},"review_comment":{"href":"https://api.github.com/repos/paritytech/substrate/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/paritytech/substrate/pulls/1943/commits"},"statuses":{"href":"https://api.github.com/repos/paritytech/substrate/statuses/f1b62a48a349e870e9f381156e332e3554e93c9e"}},"author_association":"CONTRIBUTOR"}}
{"actor":{"display_login":"AmarRSingh"}}