Bug 1423124 - add comments on nsIPaymentUIService.idl. r=MattN

dom/interfaces/payments/nsIPaymentUIService.idl

@@ -6,12 +6,60 @@
 #include "nsISupports.idl"
 #include "nsIPaymentActionResponse.idl"
 
+/**
+ * nsIPaymentUIService is the interface used by Gecko to communicate with the
+ * payment UI.
+ * In general, the implementation of this interface should be a service that
+ * manages all payment UI components and receives the requested payment actions
+ * from Gecko and perform the corresponding UI behavior.
+ */
 [scriptable, uuid(01f8bd55-9017-438b-85ec-7c15d2b35cdc)]
 interface nsIPaymentUIService : nsISupports
 {
+  /**
+   *  Show the payment UI to users.
+   *  The implementation gets the payment data through nsIPaymentRequestService
+   *  by the passed in requestId, then shows the payment UI and start to interact
+   *  with users.
+   *  According to user's action, nsIPaymentRequestService's APIs respondPayment,
+   *  changeShippingAddress, or changeShippingOtpion is possible to called in the
+   *  implementation.
+   *  @param requestId - the request identify of the payment request.
+   *                     Notice that this requestId is an internal request Id
+   *                     generated by Gecko
+   */
   void showPayment(in AString requestId);
+
+  /**
+   *  Abort the payment.
+   *  The implementation must abort and close the showing payment UI then call
+   *  nsIPaymentRequestService respondPayment with nsIPaymentAbortActionResponse
+   *  to inform Gecko of the abort status.
+   *  @param requestId - the request identify of the payment request.
+   *                     Notice that this requestId is an internal request Id
+   *                     generated by Gecko
+   */
   void abortPayment(in AString requestId);
+
+  /**
+   *  Complete the payment.
+   *  The implementation should close the showing payment UI, then call
+   *  nsIPaymentRequestService respondPayment with nsIPaymentCompleteActionResponse
+   *  to inform Gecko of the complete status.
+   *  @param requestId - the request identify of the payment request.
+   *                     Notice that this requestId is an internal request Id
+   *                     generated by Gecko
+   */
   void completePayment(in AString requestId);
+
+  /**
+   *  Update the payment data in the payment UI.
+   *  The implementation should get the updated payment data through the
+   *  nsIPaymentRequestService again, and update the UI.
+   *  @param requestId - the request identify of the payment request.
+   *                     Notice that this requestId is an internal request Id
+   *                     generated by Gecko
+   */
   void updatePayment(in AString requestId);
 };