chore!: rename GenerateUnsealedCID to PieceAggregateCommP, update docs

Author: rvagg

commd.go

@@ -17,12 +17,13 @@ type stackFrame struct {
 	commP []byte
 }
 
-// GenerateUnsealedCID generates the UnsealedCID (CommD) for a sector of size determined by the
-// proofType from the provided pieceInfos by merkleization the CommPs of the pieces.
+// PieceAggregateCommP generates an aggregate CommP for a list of pieces that combine in size up to
+// the sector size determined by the proofType parameter.
 //
-// This function **assumes** that the pieces are already padded to the sector size and may not
-// return the correct result if this is not the case.
-func GenerateUnsealedCID(proofType abi.RegisteredSealProof, pieceInfos []abi.PieceInfo) (cid.Cid, error) {
+// This function makes no assumptions, other than maximum size, about the pieces that you include.
+// To create a correctly formed UnsealedCID (CommD) for a sector using this method, you should first
+// ensure that the pieces add up to the required size.
+func PieceAggregateCommP(proofType abi.RegisteredSealProof, pieceInfos []abi.PieceInfo) (cid.Cid, error) {
 	spi, found := abi.SealProofInfos[proofType]
 	if !found {
 		return cid.Undef, fmt.Errorf("unknown seal proof type %d", proofType)

commd_test.go

@@ -26,7 +26,7 @@ func TestGenerateUnsealedCID(t *testing.T) {
 
 	expCommD := cidMustParse("baga6ea4seaqiw3gbmstmexb7sqwkc5r23o3i7zcyx5kr76pfobpykes3af62kca")
 
-	commD, _ := commp.GenerateUnsealedCID(
+	commD, _ := commp.PieceAggregateCommP(
 		abi.RegisteredSealProof_StackedDrg32GiBV1_1, // 32G sector SP
 		[]abi.PieceInfo{
 			{PieceCID: cidMustParse("baga6ea4seaqknzm22isnhsxt2s4dnw45kfywmhenngqq3nc7jvecakoca6ksyhy"), Size: 256 << 20},  // https://filfox.info/en/deal/3755444

writer/writer.go

@@ -144,7 +144,7 @@ func (w *Writer) Sum() (DataCIDSize, error) {
 		}
 	}
 
-	p, err := commp.GenerateUnsealedCID(abi.RegisteredSealProof_StackedDrg64GiBV1, pieces)
+	p, err := commp.PieceAggregateCommP(abi.RegisteredSealProof_StackedDrg64GiBV1, pieces)
 	if err != nil {
 		return DataCIDSize{}, xerrors.Errorf("generating unsealed CID: %w", err)
 	}