chore: document and add type for parent option to captureError() (#2979)

This also includes some docs chores: fixes escaping and tweaks 
capitalization of the `type-string-array` and `type-undefined` labels.

Closes: #2977

Author: trentm

CHANGELOG.asciidoc

@@ -119,6 +119,9 @@ paths are considered for body capture. ({pull}2873[#2873])
   (because there is no point). This is a performance improvement for
   Knex usage in the default configuration. ({pull}2879[#2879])
 
+* Document and add types for `parent` option to
+  <<apm-capture-error,`apm.captureError()`>>. ({issues}2977[#2977])
+
 
 [[release-notes-3.38.0]]
 ==== 3.38.0 2022/08/11

docs/agent-api.asciidoc

@@ -335,6 +335,8 @@ See the <<apm-add-labels,`apm.addLabels()`>> method for details about the format
 
 ** `skipOutcome` +{type-boolean}+ Whether to skip setting the outcome value for the current span to `failure`.  See <<span-outcome,Span outcome>> for more information. *Default:* `false`.
 
+** `parent` <<transaction-api,Transaction>> | <<span-api,Span>> | `null` - A Transaction or Span instance to make the parent of this error. If not given (or `undefined`), then the current span or transaction will be used. If `null` is given, then no span or transaction will be used. [small]#(Added in v3.33.0.)#
+
 * `callback` - Will be called after the error has been sent to the APM Server.
 It will receive an `Error` instance if the agent failed to send the error,
 and the id of the captured error.

docs/index.asciidoc

@@ -2,14 +2,14 @@ include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[]
 include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
 :type-string: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type[<string>]
-:type-string-array: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type[<string[]>]
+:type-string-array: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type[<string[\]>]
 :type-array: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array[<Array>]
 :type-boolean: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type[<boolean>]
 :type-object: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object[<Object>]
 :type-number: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type[<number>]
 :type-function: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function[<Function>]
 :type-error: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error[<Error>]
-:type-undefined: https://developer.mozilla.org/en-US/docs/Glossary/Undefined[<Undefined>]
+:type-undefined: https://developer.mozilla.org/en-US/docs/Glossary/Undefined[<undefined>]
 :type-incomingmessage: https://nodejs.org/api/http.html#http_class_http_incomingmessage[<http.IncomingMessage>]
 :type-serverresponse: https://nodejs.org/api/http.html#http_class_http_serverresponse[<http.ServerResponse>]
 

index.d.ts

@@ -320,6 +320,12 @@ declare namespace apm {
     message?: string;
     captureAttributes?: boolean;
     skipOutcome?: boolean;
+    /**
+     * A Transaction or Span instance to make the parent of this error. If not
+     * given (undefined), then the current span or transaction will be used. If
+     * `null` is given, then no span or transaction will be used.
+     */
+    parent?: Transaction | Span | null;
   }
 
   interface Labels {

test/types/index.ts

@@ -87,6 +87,9 @@ apm.captureError({ message: 'hello %s', params: ['world'] }, { tags: { foo: 'bar
 apm.captureError(new Error('foo'), () => {})
 apm.captureError('foo', () => {})
 apm.captureError({ message: 'hello %s', params: ['world'] }, () => {})
+apm.captureError(new Error('an error on the transaction'), { parent: trans })
+apm.captureError(new Error('an error on the span'), { parent: span })
+apm.captureError(new Error('an error with explicitly no parent'), { parent: null })
 
 apm.startTransaction()
 apm.startTransaction('foo')