@dwp/govuk-casa 6.8.4 → 6.9.0

package/lib/JourneyMap.js

@@ -12,8 +12,10 @@ class JourneyMap {
    * waypoints in order to help CASA identify which journey the user is
    * requesting. Thefore, if used, then it must be a valid URL slug.
    *
-   * @constructor
-   * @param {string} guid An ID that uniquely represents this journey
+   * @class
+   * @param {string} guid An ID that uniquely represents this journey.
+   * @throws {TypeError} When guid is invalid
+   * @throws {SyntaxError} When guid is misformatted
    */
   constructor(guid = null) {
     if (guid !== null) {
@@ -33,7 +35,7 @@ class JourneyMap {
   /**
    * Get guid
    *
-   * @return {string} Journey GUID
+   * @returns {string} Journey GUID
    */
   get guid() {
     return privates.get(this).guid;
@@ -43,8 +45,9 @@ class JourneyMap {
    * Define the starting point for this map - the first road that will be
    * traversed.
    *
-   * @param {JourneyRoad} road First road on the journey
-   * @return {ujMap} (chain)
+   * @param {JourneyRoad} road First road on the journey.
+   * @returns {ujMap} (chain).
+   * @throws {Error} When a non-Road is given as the starting point
    */
   startAt(road) {
     const priv = privates.get(this);
@@ -64,7 +67,8 @@ class JourneyMap {
    * The order of the returned array is insignificant. The purpose of this method
    * is to provide a means of determining if a waypoint exists on the map.
    *
-   * @return {array} List of all waypoints on the map.
+   * @returns {Array} List of all waypoints on the map.
+   * @throws {Error} When a starting waypoint is undefined.
    */
   allWaypoints() {
     const priv = privates.get(this);
@@ -80,9 +84,11 @@ class JourneyMap {
     const followedRoads = [];
 
     /**
-     * @param {JourneyRoad} road Road to follow
+     * Follow a road.
+     *
+     * @param {JourneyRoad} road Road to follow.
      * @returns {void}
-     * @throws {Error} For invalid POI type
+     * @throws {Error} For invalid POI type.
      */
     function followRoad(road) {
       if (followedRoads.indexOf(road) > -1) {
@@ -123,7 +129,7 @@ class JourneyMap {
    * at _all_ waypoints in the map.
    *
    * @param {string} waypointId Waypoint ID to find.
-   * @return {bool} Whether waypoint is present in the map or not
+   * @returns {boolean} Whether waypoint is present in the map or not.
    */
   containsWaypoint(waypointId) {
     return this.allWaypoints().indexOf(waypointId) > -1;
@@ -134,9 +140,9 @@ class JourneyMap {
    * visiting/forking/merging along the way.
    *
    * The resulting list of waypoints include those that either a) have related
-   * data in context (i.e. context[waypoint.id] exists and is not empty) and there
+   * data in context (i.e. Context[waypoint.id] exists and is not empty) and there
    * are no validation errors on that waypoint, or b) exhaust the list of possible
-   * waypoints (we reach the end of the journey)
+   * waypoints (we reach the end of the journey).
    *
    * The context associated with a waypoint is considered not-empty if it is an
    * object, and it has at least one attribute specified within that object.
@@ -148,9 +154,10 @@ class JourneyMap {
    * a JourneyContext instance, for example) so that caller can arbitrarily decide
    * whether or not to include a validation context whilst traversing.
    *
-   * @param {object} dataContext Data for each waypoint in the journey
-   * @param {object} validationContext Validation errors for each waypoint in the journey
-   * @return {array} List of waypoint IDs that have been traversed (in order)
+   * @param {object} dataContext Data for each waypoint in the journey.
+   * @param {object} validationContext Validation errors for each waypoint in the journey.
+   * @returns {Array} List of waypoint IDs that have been traversed (in order).
+   * @throws {Error} When start point is undefined.
    */
   traverse(dataContext = {}, validationContext = {}) {
     const priv = privates.get(this);
@@ -189,8 +196,9 @@ class JourneyMap {
    * will not necessarily provide the expected data when executing that logic
    * (because it may not have been gathered yet).
    *
-   * @param {object} dataContext Data for each waypoint in the journey
-   * @return {array} List of waypoint IDs that have been traversed (in order)
+   * @param {object} dataContext Data for each waypoint in the journey.
+   * @returns {Array} List of waypoint IDs that have been traversed (in order).
+   * @throws {Error} When a starting point is undefined
    */
   traverseAhead(dataContext = {}) {
     const priv = privates.get(this);

package/lib/JourneyRoad.js

@@ -3,11 +3,13 @@ const privates = new WeakMap();
 /* --------------------------------------------------------------------- Road */
 
 /**
- * Road
+ * Road.
  */
 class JourneyRoad {
   /**
-   * @constructor
+   * JourneyRoad.
+   *
+   * @class
    */
   constructor() {
     // "Points of Interest" along our journey.
@@ -18,7 +20,7 @@ class JourneyRoad {
     });
   }
 
-  /**
+  /** ..
    * Add a new waypoint(s) to the journey. A waypoint is simply a string (or a
    * function - see below) that uniquely identifies a stopping point on the
    * journey. Typically this will be the URL slug of a single page.
@@ -27,14 +29,14 @@ class JourneyRoad {
    * the function will be executed (at runtime) to determine if the waypoint
    * should be included or not (based on a given data context). In this case, pass
    * the waypoint ID and function as an array:
-   *   addWaypoints([
+   *   AddWaypoints([
    *     'normal-waypoint',
    *     ['conditional-waypoint', (context) => {...return bool...}]
    *   ]);
    *
    * You can also define waypoints as objects, which supports additional
-   * functionality. e.g.
-   *   addWaypoints([
+   * functionality. E.g.
+   *   AddWaypoints([
    *     'normal-waypoint',
    *     {
    *      id: 'conditional-waypoint',
@@ -48,8 +50,10 @@ class JourneyRoad {
    * held against that waypoint, and b) an absence of validation errors
    * associated with the waypoint.
    *
-   * @param {array|string} points Add these waypoint(s) in the order defined
-   * @return {JourneyRoad} (chain)
+   * @param {Array | string} points Add these waypoint(s) in the order defined.
+   * @returns {JourneyRoad} (chain).
+   * @throws {Error} When waypoint ordering is invalid
+   * @throws {TypeError} When any waypoint definitions are invalid
    */
   addWaypoints(points) {
     const priv = privates.get(this);
@@ -102,9 +106,9 @@ class JourneyRoad {
      * This can be overriden per-waypoint by passing in a custom `is_passable`
      * function.
      *
-     * @param {object} dc Data context
-     * @param {object} vc Validation context
-     * @returns {bool} True if the waypoint is passable
+     * @param {object} dc Data context.
+     * @param {object} vc Validation context.
+     * @returns {bool} True if the waypoint is passable.
      */
     function defaultPassableCondition(dc, vc) {
       return (dc
@@ -185,9 +189,10 @@ class JourneyRoad {
    *      ... return one of the roads based on context ...
    *  }
    *
-   * @param {array} roads Array of road choices (order is important)
-   * @param {function} test Function used to determine which of the roads to take
-   * @return {JourneyRoad} (chain)
+   * @param {Array} roads Array of road choices (order is important)
+   * @param {Function} test Function used to determine which of the roads to take
+   * @returns {JourneyRoad} (chain)
+   * @throws {Error} When a fork is created prematurely
    */
   fork(roads, test) {
     const priv = privates.get(this);
@@ -233,8 +238,9 @@ class JourneyRoad {
   /**
    * Merge this road into another road.
    *
-   * @param {JourneyRoad} road Road into which this one will merge
-   * @return {JourneyRoad} (chain)
+   * @param {JourneyRoad} road Road into which this one will merge.
+   * @returns {JourneyRoad} (chain).
+   * @throws {Error} When merge is create prematurely.
    */
   mergeWith(road) {
     const priv = privates.get(this);
@@ -273,7 +279,8 @@ class JourneyRoad {
   /**
    * Road ends here.
    *
-   * @return {JourneyRoad} (chain)
+   * @returns {JourneyRoad} (chain).
+   * @throws {Error} When the road ends prematurely.
    */
   end() {
     const priv = privates.get(this);
@@ -300,7 +307,7 @@ class JourneyRoad {
   /**
    * Return a copy of all POIs along this road.
    *
-   * @return {array} POI objects
+   * @returns {Array} POI objects.
    */
   getPOIs() {
     const priv = privates.get(this);

package/lib/Logger.js

@@ -28,7 +28,7 @@ module.exports = function Logger(suffix) {
   /**
    * Set the session ID for all messages in this debugger.
    *
-   * @param {string} sid Session ID]
+   * @param {string} sid Session ID].
    * @returns {void}
    */
   function setSessionId(sid) {
@@ -38,8 +38,8 @@ module.exports = function Logger(suffix) {
   /**
    * Wrapper for appending the session ID to all messages.
    *
-   * @param  {...string} args Message(s)
-   * @return {void}
+   * @param  {...string} args Message(s).
+   * @returns {void}
    */
   function writer(...args) {
     const logArgs = args;

package/lib/PageDirectory.js

@@ -45,7 +45,7 @@ class PageDirectory {
   /**
    * Get all page IDs in the directory.
    *
-   * @return {array} Page IDs
+   * @returns {Array} Page IDs.
    */
   getAllPageIds() {
     const priv = privates.get(this);
@@ -56,7 +56,7 @@ class PageDirectory {
    * Get page metadata for specific page
    *
    * @param  {string} pageId Page ID
-   * @return {object} Page metadata
+   * @returns {object} Page metadata
    */
   getPageMeta(pageId) {
     const priv = privates.get(this);
@@ -66,7 +66,7 @@ class PageDirectory {
   /**
    * Get all pages.
    *
-   * @return {object} All pages indexed by waypoint ID
+   * @returns {object} All pages indexed by waypoint ID.
    */
   getPages() {
     const priv = privates.get(this);

package/lib/Plan.js

@@ -6,9 +6,9 @@ const logger = require('./Logger.js')('class.Plan');
  * Will check if the source waypoint has specifically passed validation, i.e
  * there is a "null" validation entry for the route source.
  *
- * @param {object} r Route meta
- * @param {JourneyContext} context Journey Context
- * @returns {boolean} condition result
+ * @param {object} r Route meta.
+ * @param {JourneyContext} context Journey Context.
+ * @returns {boolean} Condition result.
  */
 function defaultNextFollow(r, context) {
   const { validation: v = {} } = context.toObject();
@@ -19,9 +19,9 @@ function defaultNextFollow(r, context) {
  * Will check if the target waypoint (the one we're moving back to) has
  * specifically passed validation.
  *
- * @param {object} r Route meta
- * @param {JourneyContext} context Journey context
- * @returns {boolean} condition result
+ * @param {object} r Route meta.
+ * @param {JourneyContext} context Journey context.
+ * @returns {boolean} Condition result.
  */
 function defaultPrevFollow(r, context) {
   const { validation: v = {} } = context.toObject();
@@ -53,9 +53,9 @@ function validateRouteCondition(val) {
  * be used in userland. This is the object that will be passed into follow
  * functions too as the "route" parameter.
  *
- * @param {object} dgraph Directed graph instance
- * @param {object} edge Graph edge object
- * @returns {object} Route
+ * @param {object} dgraph Directed graph instance.
+ * @param {object} edge Graph edge object.
+ * @returns {object} Route.
  */
 const makeRouteObject = (dgraph, edge) => {
   const label = dgraph.edge(edge) || {
@@ -131,9 +131,9 @@ class Plan {
    * Return all outward routes (out-edges) from the given waypoint, to the
    * optional target waypoint.
    *
-   * @param {string} src Source waypoint
-   * @param {string} tgt Target waypoint (optional)
-   * @returns {Array<object>} Route objects found
+   * @param {string} src Source waypoint.
+   * @param {string} tgt Target waypoint (optional).
+   * @returns {Array<object>} Route objects found.
    */
   getOutwardRoutes(src, tgt = null) {
     const self = priv.get(this);
@@ -144,9 +144,9 @@ class Plan {
    * Return all outward routes (out-edges) from the given waypoint, to the
    * optional target waypoint, matching the "prev" name.
    *
-   * @param {string} src Source waypoint
-   * @param {string} tgt Target waypoint (optional)
-   * @returns {Array<object>} Route objects found
+   * @param {string} src Source waypoint.
+   * @param {string} tgt Target waypoint (optional).
+   * @returns {Array<object>} Route objects found.
    */
   getPrevOutwardRoutes(src, tgt = null) {
     return this.getOutwardRoutes(src, tgt).filter((r) => r.name === 'prev');
@@ -201,11 +201,11 @@ class Plan {
    * have been true, and so to reverse the direction we also need that same test
    * to be true.
    *
-   * @param {string} src Source waypoint
-   * @param {string} tgt Target waypoint
-   * @param {function} followNext Follow test function
-   * @param {function} followPrev Follow test function
-   * @returns {Plan} self
+   * @param {string} src Source waypoint.
+   * @param {string} tgt Target waypoint.
+   * @param {Function} followNext Follow test function.
+   * @param {Function} followPrev Follow test function.
+   * @returns {Plan} Self.
    */
   setRoute(src, tgt, followNext = undefined, followPrev = undefined) {
     this.setNamedRoute(src, tgt, 'next', followNext);
@@ -228,11 +228,11 @@ class Plan {
    * Note that if you specify an origin in one waypoint, you must specify one in
    * the other waypoint too.
    *
-   * @param {string} srcId Source waypoint
-   * @param {string} tgtId Target waypoint
-   * @param {string} name Name of the route (must be unique for this waypoint pairing)
-   * @param {function} follow Test function to determine if route can be followed
-   * @return {Plan} chain
+   * @param {string} srcId Source waypoint.
+   * @param {string} tgtId Target waypoint.
+   * @param {string} name Name of the route (must be unique for this waypoint pairing).
+   * @param {Function} follow Test function to determine if route can be followed.
+   * @returns {Plan} Chain.
    */
   setNamedRoute(srcId, tgtId, name, follow) {
     const self = priv.get(this);
@@ -290,9 +290,9 @@ class Plan {
    * This is a convenience method for traversing all "next" routes, and returning
    * the IDs of all waypoints visited along the way.
    *
-   * @param {JourneyContext} context Journey Context
-   * @param {object} options Options
-   * @returns {Array<string>} List of traversed waypoints
+   * @param {JourneyContext} context Journey Context.
+   * @param {object} options Options.
+   * @returns {Array<string>} List of traversed waypoints.
    */
   traverse(context, options = {}) {
     return this.traverseNextRoutes(context, options).map((e) => e.source);
@@ -312,7 +312,7 @@ class Plan {
    * Exploration.
    *
    * The last route in the list will contain the source of the last waypoint that
-   * can be reached, i.e. the waypoint that has no further satisfiable out-edges.
+   * can be reached, i.e. The waypoint that has no further satisfiable out-edges.
    *
    * If a cyclical set of routes are encountered, traversal will stop after
    * reaching the first repeated waypoint.
@@ -326,6 +326,7 @@ class Plan {
    * @param {JourneyContext} context Journey context
    * @param {object} options Options
    * @returns {Array<object>} Routes that were traversed
+   * @throws {TypeError} When context is not a JourneyContext
    */
   traverseRoutes(context, options = {}) {
     if (!(context instanceof JourneyContext)) {
@@ -412,7 +413,7 @@ class Plan {
    * Get raw graph data structure. This can be used with other libraries to
    * generate graph visualisations, for example.
    *
-   * @returns {graphlib.Graph} Graph data structure
+   * @returns {graphlib.Graph} Graph data structure.
    */
   getGraphStructure() {
     return priv.get(this).dgraph;

package/lib/Util.js

@@ -8,8 +8,8 @@ const logger = require('./Logger')('util');
  * Generate an object path string that we can use to traverse an object using
  * `objectPathValue()`.
  *
- * @param {...string} paths Path components
- * @return {string} Constructed path
+ * @param {...string} paths Path components.
+ * @returns {string} Constructed path.
  */
 function objectPathString(...paths) {
   let pathString = paths.length ? paths.join('.') : '';
@@ -31,7 +31,7 @@ function objectPathString(...paths) {
  *      }
  *    }
  *  }
- * ... a call to `objectPathValue(obj, 'rooms.lounge.objects[0]')` would
+ * ... A call to `objectPathValue(obj, 'rooms.lounge.objects[0]')` would
  * return "TV".
  *
  * If using square-braces to access object keys, you also need to wrap the key
@@ -43,7 +43,7 @@ function objectPathString(...paths) {
  *
  * @param {object} obj Object to traverse
  * @param {string} paths Path component(s) to use
- * @return {mixed} The value of the object, or `undefined` if not found
+ * @returns {any} The value of the object, or `undefined` if not found
  */
 function objectPathValue(obj, ...paths) {
   let pathString = objectPathString(...paths);
@@ -67,7 +67,7 @@ function objectPathValue(obj, ...paths) {
  * no quotations.
  *
  * @param {string} pathString Path to normalize.
- * @return {string} Normalized path
+ * @returns {string} Normalized path.
  */
 function normalizeHtmlObjectPath(pathString) {
   return pathString.replace(/\[["']([^\]]+?)['"]\]/g, '[$1]').replace(/[[\]]/g, '.').replace(/\.+/g, '.').replace(/\.+/g, '][')
@@ -84,9 +84,9 @@ function normalizeHtmlObjectPath(pathString) {
  • Options:
  *  RegExp regexRemove = characters matching this regex are removed before test
  *
- * @param  {mixed} e Value to check
+ * @param  {any} e Value to check
  * @param  {object} options Options (see above)
- * @return {bool} True if the object is empty
+ * @returns {boolean} True if the object is empty
  */
 function isEmpty(e, options) {
   let val = e;
@@ -114,7 +114,7 @@ function isEmpty(e, options) {
  *
  * @param {Array} journeys Array of UserJourney.Map instances
  * @param {string} url URL to parse
- * @return {UserJourney.Map|null} The associated journey
+ * @returns {UserJourney.Map|null} The associated journey
  */
 function getJourneyFromUrl(journeys, url) {
   // Single-journeys are not reflected in URLs
@@ -138,8 +138,8 @@ function getPageIdFromJourneyUrl(journey, url) {
 /**
  * Extract the originId, and current waypoint being visited from the given url.
  *
- * @param {string} url URL
- * @returns {object} The origin ID, and current waypoint
+ * @param {string} url URL.
+ * @returns {object} The origin ID, and current waypoint.
  */
 function parseOriginWaypointInUrl(url) {
   try {
@@ -176,14 +176,14 @@ function isObjectWithKeys(target, keys = []) {
 }
 
 /**
-   * Discover the root folder of the specified npm module.
-   *
-   * @param {string} module Name of npm module to go and find
-   * @param {array} paths Paths to search on for module folder
-   * @returns {string} The absolute path to the named module, if found
-   * @throws Error When the module cannot be found
-   * @throws SyntaxError When the module name contains invalid characters
-   */
+ * Discover the root folder of the specified npm module.
+ *
+ * @param {string} module Name of npm module to go and find.
+ * @param {Array} paths Paths to search on for module folder.
+ * @returns {string} The absolute path to the named module, if found.
+ * @throws Error When the module cannot be found.
+ * @throws SyntaxError When the module name contains invalid characters.
+ */
 function resolveModulePath(module = '', paths = []) {
   // Strip rogue chars from module name; only valid npm package names are
   // expected (https://docs.npmjs.com/files/package.json#name)
@@ -205,8 +205,8 @@ module.exports = {
    * Convert a given URL into an ID that we can use to uniquely identify a
    * specific page. This function will not verify the page ID is valid.
    *
-   * @param {string} url Url to parse
-   * @return {string} Page ID
+   * @param {string} url Url to parse.
+   * @returns {string} Page ID.
    */
   getPageIdFromUrl,
   getPageIdFromJourneyUrl,

package/lib/Validation.js

@@ -8,7 +8,7 @@
  *   arrayObjectFieldValidation,
  *   objectFieldValidation,
  *   simpleFieldValidation
- * } = require('@dwp/govuk-casa');
+ * } = require('@dwp/govuk-casa');.
  */
 
 const util = require('util');

package/lib/bootstrap/end-session.js

@@ -9,8 +9,8 @@
  * Certain attributes will be persisted:
  *   language
  *
- * @param {http.incomingmessage} req HTTP request on which to end the session
- * @return {Promise} Promise that is resolved once session is fully ended
+ * @param {object} req HTTP request on which to end the session
+ * @returns {Promise} Promise that is resolved once session is fully ended
  */
 module.exports = function endSession(req = {}) {
   return new Promise((resolve, reject) => {

package/lib/bootstrap/load-definitions.js

@@ -8,9 +8,9 @@ const mwSessionTimeout = require('../../middleware/session/timeout.js');
 /**
  * Validate pages and generate a PageDirectory from them.
  *
- * @param {object} pages Page definitions, indexed by page id (url slug)
- * @throws {TypeError} for invalid pages type
- * @returns {PageDirectory} Pages
+ * @param {object} pages Page definitions, indexed by page id (url slug).
+ * @throws {TypeError} For invalid pages type.
+ * @returns {PageDirectory} Pages.
  */
 function buildPageDirectory(pages = {}) {
   if (Object.prototype.toString.call(pages) !== '[object Object]') {
@@ -22,9 +22,9 @@ function buildPageDirectory(pages = {}) {
 /**
  * Validate journey plan.
  *
- * @param {Plan} plan User journey plan
- * @throws {TypeError} for invalid argument type
- * @throws {Error} for invalid arguments
+ * @param {Plan} plan User journey plan.
+ * @throws {TypeError} For invalid argument type.
+ * @throws {Error} For invalid arguments.
  * @returns {void}
  */
 function validatePlan(plan = []) {
@@ -44,9 +44,9 @@ function validatePlan(plan = []) {
  * function once all custom routes and configuration has been put in place -
  * it should be the last call made just before starting the HTTP server.
  *
- * @param  {object} pages Page definitions, indexed by page id (url slug)
- * @param  {Plan} plan Journey plan definition
- * @return {void}
+ * @param  {object} pages Page definitions, indexed by page id (url slug).
+ * @param  {Plan} plan Journey plan definition.
+ * @returns {void}
  */
 
 module.exports = (app, router, config) => (pages, plan) => {

package/lib/gather-modifiers/trimPostalAddressObject.js

@@ -3,7 +3,7 @@
  *
  * @param {object} value Address object to mung
  * @param {string} prop file property name
- * @return {string} munged property
+ * @returns {string} munged property
  */
 function transferAndTrim(value, prop) {
   if (typeof value === 'object' && prop in value && typeof value[prop] === 'string') {
@@ -13,7 +13,7 @@ function transferAndTrim(value, prop) {
 }
 
 /**
- * Reformats a postcode into the standard form, as long as this results in a valid postcode
+ * Reformats a postcode into the standard form, as long as this results in a valid postcode.
  *
  * It removes all the spaces from the postcode, converts it to uppercase and then
  * puts a single space back in to separate the last three characters.
@@ -29,7 +29,7 @@ function transferAndTrim(value, prop) {
  * text, but instead are asked to correct their original
  *
  * @param {object} value Address object to test
- * @return {object} GatherModifiered version of the Address object
+ * @returns {object} GatherModifiered version of the Address object
  */
 function reformatPostcodeIfValid(value) {
   // convert to upper case
@@ -57,8 +57,8 @@ function reformatPostcodeIfValid(value) {
  *
  * Trims white space from the address items and reformats the post code.
  *
- * @param {object} value Address object to test
- * @return {object} GatherModifiered version of the Address object
+ * @param {object} value Address object to test.
+ * @returns {object} GatherModifiered version of the Address object.
  */
 function trimPostalAddressObject(value) {
   // copy only the expected address properties

package/lib/gather-modifiers/trimWhitespace.js

@@ -1,10 +1,10 @@
 /**
- * trimWhitespace is the most basic and useful munger.
- * It removes leading and tailing white space from the value
+ * TrimWhitespace is the most basic and useful munger.
+ * It removes leading and tailing white space from the value.
  *
  *
- * @param  {mixed} value Value to mung
- * @return {string} munged value
+ * @param  {any} value Value to munge
+ * @returns {string} munged value
  */
 function trimWhitespace(value) {
   if (typeof value.fieldValue === 'string') {

package/lib/utils/makeEditLink.js

@@ -6,21 +6,24 @@ const { validateMountUrl, validateWaypoint } = require('./validate.js');
  * Create a URL that can be used to go and edit data at a particular waypoint.
  *
  * If no waypoint or mountUrl is defined, then just the query part of the URL
- * will be generated (without the `?` delimiter), e.g. `&edit`
+ * will be generated (without the `?` delimiter), e.g. `&edit`.
  *
  * Parameters:
  * string waypoint = Waypoint to edit (including origin waypoint if applicable)
  * string origin = The URL to which the user is returned after editing
- * string mountUrl = The mount URL prefix
+ * string mountUrl = The mount URL prefix.
  *
  * Examples:
  * makeEditLink({ waypoint: 'the-waypoint' })
- * Generates: /the-waypoint?edit
+ * Generates: /the-waypoint?edit.
  *
  * makeEditLink({ waypoint: 'my-origin/the-waypoint', origin: '/some-url' })
  * Generates: /my-origin/the-waypoint?edit&editorigin=%2Fsome-url
  *
  * @param {object} args See parameters above
+ * @param {string} args.waypoint Waypoint ID
+ * @param {string} args.origin Original URL to send user back to after editing
+ * @param {string} args.mountUrl Mount URL
  * @returns {string} URL
  */
 module.exports = ({ waypoint = '', origin = null, mountUrl = '/' }) => {

package/lib/utils/sanitise.js

@@ -7,7 +7,7 @@
  *  an-origin/a-waypoint/with-forward-slash
  *
  * @param {string} waypoint Waypoint, including optional Plan origin
- * @return {string} Waypoint
+ * @returns {string} Waypoint
  */
 function sanitiseWaypoint(waypoint = '') {
   if (typeof waypoint !== 'string') {

package/lib/validation/ArrayObjectField.js

@@ -3,10 +3,11 @@
  * function, but the data against which it is tested is expected to be an array
  * of objects that match the structure of the `obj` defined here.
  *
- * @param {object} obj Object of fields that will be tested
- * @param {array} validators Validation rules that must be satisfied
- * @param {function|null} condition Condition to meet before validators are run
- * @return {object} Validation object suitable for processing
+ * @param {object} obj Object of fields that will be tested.
+ * @param {Array} validators Validation rules that must be satisfied.
+ * @param {Function | null} condition Condition to meet before validators are run.
+ * @returns {object} Validation object suitable for processing.
+ * @throws {TypeError} When arguments are invalid.
  */
 module.exports = (obj = {}, validators = [], condition) => {
   if (Object.prototype.toString.call(obj) !== '[object Object]') {