docs: update comments

Author: jpoehnelt

adminSDK/directory/index.js

@@ -21,19 +21,24 @@ import process from 'node:process';
 import {authenticate} from '@google-cloud/local-auth';
 import {google} from 'googleapis';
 
+// The scope for the Admin SDK Directory API.
 const SCOPES = ['https://www.googleapis.com/auth/admin.directory.user'];
+// The path to the credentials file.
 const CREDENTIALS_PATH = path.join(process.cwd(), 'credentials.json');
 
 /**
  * Lists the first 10 users in the domain.
  */
 async function listUsers() {
+  // Authenticate with Google and get an authorized client.
   const auth = await authenticate({
     scopes: SCOPES,
     keyfilePath: CREDENTIALS_PATH,
   });
 
+  // Create a new Admin SDK Directory API client.
   const service = google.admin({version: 'directory_v1', auth});
+  // Get the list of users.
   const result = await service.users.list({
     customer: 'my_customer',
     maxResults: 10,
@@ -46,6 +51,7 @@ async function listUsers() {
     return;
   }
 
+  // Print the primary email and full name of each user.
   console.log('Users:');
   users.forEach((user) => {
     console.log(`${user.primaryEmail} (${user.name?.fullName})`);

adminSDK/reports/index.js

@@ -21,18 +21,24 @@ import process from 'node:process';
 import {authenticate} from '@google-cloud/local-auth';
 import {google} from 'googleapis';
 
+// The scope for the Admin SDK Reports API.
 const SCOPES = ['https://www.googleapis.com/auth/admin.reports.audit.readonly'];
+// The path to the credentials file.
 const CREDENTIALS_PATH = path.join(process.cwd(), 'credentials.json');
 
 /**
  * Lists the last 10 login events for the domain.
  */
 async function listLoginEvents() {
+  // Authenticate with Google and get an authorized client.
   const auth = await authenticate({
     scopes: SCOPES,
     keyfilePath: CREDENTIALS_PATH,
   });
+
+  // Create a new Admin SDK Reports API client.
   const service = google.admin({version: 'reports_v1', auth});
+  // Get the list of login events.
   const result = await service.activities.list({
     userKey: 'all',
     applicationName: 'login',
@@ -44,6 +50,7 @@ async function listLoginEvents() {
     return;
   }
 
+  // Print the time, email, and event name of each login event.
   console.log('Logins:');
   activities.forEach((activity) => {
     console.log(

adminSDK/reseller/index.js

@@ -21,19 +21,24 @@ import process from 'node:process';
 import {authenticate} from '@google-cloud/local-auth';
 import {google} from 'googleapis';
 
+// The scope for the Admin SDK Reseller API.
 const SCOPES = ['https://www.googleapis.com/auth/apps.order'];
+// The path to the credentials file.
 const CREDENTIALS_PATH = path.join(process.cwd(), 'credentials.json');
 
 /**
  * Lists the first 10 subscriptions you manage.
  */
 async function listSubscriptions() {
+  // Authenticate with Google and get an authorized client.
   const auth = await authenticate({
     scopes: SCOPES,
     keyfilePath: CREDENTIALS_PATH,
   });
 
+  // Create a new Admin SDK Reseller API client.
   const service = google.reseller({version: 'v1', auth});
+  // Get the list of subscriptions.
   const result = await service.subscriptions.list({
     maxResults: 10,
   });
@@ -43,6 +48,7 @@ async function listSubscriptions() {
     return;
   }
 
+  // Print the customer ID, SKU ID, and plan name of each subscription.
   console.log('Subscriptions:');
   subscriptions.forEach(({customerId, skuId, plan}) => {
     console.log(`${customerId} (${skuId}, ${plan?.planName})`);

apps-script/execute/index.js

@@ -20,49 +20,47 @@ import {GoogleAuth} from 'google-auth-library';
 import {google} from 'googleapis';
 
 /**
- * Call an Apps Script function to list the folders in the user's root Drive
- * folder.
+ * Calls an Apps Script function to list the folders in the user's root Drive folder.
  */
 async function callAppsScript() {
+  // The ID of the Apps Script project to call.
   const scriptId = '1xGOh6wCm7hlIVSVPKm0y_dL-YqetspS5DEVmMzaxd_6AAvI-_u8DSgBT';
 
-  // Get credentials and build service
-  // TODO (developer) - Use appropriate auth mechanism for your app
+  // Authenticate with Google and get an authorized client.
+  // TODO (developer): Use an appropriate auth mechanism for your app.
   const auth = new GoogleAuth({
     scopes: 'https://www.googleapis.com/auth/drive',
   });
+
+  // Create a new Apps Script API client.
   const script = google.script({version: 'v1', auth});
-  // Make the API request. The request object is included here as 'resource'.
+
   const resp = await script.scripts.run({
     auth,
     requestBody: {
+      // The name of the function to call in the Apps Script project.
       function: 'getFoldersUnderRoot',
     },
     scriptId,
   });
 
   if (resp.data.error?.details?.[0]) {
     // The API executed, but the script returned an error.
-
-    // Extract the first (and only) set of error details. The values of this
-    // object are the script's 'errorMessage' and 'errorType', and an array of
-    // stack trace elements.
+    // Extract the error details.
     const error = resp.data.error.details[0];
-
     console.log(`Script error message: ${error.errorMessage}`);
     console.log('Script error stacktrace:');
 
     if (error.scriptStackTraceElements) {
-      // There may not be a stacktrace if the script didn't start executing.
+      // Log the stack trace.
       for (let i = 0; i < error.scriptStackTraceElements.length; i++) {
         const trace = error.scriptStackTraceElements[i];
         console.log('\t%s: %s', trace.function, trace.lineNumber);
       }
     }
   } else {
-    // The structure of the result depends on the Apps Script function's return value.
-    // Here, the function returns an object with string keys and values, which is
-    // treated as a Node.js object (folderSet).
+    // The script executed successfully.
+    // The structure of the response depends on the Apps Script function's return value.
     const folderSet = resp.data.response ?? {};
     if (Object.keys(folderSet).length === 0) {
       console.log('No folders returned!');

calendar/quickstart/index.js

@@ -21,19 +21,24 @@ import process from 'node:process';
 import {authenticate} from '@google-cloud/local-auth';
 import {google} from 'googleapis';
 
+// The scope for reading calendar events.
 const SCOPES = ['https://www.googleapis.com/auth/calendar.readonly'];
+// The path to the credentials file.
 const CREDENTIALS_PATH = path.join(process.cwd(), 'credentials.json');
 
 /**
  * Lists the next 10 events on the user's primary calendar.
  */
 async function listEvents() {
+  // Authenticate with Google and get an authorized client.
   const auth = await authenticate({
     scopes: SCOPES,
     keyfilePath: CREDENTIALS_PATH,
   });
 
+  // Create a new Calendar API client.
   const calendar = google.calendar({version: 'v3', auth});
+  // Get the list of events.
   const result = await calendar.events.list({
     calendarId: 'primary',
     timeMin: new Date().toISOString(),
@@ -48,6 +53,7 @@ async function listEvents() {
   }
   console.log('Upcoming 10 events:');
 
+  // Print the start time and summary of each event.
   for (const event of events) {
     const start = event.start?.dateTime ?? event.start?.date;
     console.log(`${start} - ${event.summary}`);

chat/quickstart/index.js

@@ -21,35 +21,38 @@ import process from 'node:process';
 import {ChatServiceClient} from '@google-apps/chat';
 import {authenticate} from '@google-cloud/local-auth';
 
+// The scope for reading Chat spaces.
 const SCOPES = ['https://www.googleapis.com/auth/chat.spaces.readonly'];
+// The path to the credentials file.
 const CREDENTIALS_PATH = path.join(process.cwd(), 'credentials.json');
 
 /**
- * Lists spaces with user credential.
+ * Lists the spaces that the user is a member of.
  */
 async function listSpaces() {
+  // Authenticate with Google and get an authorized client.
   const authClient = await authenticate({
     scopes: SCOPES,
     keyfilePath: CREDENTIALS_PATH,
   });
 
-  // Create a client
+  // Create a new Chat API client.
   const chatClient = new ChatServiceClient({
     authClient,
     scopes: SCOPES,
   });
 
-  // Initialize request argument(s)
+  // The request to list spaces.
   const request = {
-    // Filter spaces by space type (SPACE or GROUP_CHAT or DIRECT_MESSAGE)
+    // Filter spaces by type. In this case, we are only interested in "SPACE" type.
     filter: 'space_type = "SPACE"',
   };
 
-  // Make the request
+  // Make the API request.
   const pageResult = chatClient.listSpacesAsync(request);
 
-  // Handle the response. Iterating over pageResult will yield results
-  // and resolve additional pages automatically.
+  // Process the response.
+  // The `pageResult` is an async iterable that will yield each space.
   for await (const response of pageResult) {
     console.log(response);
   }

classroom/quickstart/index.js

@@ -21,18 +21,24 @@ import process from 'node:process';
 import {authenticate} from '@google-cloud/local-auth';
 import {google} from 'googleapis';
 
+// The scope for reading Classroom courses.
 const SCOPES = ['https://www.googleapis.com/auth/classroom.courses.readonly'];
+// The path to the credentials file.
 const CREDENTIALS_PATH = path.join(process.cwd(), 'credentials.json');
 
 /**
  * Lists the first 10 courses the user has access to.
  */
 async function listCourses() {
+  // Authenticate with Google and get an authorized client.
   const auth = await authenticate({
     scopes: SCOPES,
     keyfilePath: CREDENTIALS_PATH,
   });
+
+  // Create a new Classroom API client.
   const classroom = google.classroom({version: 'v1', auth});
+  // Get the list of courses.
   const result = await classroom.courses.list({
     pageSize: 10,
   });
@@ -42,6 +48,7 @@ async function listCourses() {
     return;
   }
   console.log('Courses:');
+  // Print the name and ID of each course.
   courses.forEach((course) => {
     console.log(`${course.name} (${course.id})`);
   });

docs/quickstart/index.js

@@ -21,22 +21,29 @@ import process from 'node:process';
 import {authenticate} from '@google-cloud/local-auth';
 import {google} from 'googleapis';
 
+// The scope for reading Google Docs.
 const SCOPES = ['https://www.googleapis.com/auth/documents.readonly'];
+// The path to the credentials file.
 const CREDENTIALS_PATH = path.join(process.cwd(), 'credentials.json');
 
 /**
  * Prints the title of a sample doc:
  * https://docs.google.com/document/d/195j9eDD3ccgjQRttHhJPymLJUCOUjs-jmwTrekvdjFE/edit
  */
 async function printDocTitle() {
+  // Authenticate with Google and get an authorized client.
   const auth = await authenticate({
     scopes: SCOPES,
     keyfilePath: CREDENTIALS_PATH,
   });
+
+  // Create a new Docs API client.
   const docs = google.docs({version: 'v1', auth});
+  // Get the document.
   const result = await docs.documents.get({
     documentId: '195j9eDD3ccgjQRttHhJPymLJUCOUjs-jmwTrekvdjFE',
   });
+  // Print the title of the document.
   console.log(`The title of the document is: ${result.data.title}`);
 }
 

drive/activity-v2/index.js

@@ -21,29 +21,38 @@ import process from 'node:process';
 import {authenticate} from '@google-cloud/local-auth';
 import {google} from 'googleapis';
 
+// The scope for reading Drive activity.
 const SCOPES = ['https://www.googleapis.com/auth/drive.activity.readonly'];
+// The path to the credentials file.
 const CREDENTIALS_PATH = path.join(process.cwd(), 'credentials.json');
 
 /**
  * Lists the recent activity in your Google Drive.
  */
 async function listDriveActivity() {
+  // Authenticate with Google and get an authorized client.
   const auth = await authenticate({
     scopes: SCOPES,
     keyfilePath: CREDENTIALS_PATH,
   });
+
+  // Create a new Drive Activity API client.
   const service = google.driveactivity({version: 'v2', auth});
+
+  // The parameters for the activity query.
   const params = {
     pageSize: 10,
   };
+
+  // Query for recent activity.
   const result = await service.activity.query({requestBody: params});
   const activities = result.data.activities;
   if (!activities || activities.length === 0) {
     console.log('No activity.');
     return;
   }
   console.log('Recent activity:');
-
+  // Print the recent activity.
   console.log(JSON.stringify(activities, null, 2));
 }
 

drive/quickstart/index.js

@@ -21,30 +21,36 @@ import process from 'node:process';
 import {authenticate} from '@google-cloud/local-auth';
 import {google} from 'googleapis';
 
+// The scope for reading file metadata.
 const SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly'];
+// The path to the credentials file.
 const CREDENTIALS_PATH = path.join(process.cwd(), 'credentials.json');
 
 /**
  * Lists the names and IDs of up to 10 files.
  */
 async function listFiles() {
+  // Authenticate with Google and get an authorized client.
   const auth = await authenticate({
     scopes: SCOPES,
     keyfilePath: CREDENTIALS_PATH,
   });
 
+  // Create a new Drive API client.
   const drive = google.drive({version: 'v3', auth});
+  // Get the list of files.
   const result = await drive.files.list({
     pageSize: 10,
     fields: 'nextPageToken, files(id, name)',
   });
   const files = result.data.files;
-  if (!files) {
+  if (!files || files.length === 0) {
     console.log('No files found.');
     return;
   }
 
   console.log('Files:');
+  // Print the name and ID of each file.
   files.forEach((file) => {
     console.log(`${file.name} (${file.id})`);
   });