Document queryParams + rename example module (#3170)

This file does more than transform, and `examples` seems is a bit more consistent with e.g. `trace.js` and `route.js`.

core/base-service/base.js

@@ -14,6 +14,7 @@ const {
   InvalidParameter,
   Deprecated,
 } = require('./errors')
+const { validateExample, transformExample } = require('./examples')
 const {
   makeFullUrl,
   assertValidRoute,
@@ -23,7 +24,6 @@ const {
 } = require('./route')
 const { assertValidServiceDefinition } = require('./service-definitions')
 const trace = require('./trace')
-const { validateExample, transformExample } = require('./transform-example')
 const validate = require('./validate')
 
 const defaultBadgeDataSchema = Joi.object({
@@ -106,7 +106,22 @@ module.exports = class BaseService {
    *  - capture: Array of names for the capture groups in the regular
    *             expression. The handler will be passed an object containing
    *             the matches.
-   *  - queryParamSchema: Joi schema for valid query params.
+   *  - queryParamSchema: (Optional) A Joi schema (`Joi.object({ ... }).required()`)
+   *                      for the query param object. If you know a parameter
+   *                      will never receive a numeric string, you can use
+   *                      `Joi.string()`. Because of quirks in Scoutcamp and Joi,
+   *                      alphanumeric strings should be declared using
+   *                      `Joi.alternatives().try(Joi.string(), Joi.number())`,
+   *                      otherwise a value like `?success_color=999` will fail.
+   *                      A parameter requiring a numeric string can use
+   *                      `Joi.number()`. A parameter that receives only non-numeric
+   *                      strings can use `Joi.string()`. A parameter that never
+   *                      receives numeric can use `Joi.string()`. A boolean
+   *                      parameter should use `Joi.equal('')` and will receive an
+   *                      empty string on e.g. `?compact_message` and undefined
+   *                      when the parameter is absent. (Note that in,
+   *                      `examples.queryParams` boolean query params should be given
+   *                      `null` values.)
    */
   static get route() {
     throw new Error(`Route not defined for ${this.name}`)
@@ -142,7 +157,8 @@ module.exports = class BaseService {
    * namedParams: An object containing the values of named parameters to
    *   substitute into the compiled route pattern.
    * queryParams: An object containing query parameters to include in the
-   *   example URLs.
+   *   example URLs. For alphanumeric query parameters, specify a string value.
+   *   For boolean query parameters, specify `null`.
    * pattern: The route pattern to compile. Defaults to `this.route.pattern`.
    * staticPreview: A rendered badge of the sort returned by `handle()` or
    *   `render()`: an object containing `message` and optional `label` and

core/base-service/base.spec.js

@@ -397,7 +397,7 @@ describe('BaseService', function() {
           queryParams: ['queryParamA', 'legacyQueryParamA'],
         },
       })
-      // The in-depth tests for examples reside in transform-example.spec.js
+      // The in-depth tests for examples reside in examples.spec.js
       expect(examples).to.have.lengthOf(1)
     })
   })

core/base-service/examples.spec.js

@@ -2,7 +2,7 @@
 
 const { expect } = require('chai')
 const { test, given } = require('sazerac')
-const { validateExample, transformExample } = require('./transform-example')
+const { validateExample, transformExample } = require('./examples')
 
 describe('validateExample function', function() {
   it('passes valid examples', function() {