Merge pull request #4529 from corda/FinalityFlowMigrationDocUpdate

Finality flow migration doc update

docs/source/app-upgrade-notes.rst

@@ -121,7 +121,7 @@ away to the new API, as otherwise things like business network membership checks
 
 This is a three step process:
 
-1. Change the flow that calls ``FinalityFlow``
+1. Change the flow that calls ``FinalityFlow``.
 2. Change or create the flow that will receive the finalised transaction.
 3. Make sure your application's minimum and target version numbers are both set to 4 (see step 2).
 
@@ -140,7 +140,7 @@ As an example, let's take a very simple flow that finalises a transaction withou
         :end-before: DOCEND SimpleFlowUsingOldApi
         :dedent: 4
 
-To use the new API, this flow needs to be annotated with ``InitiatingFlow`` and a ``FlowSession`` to the participant of the transaction must be
+To use the new API, this flow needs to be annotated with ``InitiatingFlow`` and a ``FlowSession`` to the participant(s) of the transaction must be
 passed to ``FinalityFlow`` :
 
 .. container:: codeset

docs/source/example-code/src/main/java/net/corda/docs/java/FinalityFlowMigration.java

@@ -110,18 +110,21 @@ public class FinalityFlowMigration {
         @Suspendable
         @Override
         public Void call() throws FlowException {
+
+            // DOCSTART ExistingResponderFlow
+            // First we have to run the SignTransactionFlow, which will return a SignedTransaction.
             SignedTransaction txWeJustSigned = subFlow(new SignTransactionFlow(otherSide) {
                 @Suspendable
                 @Override
                 protected void checkTransaction(@NotNull SignedTransaction stx) throws FlowException {
-                    // Do checks here
+                    // Implement responder flow transaction checks here
                 }
             });
-            // DOCSTART ExistingResponderFlow
+
             if (otherSide.getCounterpartyFlowInfo().getFlowVersion() >= 2) {
                 // The other side is not using the old CorDapp so call ReceiveFinalityFlow to record the finalised transaction.
                 // If SignTransactionFlow is used then we can verify the tranaction we receive for recording is the same one
-                // that was just signed.
+                // that was just signed by passing the transaction id to ReceiveFinalityFlow.
                 subFlow(new ReceiveFinalityFlow(otherSide, txWeJustSigned.getId()));
             } else {
                 // Otherwise the other side is running the old CorDapp and so we don't need to do anything further. The node

docs/source/example-code/src/main/kotlin/net/corda/docs/kotlin/FinalityFlowMigration.kt

@@ -70,13 +70,15 @@ class ExistingInitiatingFlow(private val counterparty: Party) : FlowLogic<Signed
 class ExistingResponderFlow(private val otherSide: FlowSession) : FlowLogic<Unit>() {
     @Suspendable
     override fun call() {
+        // DOCSTART ExistingResponderFlow
+        // First we have to run the SignTransactionFlow, which will return a SignedTransaction.
         val txWeJustSigned = subFlow(object : SignTransactionFlow(otherSide) {
             @Suspendable
             override fun checkTransaction(stx: SignedTransaction) {
-                // Do checks here
+                // Implement responder flow transaction checks here
             }
         })
-        // DOCSTART ExistingResponderFlow
+
         if (otherSide.getCounterpartyFlowInfo().flowVersion >= 2) {
             // The other side is not using the old CorDapp so call ReceiveFinalityFlow to record the finalised transaction.
             // If SignTransactionFlow is used then we can verify the tranaction we receive for recording is the same one