* formatting

* use uniform notion of parent and child, no "master" or "general" entity
* README updated to match comments

frame/bounties/README.md

@@ -2,43 +2,55 @@
 
 ## Bounty
 
-**Note :: This pallet is tightly coupled with pallet-treasury**
+> NOTE: This pallet is tightly coupled with pallet-treasury.
 
-A Bounty Spending is a reward for a specified body of work - or specified set of objectives - that
-needs to be executed for a predefined Treasury amount to be paid out. A curator is assigned after
-the bounty is approved and funded by Council, to be delegated with the responsibility of assigning a
-payout address once the specified set of objectives is completed.
+A Bounty Spending is a reward for a specified body of work - or specified set of objectives -
+that needs to be executed for a predefined Treasury amount to be paid out. A curator is assigned
+after the bounty is approved and funded by Council, to be delegated with the responsibility of
+assigning a payout address once the specified set of objectives is completed.
 
-After the Council has activated a bounty, it delegates the work that requires expertise to a curator
-in exchange of a deposit. Once the curator accepts the bounty, they get to close the active bounty.
-Closing the active bounty enacts a delayed payout to the payout address, the curator fee and the
-return of the curator deposit. The delay allows for intervention through regular democracy. The
-Council gets to unassign the curator, resulting in a new curator election. The Council also gets to
-cancel the bounty if deemed necessary before assigning a curator or once the bounty is active or
-payout is pending, resulting in the slash of the curator's deposit.
+After the Council has activated a bounty, it delegates the work that requires expertise to a
+curator in exchange of a deposit. Once the curator accepts the bounty, they get to close the
+active bounty. Closing the active bounty enacts a delayed payout to the payout address, the
+curator fee and the return of the curator deposit. The delay allows for intervention through
+regular democracy. The Council gets to unassign the curator, resulting in a new curator
+election. The Council also gets to cancel the bounty if deemed necessary before assigning a
+curator or once the bounty is active or payout is pending, resulting in the slash of the
+curator's deposit.
+
+This pallet may opt into using a [`ChildBountyManager`] that enables bounties to be split into
+sub-bounties, as children of anh established bounty (called the parent in the context of it's
+children).
+
+> NOTE: The parent bounty cannot be closed if it has a non-zero number of it has active child
+> bounties associated with it.
 
 ### Terminology
 
-- **Bounty spending proposal:** A proposal to reward a predefined body of work upon completion by
-  the Treasury.
+Bounty:
+
+- **Bounty spending proposal:** A proposal to reward a predefined body of work upon completion
+  by the Treasury.
 - **Proposer:** An account proposing a bounty spending.
-- **Curator:** An account managing the bounty and assigning a payout address receiving the reward
-  for the completion of work.
+- **Curator:** An account managing the bounty and assigning a payout address receiving the
+  reward for the completion of work.
 - **Deposit:** The amount held on deposit for placing a bounty proposal plus the amount held on
   deposit per byte within the bounty description.
 - **Curator deposit:** The payment from a candidate willing to curate an approved bounty. The
   deposit is returned when/if the bounty is completed.
 - **Bounty value:** The total amount that should be paid to the Payout Address if the bounty is
   rewarded.
 - **Payout address:** The account to which the total or part of the bounty is assigned to.
-- **Payout Delay:** The delay period for which a bounty beneficiary needs to wait before claiming.
+- **Payout Delay:** The delay period for which a bounty beneficiary needs to wait before
+  claiming.
 - **Curator fee:** The reserved upfront payment for a curator for work related to the bounty.
 
 ## Interface
 
 ### Dispatchable Functions
 
 Bounty protocol:
+
 - `propose_bounty` - Propose a specific treasury amount to be earmarked for a predefined set of
   tasks and stake the required deposit.
 - `approve_bounty` - Accept a specific treasury amount to be earmarked for a predefined body of

frame/bounties/src/lib.rs

@@ -35,10 +35,17 @@
 //! curator or once the bounty is active or payout is pending, resulting in the slash of the
 //! curator's deposit.
 //!
+//! This pallet may opt into using a [`ChildBountyManager`] that enables bounties to be split into
+//! sub-bounties, as children of anh established bounty (called the parent in the context of it's
+//! children).
+//!
+//! > NOTE: The parent bounty cannot be closed if it has a non-zero number of it has active child
+//! > bounties associated with it.
 //!
 //! ### Terminology
 //!
 //! Bounty:
+//!
 //! - **Bounty spending proposal:** A proposal to reward a predefined body of work upon completion
 //!   by the Treasury.
 //! - **Proposer:** An account proposing a bounty spending.
@@ -60,6 +67,7 @@
 //! ### Dispatchable Functions
 //!
 //! Bounty protocol:
+//!
 //! - `propose_bounty` - Propose a specific treasury amount to be earmarked for a predefined set of
 //!   tasks and stake the required deposit.
 //! - `approve_bounty` - Accept a specific treasury amount to be earmarked for a predefined body of
@@ -165,9 +173,9 @@ pub enum BountyStatus<AccountId, BlockNumber> {
 	},
 }
 
