refactor (Voice): Enhance comments

Author: JPPortier

snippets/src/main/java/voice/applications/AssignNumbers.java

@@ -25,6 +25,8 @@ public static void main(String[] args) {
     String applicationKey = Settings.getApplicationKey().orElse("MY_APPLICATION_KEY");
     String applicationSecret = Settings.getApplicationSecret().orElse("MY_APPLICATION_SECRET");
 
+    // The Sinch virtual phone number to assign to the application, in E.164 format (e.g.,
+    // +12025550123)
     String phoneNumber = Settings.getPhoneNumber().orElse("MY_SINCH_PHONE_NUMBER");
 
     Configuration configuration =

snippets/src/main/java/voice/applications/UnAssignNumber.java

@@ -23,6 +23,7 @@ public static void main(String[] args) {
     String applicationKey = Settings.getApplicationKey().orElse("MY_APPLICATION_KEY");
     String applicationSecret = Settings.getApplicationSecret().orElse("MY_APPLICATION_SECRET");
 
+    // The phone number to unassign from the application, in E.164 format (e.g., +12025550123)
     String phoneNumber = Settings.getPhoneNumber().orElse("MY_SINCH_PHONE_NUMBER");
 
     Configuration configuration =

snippets/src/main/java/voice/applications/UpdateCallbackUrls.java

@@ -24,7 +24,8 @@ public static void main(String[] args) {
     String applicationKey = Settings.getApplicationKey().orElse("MY_APPLICATION_KEY");
     String applicationSecret = Settings.getApplicationSecret().orElse("MY_APPLICATION_SECRET");
 
-    String callbackURL = "A_WEBHOOK_URL";
+    // The new callback URL to set for the application
+    String callbackURL = "https://my.callback.url/voice";
 
     Configuration configuration =
         Configuration.builder()

snippets/src/main/java/voice/callouts/Call.java

@@ -24,7 +24,8 @@ public static void main(String[] args) {
     String applicationKey = Settings.getApplicationKey().orElse("MY_APPLICATION_KEY");
     String applicationSecret = Settings.getApplicationSecret().orElse("MY_APPLICATION_SECRET");
 
-    String recipientPhoneNumber = "PHONE_NUMBER_TO_BE_CALLED";
+    // The phone number you want to call, in E.164 format (e.g., +12025550123)
+    String recipientPhoneNumber = "RECIPIENT_PHONE_NUMBER";
     String textToSpeech = "Hello, this is a call initiated from Sinch Java SDK. Goodbye.";
 
     Configuration configuration =

snippets/src/main/java/voice/calls/Get.java

@@ -23,7 +23,8 @@ public static void main(String[] args) {
     String applicationKey = Settings.getApplicationKey().orElse("MY_APPLICATION_KEY");
     String applicationSecret = Settings.getApplicationSecret().orElse("MY_APPLICATION_SECRET");
 
-    String callId = "A_CALL_ID";
+    // The ID of the call to retrieve
+    String callId = "CALL_ID";
 
     Configuration configuration =
         Configuration.builder()

snippets/src/main/java/voice/calls/ManageWithCallLeg.java

@@ -30,7 +30,10 @@ public static void main(String[] args) {
     String applicationKey = Settings.getApplicationKey().orElse("MY_APPLICATION_KEY");
     String applicationSecret = Settings.getApplicationSecret().orElse("MY_APPLICATION_SECRET");
 
-    String callId = "A_CALL_ID";
+    // The ID of the call to manage
+    String callId = "CALL_ID";
+    // The call leg to manage
+    CallLeg callLeg = CallLeg.CALLEE;
 
     Configuration configuration =
         Configuration.builder()
@@ -55,7 +58,7 @@ public static void main(String[] args) {
     SvamlControl request =
         SvamlControl.builder().setInstructions(instructions).setAction(action).build();
 
-    callsService.manageWithCallLeg(callId, CallLeg.CALLEE, request);
+    callsService.manageWithCallLeg(callId, callLeg, request);
 
     LOGGER.info("Done");
   }

snippets/src/main/java/voice/calls/Update.java

@@ -29,7 +29,12 @@ public static void main(String[] args) {
     String applicationKey = Settings.getApplicationKey().orElse("MY_APPLICATION_KEY");
     String applicationSecret = Settings.getApplicationSecret().orElse("MY_APPLICATION_SECRET");
 
-    String callId = "A_CALL_ID";
+    // The ID of the call to update
+    String callId = "CALL_ID";
+    // The instruction to be performed
+    SvamlInstruction instruction = SvamlInstructionSay.builder().setText("Goodbye").build();
+    // The instruction to add to the call
+    SvamlAction action = SvamlActionHangup.DEFAULT;
 
     Configuration configuration =
         Configuration.builder()
@@ -43,10 +48,6 @@ public static void main(String[] args) {
 
     LOGGER.info(String.format("Updating call with ID '%s'", callId));
 
-    SvamlAction action = SvamlActionHangup.DEFAULT;
-
-    SvamlInstruction instruction = SvamlInstructionSay.builder().setText("Goodbye").build();
-
     Collection<SvamlInstruction> instructions = Collections.singletonList(instruction);
 
     SvamlControl request =

snippets/src/main/java/voice/conferences/Call.java

@@ -25,8 +25,11 @@ public static void main(String[] args) {
     String applicationSecret = Settings.getApplicationSecret().orElse("MY_APPLICATION_SECRET");
     String phoneNumber = Settings.getPhoneNumber().orElse("MY_SINCH_PHONE_NUMBER");
 
-    String conferenceId = "AN_EXISTING_OR_TO_BE_CREATED_CONFERENCE_ID";
-    String phoneNumberToBeCalled = "PHONE_NUMBER_TO_BE_CALLED";
+    // An existing or to be created conference ID
+    String conferenceId = "CONFERENCE_ID";
+    // The phone number to be called and added to the conference, in E.164 format (e.g.,
+    // +12025550123)
+    String recipientPhoneNumber = "RECIPIENT_PHONE_NUMBER";
 
     Configuration configuration =
         Configuration.builder()
@@ -40,11 +43,11 @@ public static void main(String[] args) {
 
     LOGGER.info(
         String.format(
-            "Joining conference '%s' for phone number '%s'", conferenceId, phoneNumberToBeCalled));
+            "Joining conference '%s' for phone number '%s'", conferenceId, recipientPhoneNumber));
 
     CalloutRequestConference request =
         CalloutRequestConference.builder()
-            .setDestination(DestinationPstn.from(phoneNumberToBeCalled))
+            .setDestination(DestinationPstn.from(recipientPhoneNumber))
             .setCli(phoneNumber)
             .setConferenceId(conferenceId)
             .build();

snippets/src/main/java/voice/conferences/Get.java

@@ -23,7 +23,8 @@ public static void main(String[] args) {
     String applicationKey = Settings.getApplicationKey().orElse("MY_APPLICATION_KEY");
     String applicationSecret = Settings.getApplicationSecret().orElse("MY_APPLICATION_SECRET");
 
-    String conferenceId = "AN_EXISTING_CONFERENCE_ID";
+    // The ID of the conference to retrieve
+    String conferenceId = "CONFERENCE_ID";
 
     Configuration configuration =
         Configuration.builder()

snippets/src/main/java/voice/conferences/KickAll.java

@@ -22,7 +22,8 @@ public static void main(String[] args) {
     String applicationKey = Settings.getApplicationKey().orElse("MY_APPLICATION_KEY");
     String applicationSecret = Settings.getApplicationSecret().orElse("MY_APPLICATION_SECRET");
 
-    String conferenceId = "AN_EXISTING_CONFERENCE_ID";
+    // The ID of the conference to remove all participants from
+    String conferenceId = "CONFERENCE_ID";
 
     Configuration configuration =
         Configuration.builder()