Expand documentation for deal activation and verified claim parameters and results. (#1325)

Author: anorth

actors/market/src/lib.rs

@@ -530,9 +530,10 @@ impl Actor {
         Ok(VerifyDealsForActivationReturn { sectors: sectors_data })
     }
 
-    /// Activate a set of deals, returning the deal space and extra info for sectors containing
-    /// verified deals. Sectors are activated in parameter-defined order and can fail independently of
-    /// each other with the responsible ExitCode recorded in a BatchReturn.
+    /// Activate a set of deals grouped by sector, returning the size and
+    /// extra info about verified deals.
+    /// Sectors' deals are activated in parameter-defined order.
+    /// Each sector's deals are activated or fail as a group, but independently of other sectors.
     fn batch_activate_deals(
         rt: &impl Runtime,
         params: BatchActivateDealsParams,

actors/market/src/types.rs

@@ -71,11 +71,9 @@ pub struct PublishStorageDealsReturn {
     pub valid_deals: BitField,
 }
 
-// Changed since V2:
-// - Array of Sectors rather than just one
-// - Removed SectorStart
 #[derive(Serialize_tuple, Deserialize_tuple, Debug, Clone, Eq, PartialEq)]
 pub struct VerifyDealsForActivationParams {
+    /// Deals to verify, grouped by sector.
     pub sectors: Vec<SectorDeals>,
 }
 
@@ -100,9 +98,11 @@ pub struct SectorDealData {
 #[derive(Serialize_tuple, Deserialize_tuple, Debug, Clone, Eq, PartialEq)]
 #[serde(transparent)]
 pub struct BatchActivateDealsParams {
+    /// Deals to activate, grouped by sector.
     pub sectors: Vec<SectorDeals>,
 }
 
+// Information about a verified deal that has been activated.
 #[derive(Serialize_tuple, Deserialize_tuple, Debug, Clone, Eq, PartialEq)]
 pub struct VerifiedDealInfo {
     pub client: ActorID,
@@ -111,16 +111,21 @@ pub struct VerifiedDealInfo {
     pub size: PaddedPieceSize,
 }
 
+// Information about a sector-grouping of deals that have been activated.
 #[derive(Serialize_tuple, Deserialize_tuple, Debug, Clone, Eq, PartialEq)]
 pub struct DealActivation {
+    /// The total size of the non-verified deals activated.
     #[serde(with = "bigint_ser")]
     pub nonverified_deal_space: BigInt,
+    /// Information about each verified deal activated.
     pub verified_infos: Vec<VerifiedDealInfo>,
 }
 
 #[derive(Serialize_tuple, Deserialize_tuple, Debug, Clone, Eq, PartialEq)]
 pub struct BatchActivateDealsResult {
+    /// Status of each sector grouping of deals.
     pub activation_results: BatchReturn,
+    /// Activation information for the sector groups that were activated.
     pub activations: Vec<DealActivation>,
 }
 

actors/verifreg/src/lib.rs

@@ -366,10 +366,9 @@ impl Actor {
     /// Called by storage provider actor to claim allocations for data provably committed to storage.
     /// For each allocation claim, the registry checks that the provided piece CID
     /// and size match that of the allocation.
-    /// Returns a vec of claimed spaces parallel (with same length and corresponding indices) to
-    /// the requested allocations. When `all_or_nothing` is false, failed claims are represented by
-    /// DataCap::zero() entry in the result vec. When `all_or_nothing` is enabled, any failure to
-    /// claim results in the entire function returning an error.
+    /// Returns an indicator of success for each claim, and the size of each successful claim.
+    /// When `all_or_nothing` is enabled, any failure to claim results in the entire
+    /// method returning an error.
     pub fn claim_allocations(
         rt: &impl Runtime,
         params: ClaimAllocationsParams,

actors/verifreg/src/types.rs

@@ -133,6 +133,7 @@ pub struct SectorAllocationClaim {
 #[derive(Clone, Debug, PartialEq, Eq, Serialize_tuple, Deserialize_tuple)]
 pub struct ClaimAllocationsParams {
     pub allocations: Vec<SectorAllocationClaim>,
+    // Whether to abort entirely if any claim fails.
     pub all_or_nothing: bool,
 }
 
@@ -145,7 +146,9 @@ pub struct SectorAllocationClaimResult {
 
 #[derive(Clone, Debug, PartialEq, Eq, Serialize_tuple, Deserialize_tuple)]
 pub struct ClaimAllocationsReturn {
+    // Success/failure indication for each claim.
     pub claim_results: BatchReturn,
+    // The claimed space for each successful claim, in order.
     pub claims: Vec<SectorAllocationClaimResult>,
 }