docs: cleaned up formatting of api.js to properly inject example snip…

…pets when rendering on API docs site (#2524)

api.js

@@ -304,8 +304,7 @@ API.prototype.addCustomAttribute = function addCustomAttribute(key, value) {
  * See documentation for newrelic.addCustomAttribute for more information on
  * setting custom attributes.
  *
- * An example of setting a custom attribute object:
- *
+ * @example
  *    newrelic.addCustomAttributes({test: 'value', test2: 'value2'});
  *
  * @param {object} [atts] Attribute object
@@ -332,7 +331,7 @@ API.prototype.addCustomAttributes = function addCustomAttributes(atts) {
  *
  * See documentation for newrelic.addCustomSpanAttribute for more information.
  *
- * An example of setting a custom span attribute:
+ * @example
  *
  *    newrelic.addCustomSpanAttribute({test: 'value', test2: 'value2'})
  *
@@ -401,21 +400,20 @@ API.prototype.addCustomSpanAttribute = function addCustomSpanAttribute(key, valu
  * `Error` or one of its subtypes, but the API will handle strings and objects
  * that have an attached `.message` or `.stack` property.
  *
- * An example of using this function is
- *
- *    try {
- *      performSomeTask();
- *    } catch (err) {
- *      newrelic.noticeError(
- *        err,
- *        {extraInformation: "error already handled in the application"},
- *        true
- *      );
- *    }
- *
  * NOTE: Errors that are recorded using this method do _not_ obey the
  * `ignore_status_codes` configuration.
  *
+ * @example
+ * try {
+ *  performSomeTask();
+ * } catch (err) {
+ *  newrelic.noticeError(
+ *    err,
+ *    {extraInformation: "error already handled in the application"},
+ *    true
+ *  );
+ * }
+ *
  * @param {Error} error
  *  The error to be traced.
  * @param {object} [customAttributes]
@@ -474,13 +472,12 @@ API.prototype.noticeError = function noticeError(error, customAttributes, expect
  * If application log forwarding is disabled in the agent
  * configuration, this function does nothing.
  *
- * An example of using this function is
- *
- *    newrelic.recordLogEvent({
- *       message: 'cannot find file',
- *       level: 'ERROR',
- *       error: new SystemError('missing.txt')
- *    })
+ * @example
+ * newrelic.recordLogEvent({
+ *  message: 'cannot find file',
+ *  level: 'ERROR',
+ *  error: new SystemError('missing.txt')
+ * })
  *
  * @param {object} logEvent The log event object to send. Any
  *   attributes besides `message`, `level`, `timestamp`, and `error` are
@@ -554,20 +551,21 @@ API.prototype.recordLogEvent = function recordLogEvent(logEvent = {}) {
  * GUIDs, or timestamps), the rule will generate too many metrics and
  * potentially get your application blocked by New Relic.
  *
- * An example of a good rule with replacements:
- *
- *   newrelic.addNamingRule('^/storefront/(v[1-5])/(item|category|tag)',
- *                          'CommerceAPI/$1/$2')
  *
- * An example of a bad rule with replacements:
+ * @example
+ * // An example of a good rule with replacements:
+ * newrelic.addNamingRule('^/storefront/(v[1-5])/(item|category|tag)',
+ *                        'CommerceAPI/$1/$2')
  *
- *   newrelic.addNamingRule('^/item/([0-9a-f]+)', 'Item/$1')
+ * @example
+ * // An example of a bad rule with replacements:
+ * newrelic.addNamingRule('^/item/([0-9a-f]+)', 'Item/$1')
  *
- * Keep in mind that the original URL and any query parameters will be sent
- * along with the request, so slow transactions will still be identifiable.
+ * // Keep in mind that the original URL and any query parameters will be sent
+ * // along with the request, so slow transactions will still be identifiable.
  *
- * Naming rules can not be removed once added. They can also be added via the
- * agent's configuration. See configuration documentation for details.
+ * // Naming rules can not be removed once added. They can also be added via the
+ * // agent's configuration. See configuration documentation for details.
  *
  * @param {RegExp} pattern The pattern to rename (with capture groups).
  * @param {string} name    The name to use for the transaction.
@@ -591,8 +589,7 @@ API.prototype.addNamingRule = function addNamingRule(pattern, name) {
  * distorting an app's apdex or mean response time. Pattern may be a (standard
  * JavaScript) RegExp or a string.
  *
- * Example:
- *
+ * @example
  *   newrelic.addIgnoringRule('^/socket\\.io/')
  *
  * @param {RegExp} pattern The pattern to ignore.
@@ -929,9 +926,9 @@ API.prototype.startSegment = function startSegment(name, record, handler, callba
  *    will be ended when {@link TransactionHandle#end} is called in the user's code.
  *
  * @example
- * var newrelic = require('newrelic')
+ * const newrelic = require('newrelic')
  * newrelic.startWebTransaction('/some/url/path', function() {
- *   var transaction = newrelic.getTransaction()
+ *   const transaction = newrelic.getTransaction()
  *   setTimeout(function() {
  *     // do some work
  *     transaction.end()
@@ -1017,9 +1014,9 @@ API.prototype.startBackgroundTransaction = startBackgroundTransaction
  *    will be ended when {@link TransactionHandle#end} is called in the user's code.
  *
  * @example
- * var newrelic = require('newrelic')
+ * const newrelic = require('newrelic')
  * newrelic.startBackgroundTransaction('Red October', 'Subs', function() {
- *   var transaction = newrelic.getTransaction()
+ *   const transaction = newrelic.getTransaction()
  *   setTimeout(function() {
  *     // do some work
  *     transaction.end()
@@ -1478,14 +1475,15 @@ API.prototype.instrumentMessages = function instrumentMessages(moduleName, onReq
  * Applies an instrumentation to an already loaded CommonJs module.
  *
  * Note: This function will not work for ESM packages.
+ * @example
  *
- *    // oh no, express was loaded before newrelic
- *    const express   = require('express')
- *    const newrelic  = require('newrelic')
+ * // oh no, express was loaded before newrelic
+ * const express   = require('express')
+ * const newrelic  = require('newrelic')
  *
- *    // phew, we can use instrumentLoadedModule to make
- *    // sure express is still instrumented
- *    newrelic.instrumentLoadedModule('express', express)
+ * // phew, we can use instrumentLoadedModule to make
+ * // sure express is still instrumented
+ * newrelic.instrumentLoadedModule('express', express)
  *
  * @param {string} moduleName
  *  The module's name/identifier.  Will be normalized
@@ -1906,11 +1904,14 @@ API.prototype.ignoreApdex = function ignoreApdex() {
 /**
  * Run a function with the passed in LLM context as the active context and return its return value.
  *
- * An example of setting a custom attribute:
- *
- *    newrelic.withLlmCustomAttributes({'llm.someAttribute': 'someValue'}, () => {
- *      return;
- *    })
+ * @example
+ * const OpenAI = require('openai')
+ * const client = new OpenAI()
+ * newrelic.withLlmCustomAttributes({'llm.someAttribute': 'someValue'}, async () => {
+ *    const response = await client.chat.completions.create({ messages: [
+ *      { role: 'user', content: 'Tell me about Node.js.'}
+ *    ]})
+ * })
  * @param {Object} context LLM custom attributes context
  * @param {Function} callback The function to execute in context.
  */