-/// The child-bounty manager.
+/// The child bounty manager.
 pub trait ChildBountyManager<Balance> {
-	/// Get the active child-bounties for a parent bounty.
+	/// Get the active child bounties for a parent bounty.
 	fn child_bounties_count(bounty_id: BountyIndex) -> BountyIndex;
 
 	/// Get total curator fees of children-bounty curators.
@@ -230,7 +238,7 @@ pub mod pallet {
 		/// Weight information for extrinsics in this pallet.
 		type WeightInfo: WeightInfo;
 
-		/// The child-bounty manager.
+		/// The child bounty manager.
 		type ChildBountyManager: ChildBountyManager<BalanceOf<Self>>;
 	}
 
@@ -255,7 +263,7 @@ pub mod pallet {
 		PendingPayout,
 		/// The bounties cannot be claimed/closed because it's still in the countdown period.
 		Premature,
-		/// The bounty cannot be closed because it has active child-bounties.
+		/// The bounty cannot be closed because it has active child bounties.
 		HasActiveChildBounty,
 		/// Too many approvals are already queued.
 		TooManyQueued,
@@ -551,7 +559,7 @@ pub mod pallet {
 			Bounties::<T>::try_mutate_exists(bounty_id, |maybe_bounty| -> DispatchResult {
 				let mut bounty = maybe_bounty.as_mut().ok_or(Error::<T>::InvalidIndex)?;
 
-				// Ensure no active child-bounties before processing the call.
+				// Ensure no active child bounties before processing the call.
 				ensure!(
 					T::ChildBountyManager::child_bounties_count(bounty_id) == 0,
 					Error::<T>::HasActiveChildBounty
@@ -609,8 +617,8 @@ pub mod pallet {
 					let err_amount = T::Currency::unreserve(&curator, bounty.curator_deposit);
 					debug_assert!(err_amount.is_zero());
 
-					// Get total child-bounties curator fees, and subtract it from master curator
-					// fee.
+					// Get total child bounties curator fees, and subtract it from the parent
+					// curator fee (the fee in present referenced bounty, `self`).
 					let children_fee = T::ChildBountyManager::children_curator_fees(bounty_id);
 					debug_assert!(children_fee <= fee);
 
@@ -662,7 +670,7 @@ pub mod pallet {
 				|maybe_bounty| -> DispatchResultWithPostInfo {
 					let bounty = maybe_bounty.as_ref().ok_or(Error::<T>::InvalidIndex)?;
 
-					// Ensure no active child-bounties before processing the call.
+					// Ensure no active child bounties before processing the call.
 					ensure!(
 						T::ChildBountyManager::child_bounties_count(bounty_id) == 0,
 						Error::<T>::HasActiveChildBounty

frame/child-bounties/README.md

@@ -1,21 +1,29 @@
-# Child Bounties Pallet (pallet-child-bounties)
+# Child Bounties Pallet ( `pallet-child-bounties` )
 
 ## Child Bounty
 
-> NOTE: This pallet is tightly coupled with pallet-treasury and pallet-bounties.
+> NOTE: This pallet is tightly coupled with `pallet-treasury` and `pallet-bounties`.
 
-With child bounties, a large bounty proposal can be divided into smaller chunks, for parallel execution, and for efficient governance and tracking of spent funds.
-
-A child-bounty is a smaller piece of work, extracted from a parent bounty. A curator is assigned after the child-bounty is created by the parent bounty curator, to be delegated with the responsibility of assigning a payout address once the specified set of tasks is completed.
+With child bounties, a large bounty proposal can be divided into smaller chunks,
+for parallel execution, and for efficient governance and tracking of spent funds.
+A child bounty is a smaller piece of work, extracted from a parent bounty.
+A curator is assigned after the child bounty is created by the parent bounty curator,
+to be delegated with the responsibility of assigning a payout address once the specified
+set of tasks is completed.
 
 ## Interface
 
 ### Dispatchable Functions
 
-- `add_child_bounty` - Add a child-bounty for a parent-bounty to for dividing the work in smaller tasks.
-- `propose_curator` - Assign an account to a child-bounty as candidate curator.
-- `accept_curator` - Accept a child-bounty assignment from the parent-bounty curator, setting a curator deposit.
+Child Bounty protocol:
+
+- `add_child_bounty` - Add a child bounty for a parent bounty to for dividing the work in
+  smaller tasks.
+- `propose_curator` - Assign an account to a child bounty as candidate curator.
+- `accept_curator` - Accept a child bounty assignment from the parent bounty curator, setting a
+  curator deposit.
 - `award_child_bounty` - Close and pay out the specified amount for the completed work.
-- `claim_child_bounty` - Claim a specific child-bounty amount from the payout address.
-- `unassign_curator` - Unassign an accepted curator from a specific child-bounty.
-- `close_child_bounty` - Cancel the child-bounty for a specific treasury amount and close the bounty.
+- `claim_child_bounty` - Claim a specific child bounty amount from the payout address.
+- `unassign_curator` - Unassign an accepted curator from a specific child bounty.
+- `close_child_bounty` - Cancel the child bounty for a specific treasury amount and close the
+  bounty.