Formatting improvements and add code comments on Order API + fix broken URL

docs/financial/orderAPI.md

@@ -62,7 +62,7 @@ Things to note:
 5. The `line_total` *must* equal the `unit_price` × `qty`
 
 !!! info
-    If you provide a value to `total_amount` as we have above, it *must* equal the sum of all the `line_total` values. Before 5.20 there was [a bug](https://lab.civicrm.orog/dev/financial/issues/73) that required the top-level `total_amount` was provided, but from 5.20 onward you can omit this and it will be calculated automatically from the sum of the `line_items`.
+    If you provide a value to `total_amount` as we have above, it *must* equal the sum of all the `line_total` values. Before 5.20 there was [a bug](https://lab.civicrm.org/dev/financial/issues/73) that required the top-level `total_amount` was provided, but from 5.20 onward you can omit this and it will be calculated automatically from the sum of the `line_items`.
 
 
 Currently the data returned from `Order.create` shows only the fields from the created Contribution. However an `Order.get` API call for the ID will also include an array of `line_items` (see below for example).
@@ -335,11 +335,13 @@ The Contribution.transact api will create a 'simple' contribution and process a
 
 The simplest first step to migrate off it is to replace the order api call with a call that follows the recommended flow but still does not address the line item creation gaps & it is recommended you  look at the patterns above to do that. This first step looks like
 
-```
-# start with the same parameters as Contribution.transact.
+```php
+// Start with the same parameters as Contribution.transact.
 $params = $transactParams;
-# it would be  better just  to include the relevant params but....
+
+// It would be  better just  to include the relevant params but....
 $paymentParams = $transactParams;
+
 $params['contribution_status_id'] = 'Pending';
 if (!isset($params['invoice_id')) {
   // Set an invoice_id here if you have not already done so.
@@ -351,8 +353,14 @@ if (!isset($params['invoiceID']) {
 }
 $order = civicrm_api3('Order', 'create' $params);
 try {
+  // Use the Payment Processor to attempt to take the actual payment. You may
+  // pass in other params here, too.
   civicrm_api3('PaymentProcessor', 'pay', ['contribution_id' => $order['id']]);
-  civicrm_api3('Payment', 'create', ['contribution_id' => $order['id'], 'amount' => $params['amount']]);
+
+  // Assuming the payment was taken, record it which will mark the Contribution
+  // as Completed and update related entities.
+  civicrm_api3('Payment', 'create',
+    ['contribution_id' => $order['id'], 'amount' => $params['amount']]);
 }
 catch  {
   // it failed