chore: compute sample comments and readme updates (GoogleCloudPlatform#1377)

README.md and comments updates based on iX input.

Author: rsamborski

compute/cloud-client/instances/README.md

@@ -82,6 +82,18 @@ Instances for YOUR_PROJECT_ID (us-central1-a)
  - my-new-instance-name
 ```
 
+### List all instances
+
+```
+$ php src/list_all_instances.php $YOUR_PROJECT_ID
+All instances for YOUR_PROJECT_ID
+Zone - zones/us-central1-a
+ - my-new-instance-name
+Zone - zones/us-central1-b
+ - my-new-instance-name-2
+ - my-new-instance-name-3
+```
+
 ### Delete an instance
 
 ```

compute/cloud-client/instances/src/create_instance.php

@@ -33,18 +33,18 @@
 use Google\Cloud\Compute\V1\ZoneOperationsClient;
 
 /**
- * Creates an instance.
+ * Create an instance in the specified project and zone.
  * Example:
  * ```
  * create_instance($projectId, $zone, $instanceName);
  * ```
  *
- * @param string $projectId Your Google Cloud project ID.
- * @param string $zone The zone to create the instance in (e.g. "us-central1-a").
- * @param string $instanceName The unique name for this Compute instance.
- * @param string $machineType Instance machine type.
+ * @param string $projectId Project ID of the Cloud project to create the instance in.
+ * @param string $zone Zone to create the instance in (like "us-central1-a").
+ * @param string $instanceName Unique name for this Compute Engine instance.
+ * @param string $machineType Machine type of the instance being created.
  * @param string $sourceImage Boot disk image name or family.
- * @param string $networkName The Compute instance ID.
+ * @param string $networkName Network interface to associate with the instance.
  *
  * @throws \Google\ApiCore\ApiException if the remote call fails.
  */
@@ -56,33 +56,33 @@ function create_instance(
     string $sourceImage = 'projects/debian-cloud/global/images/family/debian-10',
     string $networkName = 'global/networks/default'
 ) {
-    // Set the machine type using the specified zone
+    // Set the machine type using the specified zone.
     $machineTypeFullName = sprintf('zones/%s/machineTypes/%s', $zone, $machineType);
 
-    // Set the boot disk
+    // Describe the source image of the boot disk to attach to the instance.
     $diskInitializeParams = (new AttachedDiskInitializeParams())
         ->setSourceImage($sourceImage);
     $disk = (new AttachedDisk())
         ->setBoot(true)
         ->setInitializeParams($diskInitializeParams);
 
-    // Set the network
+    // Use the network interface provided in the $networkName argument.
     $network = (new NetworkInterface())
         ->setName($networkName);
 
-    // Create the Instance message
+    // Create the Instance object.
     $instance = (new Instance())
         ->setName($instanceName)
         ->setDisks([$disk])
         ->setMachineType($machineTypeFullName)
         ->setNetworkInterfaces([$network]);
 
-    // Insert the new Compute Engine instance using the InstancesClient
+    // Insert the new Compute Engine instance using InstancesClient.
     $instancesClient = new InstancesClient();
     $operation = $instancesClient->insert($instance, $projectId, $zone);
 
+    // Wait for the create operation to complete.
     if ($operation->getStatus() === Operation\Status::RUNNING) {
-        // Wait until operation completes
         $operationClient = new ZoneOperationsClient();
         $operationClient->wait($operation->getName(), $projectId, $zone);
     }

compute/cloud-client/instances/src/delete_instance.php

@@ -32,15 +32,15 @@
 # [END compute_instances_operation_check]
 
 /**
- * Creates an instance.
+ * Delete an instance.
  * Example:
  * ```
  * delete_instance($projectId, $zone, $instanceName);
  * ```
  *
  * @param string $projectId Your Google Cloud project ID.
- * @param string $zone The zone to delete the instance in (e.g. "us-central1-a").
- * @param string $instanceName The unique name for the Compute instance to delete.
+ * @param string $zone Zone where the instance you want to delete is (like "us-central1-a").
+ * @param string $instanceName Unique name for the Compute instance to delete.
  *
  * @throws \Google\ApiCore\ApiException if the remote call fails.
  */
@@ -49,16 +49,16 @@ function delete_instance(
     string $zone,
     string $instanceName
 ) {
-    // Delete the Compute Engine instance using the InstancesClient
+    // Delete the Compute Engine instance using InstancesClient.
     $instancesClient = new InstancesClient();
     $operation = $instancesClient->delete($instanceName, $projectId, $zone);
 
     # [START compute_instances_operation_check]
     if ($operation->getStatus() === Operation\Status::RUNNING) {
-        // Wait until operation completes
+        // Wait for the operation to complete.
         $operationClient = new ZoneOperationsClient();
 
-        // Default timeout of 60s is not always enough for operation to finish,
+        // Default timeout of 60 s is not always enough for operation to finish,
         // to avoid an exception we set timeout to 180000 ms = 180 s = 3 minutes
         $optionalArgs = ['timeoutMillis' => 180000];
         $operationClient->wait($operation->getName(), $projectId, $zone, $optionalArgs);

compute/cloud-client/instances/src/list_all_instances.php

@@ -27,7 +27,7 @@
 use Google\Cloud\Compute\V1\InstancesClient;
 
 /**
- * List all instances for particular $projectId
+ * List all instances for a particular Cloud project.
  * Example:
  * ```
  * list_all_instances($projectId);
@@ -39,7 +39,7 @@
  */
 function list_all_instances(string $projectId)
 {
-    // List the new Compute Engine instance using the InstancesClient
+    // List Compute Engine instances using InstancesClient.
     $instancesClient = new InstancesClient();
     $allInstances = $instancesClient->aggregatedList($projectId);
 

compute/cloud-client/instances/src/list_instances.php

@@ -27,20 +27,20 @@
 use Google\Cloud\Compute\V1\InstancesClient;
 
 /**
- * List instances for particular $projectId and $zone
+ * List all instances for a particular Cloud project and zone.
  * Example:
  * ```
  * list_instances($projectId, $zone);
  * ```
  *
  * @param string $projectId Your Google Cloud project ID.
- * @param string $zone The zone to list the instance in (e.g. "us-central1-a").
+ * @param string $zone Zone to list instances for (like "us-central1-a").
  *
  * @throws \Google\ApiCore\ApiException if the remote call fails.
  */
 function list_instances(string $projectId, string $zone)
 {
-    // List the new Compute Engine instance using the InstancesClient
+    // List Compute Engine instances using InstancesClient.
     $instancesClient = new InstancesClient();
     $instancesList = $instancesClient->list($projectId, $zone);