chore(various): Wordsmith comments and docstrings (getsentry#4390)

lobsterkatie · web-flow · commit e32a6e5799b1 · 2022-01-12T00:48:29.000-08:00
A whole bunch of proofreading edits I stashed away while working on other things. No code changes.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -120,6 +120,7 @@ jobs:
         if: github.ref == 'refs/heads/master' || github.event_name == 'pull_request'
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
+          # see https://github.com/getsentry/size-limit-action#usage
           skip_step: build
           workflow_name: 'build'
 
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -29,7 +29,8 @@
       "program": "${workspaceFolder}/node_modules/.bin/jest",
       "args": [
         "--watch",
-        // this makes the output less noisy (and at some point in the past seemed necessary to fix... something)
+        // this runs one test at a time, rather than running them in parallel (necessary for debugging so that you know
+        // you're hitting a single test's breakpoints, in order)
         "--runInBand",
         // TODO: when we unify jest config, we may need to change this
         "--config",
diff --git a/packages/browser/rollup.config.js b/packages/browser/rollup.config.js
@@ -21,7 +21,7 @@ const terserInstance = terser({
     // captureExceptions and captureMessage are public API methods and they don't need to be listed here
     // as mangler doesn't touch user-facing thing, however sentryWrapped is not, and it would be mangled into a minified version.
     // We need those full names to correctly detect our internal frames for stripping.
-    // I listed all of them here just for the clarity sake, as they are all used in the frames manipulation process.
+    // I listed all of them here just for the clarity's sake, as they are all used in the frame-manipulation process.
     reserved: ['captureException', 'captureMessage', 'sentryWrapped'],
     properties: {
       regex: /^_[^_]/,
diff --git a/packages/browser/src/eventbuilder.ts b/packages/browser/src/eventbuilder.ts
@@ -15,7 +15,7 @@ import { eventFromPlainObject, eventFromStacktrace, prepareFramesForEvent } from
 import { computeStackTrace } from './tracekit';
 
 /**
- * Builds and Event from a Exception
+ * Creates an {@link Event} from all inputs to `captureException` and non-primitive inputs to `captureMessage`.
  * @hidden
  */
 export function eventFromException(options: Options, exception: unknown, hint?: EventHint): PromiseLike<Event> {
@@ -104,9 +104,9 @@ export function eventFromUnknownInput(
     return event;
   }
   if (isPlainObject(exception) || isEvent(exception)) {
-    // If it is plain Object or Event, serialize it manually and extract options
-    // This will allow us to group events based on top-level keys
-    // which is much better than creating new group when any key/value change
+    // If it's a plain object or an instance of `Event` (the built-in JS kind, not this SDK's `Event` type), serialize
+    // it manually. This will allow us to group events based on top-level keys which is much better than creating a new
+    // group on any key/value change.
     const objectException = exception as Record<string, unknown>;
     event = eventFromPlainObject(objectException, syntheticException, options.rejection);
     addExceptionMechanism(event, {
diff --git a/packages/browser/src/transports/fetch.ts b/packages/browser/src/transports/fetch.ts
@@ -37,9 +37,9 @@ export class FetchTransport extends BaseTransport {
     const options: RequestInit = {
       body: sentryRequest.body,
       method: 'POST',
-      // Despite all stars in the sky saying that Edge supports old draft syntax, aka 'never', 'always', 'origin' and 'default
-      // https://caniuse.com/#feat=referrer-policy
-      // It doesn't. And it throw exception instead of ignoring this parameter...
+      // Despite all stars in the sky saying that Edge supports old draft syntax, aka 'never', 'always', 'origin' and 'default'
+      // (see https://caniuse.com/#feat=referrer-policy),
+      // it doesn't. And it throws an exception instead of ignoring this parameter...
       // REF: https://github.com/getsentry/raven-js/issues/1233
       referrerPolicy: (supportsReferrerPolicy() ? 'origin' : '') as ReferrerPolicy,
     };
diff --git a/packages/core/src/basebackend.ts b/packages/core/src/basebackend.ts
@@ -24,11 +24,11 @@ import { NoopTransport } from './transports/noop';
  * @hidden
  */
 export interface Backend {
-  /** Creates a {@link Event} from an exception. */
+  /** Creates an {@link Event} from all inputs to `captureException` and non-primitive inputs to `captureMessage`. */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   eventFromException(exception: any, hint?: EventHint): PromiseLike<Event>;
 
-  /** Creates a {@link Event} from a plain message. */
+  /** Creates an {@link Event} from primitive inputs to `captureMessage`. */
   eventFromMessage(message: string, level?: SeverityLevel, hint?: EventHint): PromiseLike<Event>;
 
   /** Submits the event to Sentry */
diff --git a/packages/eslint-config-sdk/src/index.js b/packages/eslint-config-sdk/src/index.js
@@ -179,7 +179,7 @@ module.exports = {
       },
     },
     {
-      // Configuration for config files like webpack/rollback
+      // Configuration for config files like webpack/rollup
       files: ['*.config.js'],
       parserOptions: {
         sourceType: 'module',
diff --git a/packages/nextjs/test/run-integration-tests.sh b/packages/nextjs/test/run-integration-tests.sh
@@ -58,7 +58,7 @@ for NEXTJS_VERSION in 10 11 12; do
   fi
   yarn --no-lockfile --silent >/dev/null 2>&1
   # if applicable, use local versions of `@sentry/cli` and/or `@sentry/webpack-plugin` (these commands no-op unless
-  # LINKED_CLI_REPO and/or LINKED_PLUGIN_REPO is set)
+  # LINKED_CLI_REPO and/or LINKED_PLUGIN_REPO are set)
   linkcli && linkplugin
   mv -f package.json.bak package.json 2>/dev/null || true
 
diff --git a/packages/serverless/src/utils.ts b/packages/serverless/src/utils.ts
@@ -5,7 +5,7 @@ import * as domain from 'domain';
 /**
  * Event processor that will override SDK details to point to the serverless SDK instead of Node,
  * as well as set correct mechanism type, which should be set to `handled: false`.
- * We do it like this, so that we don't introduce any side-effects in this module, which makes it tree-shakeable.
+ * We do it like this so that we don't introduce any side-effects in this module, which makes it tree-shakeable.
  * @param event Event
  * @param integration Name of the serverless integration ('AWSLambda', 'GCPFunction', etc)
  */
diff --git a/packages/tracing/src/hubextensions.ts b/packages/tracing/src/hubextensions.ts
@@ -34,8 +34,8 @@ function traceHeaders(this: Hub): { [key: string]: string } {
  * Called every time a transaction is created. Only transactions which emerge with a `sampled` value of `true` will be
  * sent to Sentry.
  *
- * @param hub: The hub off of which to read config options
  * @param transaction: The transaction needing a sampling decision
+ * @param options: The current client's options, so we can access `tracesSampleRate` and/or `tracesSampler`
  * @param samplingContext: Default and user-provided data which may be used to help make the decision
  *
  * @returns The given transaction with its `sampled` value set
diff --git a/packages/tracing/src/idletransaction.ts b/packages/tracing/src/idletransaction.ts
@@ -81,7 +81,7 @@ export class IdleTransaction extends Transaction {
      * @default 1000
      */
     private readonly _idleTimeout: number = DEFAULT_IDLE_TIMEOUT,
-    // If an idle transaction should be put itself on and off the scope automatically.
+    // Whether or not the transaction should put itself on the scope when it starts and pop itself off when it ends
     private readonly _onScope: boolean = false,
   ) {
     super(transactionContext, _idleHub);
@@ -143,7 +143,7 @@ export class IdleTransaction extends Transaction {
       logger.log('[Tracing] No active IdleTransaction');
     }
 
-    // this._onScope is true if the transaction was previously on the scope.
+    // if `this._onScope` is `true`, the transaction put itself on the scope when it started
     if (this._onScope) {
       clearActiveTransaction(this._idleHub);
     }
@@ -272,7 +272,7 @@ export class IdleTransaction extends Transaction {
 }
 
 /**
- * Reset active transaction on scope
+ * Reset transaction on scope to `undefined`
  */
 function clearActiveTransaction(hub?: Hub): void {
   if (hub) {
diff --git a/packages/types/src/debugMeta.ts b/packages/types/src/debugMeta.ts
@@ -1,5 +1,5 @@
 /**
- * Holds meta information to customize the behavior of sentry's event processing.
+ * Holds meta information to customize the behavior of Sentry's server-side event processing.
  **/
 export interface DebugMeta {
   images?: Array<DebugImage>;
diff --git a/packages/types/src/scope.ts b/packages/types/src/scope.ts
@@ -24,8 +24,7 @@ export interface ScopeContext {
 }
 
 /**
- * Holds additional event information. {@link Scope.applyToEvent} will be
- * called by the client before an event will be sent.
+ * Holds additional event information. {@link Scope.applyToEvent} will be called by the client before an event is sent.
  */
 export interface Scope {
   /** Add new event processor that will be called after {@link applyToEvent}. */
diff --git a/packages/utils/src/is.ts b/packages/utils/src/is.ts
@@ -73,7 +73,7 @@ export function isString(wat: unknown): boolean {
 }
 
 /**
- * Checks whether given value's is a primitive (undefined, null, number, boolean, string, bigint, symbol)
+ * Checks whether given value is a primitive (undefined, null, number, boolean, string, bigint, symbol)
  * {@link isPrimitive}.
  *
  * @param wat A value to be checked.
diff --git a/packages/utils/src/object.ts b/packages/utils/src/object.ts
@@ -310,7 +310,7 @@ function normalizeValue<T>(value: T, key?: any): T | string {
  */
 // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
 export function walk(key: string, value: any, depth: number = +Infinity, memo: MemoFunc = memoBuilder()): any {
-  // If we reach the maximum depth, serialize whatever has left
+  // If we reach the maximum depth, serialize whatever is left
   if (depth === 0) {
     return serializeValue(value);
   }
@@ -322,13 +322,14 @@ export function walk(key: string, value: any, depth: number = +Infinity, memo: M
   }
   /* eslint-enable @typescript-eslint/no-unsafe-member-access */
 
-  // If normalized value is a primitive, there are no branches left to walk, so we can just bail out, as theres no point in going down that branch any further
+  // If normalized value is a primitive, there are no branches left to walk, so bail out
   const normalized = normalizeValue(value, key);
   if (isPrimitive(normalized)) {
     return normalized;
   }
 
-  // Create source that we will use for next itterations, either objectified error object (Error type with extracted keys:value pairs) or the input itself
+  // Create source that we will use for the next iteration. It will either be an objectified error object (`Error` type
+  // with extracted key:value pairs) or the input itself.
   const source = getWalkSource(value);
 
   // Create an accumulator that will act as a parent for all future itterations of that branch
diff --git a/packages/utils/src/supports.ts b/packages/utils/src/supports.ts
@@ -139,9 +139,9 @@ export function supportsReportingObserver(): boolean {
  * @returns Answer to the given question.
  */
 export function supportsReferrerPolicy(): boolean {
-  // Despite all stars in the sky saying that Edge supports old draft syntax, aka 'never', 'always', 'origin' and 'default
-  // https://caniuse.com/#feat=referrer-policy
-  // It doesn't. And it throw exception instead of ignoring this parameter...
+  // Despite all stars in the sky saying that Edge supports old draft syntax, aka 'never', 'always', 'origin' and 'default'
+  // (see https://caniuse.com/#feat=referrer-policy),
+  // it doesn't. And it throws an exception instead of ignoring this parameter...
   // REF: https://github.com/getsentry/raven-js/issues/1233
 
   if (!supportsFetch()) {
diff --git a/packages/utils/src/time.ts b/packages/utils/src/time.ts
@@ -21,7 +21,7 @@ const dateTimestampSource: TimestampSource = {
 
 /**
  * A partial definition of the [Performance Web API]{@link https://developer.mozilla.org/en-US/docs/Web/API/Performance}
- * for accessing a high resolution monotonic clock.
+ * for accessing a high-resolution monotonic clock.
  */
 interface Performance {
   /**

Original file line number	Diff line number	Diff line change
`@@ -179,7 +179,7 @@ module.exports = {`
`179`	`179`	`},`
`180`	`180`	`},`
`181`	`181`	`{`
`182`		`- // Configuration for config files like webpack/rollback`
	`182`	`+ // Configuration for config files like webpack/rollup`
`183`	`183`	`files: ['*.config.js'],`
`184`	`184`	`parserOptions: {`
`185`	`185`	`sourceType: 'module',`
Original file line number	Diff line number	Diff line change
`@@ -34,8 +34,8 @@ function traceHeaders(this: Hub): { [key: string]: string } {`
`34`	`34`	* Called every time a transaction is created. Only transactions which emerge with a `sampled` value of `true` will be
`35`	`35`	`* sent to Sentry.`
`36`	`36`	`*`
`37`		`- * @param hub: The hub off of which to read config options`
`38`	`37`	`* @param transaction: The transaction needing a sampling decision`
	`38`	+ * @param options: The current client's options, so we can access `tracesSampleRate` and/or `tracesSampler`
`39`	`39`	`* @param samplingContext: Default and user-provided data which may be used to help make the decision`
`40`	`40`	`*`
`41`	`41`	* @returns The given transaction with its `sampled` value set