Source: example/utility-module--one.js

'use strict';

/** Support some reasonable feature
 * @module exampleUtilityOne
 */

import * as SomeUtil from '../../utility/some-util';

//
// Definitions
//

/** A complex set of options
 * @typedef {string} Options
 * @property {boolean} optOne - Whether to count sheep
 * @property {number} optTwo - The number of sheep to count
 * @property {boolean} optThree - Whether to allow insomnia
 */

/** Some object or syntax standard to the language, but not easily expressed
 * @external Cookie
 * @see [MDN > Web APIs > Document > Document.cookie (search `newCookie`)](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie#Syntax)
 */

//
// Helpers
//

/** A private helper function
 * @private
 * @param {string} paramOne - Thing one
 * @param {array|string} paramTwo - Thing two (could be string, could be array)
 * @param {module:exampleUtilityOne~Options} [options] - Complicated thing
 * @return {external:Cookie} A cookie
 */
function _privateHelperFunction(paramOne, paramTwo, {optOne = false, optTwo = undefined, optThree = false} = {}) {
  // Amazing code goes here
  const prefix = SomeUtil.someMethod();

  // Shortcut to get to the chocalate chippity point
  const cookie = prefix + 'yummy';

  return cookie;
}

//
// Utility
//

/** Manage a thing in a way for a purpose
 *
 * Maybe talk more about what we're doing. Maybe use a little
 * [Markdown](https://daringfireball.net/projects/markdown/syntax).
 * Maybe _have a little fun_. But remember, kids:
 *
 * **A new line in the doc require two new lines here.**
 */
class ExampleUtilityOne {
  /** A public property
   * @memberof module:exampleUtilityOne~ExampleUtilityOne
   * @type {string}
   */
  foo = 'fooFighter';

  /** A fake private property
   *
   * This property is accessible externally, and manually hidden from docs.
   * @private
   * @memberof module:exampleUtilityOne~ExampleUtilityOne
   * @type {RegExp}
   * @see https://github.com/tc39/proposal-class-fields/blob/master/PRIVATE_SYNTAX_FAQ.md
   */
  _bar = 'barMan';

  /** A real private property
   *
   * This property is not accessible externally, and automatically hidden from docs.
   * @memberof module:exampleUtilityOne~ExampleUtilityOne
   * @type {RegExp}
   * @see https://github.com/tc39/proposal-class-fields/blob/master/PRIVATE_SYNTAX_FAQ.md
   */
  #baz = 'bazTard';

  /* eslint-disable class-methods-use-this */
  /** Add a cookie in the legacy format
   * @param {string} paramOne - Thing one
   * @param {array|string} paramTwo - Thing two (could be string, could be array)
   * @param {module:exampleUtilityOne~Options} [paramThree] - Complicated thing
   */
  set(paramOne, paramTwo, paramThree = {}) {
    document.cookie = _privateHelperFunction(paramOne, paramTwo, paramThree);
  }
  /* eslint-enable */

  /* eslint-disable class-methods-use-this */
  /** Expire the named cookie from the browser
   * @param {string} name - Name of the cookie to expire i.e. delete
   */
  delete(name) {
    document.cookie = name + '=; Max-Age=0';
  }
  /* eslint-enable */
}

/** Instance of the class of this module
 *
 * > Notice that because `ExampleUtilityOne` is **not** exported,
 * it is reerenced with a tilde `~`, not a dot `.`
 * @type {module:exampleUtilityOne~ExampleUtilityOne}
 */
export const exampleUtilityOne = new ExampleUtilityOne();